brynq-sdk-meta4 1.0.1__py3-none-any.whl

brynq_sdk_meta4/__init__.py

@@ -0,0 +1 @@
+from .meta4 import Meta4

brynq_sdk_meta4/cost_centers.py

@@ -0,0 +1,74 @@
+import pandas as pd
+from .schemas.cost_center import CostCenterSchema
+
+class CostCenters:
+    """
+    Handles all cost center related operations in Meta4
+    """
+    def __init__(self, meta4):
+        self.meta4 = meta4
+        schema_fields = CostCenterSchema.model_fields
+        column_names = [field.alias or name for name, field in schema_fields.items()]
+        self.batch_df = pd.DataFrame(columns=column_names)
+
+    def create(self, df: pd.DataFrame) -> str:
+        """
+        Export cost center data to CSV with validation.
+
+        Args:
+            df (pd.DataFrame): DataFrame containing cost center data to validate and export
+
+        Returns:
+            str: Path to the generated CSV file
+
+        Raises:
+            Exception: If validation or export fails
+        """
+        try:
+            # Set movement_type to ALTA for all records
+            df['movement_type'] = '-36'
+            valid_df = self.meta4.validate(df=df,schema=CostCenterSchema)
+            self.batch_df = pd.concat([self.batch_df, valid_df], ignore_index=True)
+            return {"success": True, "message": "Cost centers created successfully"}
+        except Exception as e:
+            raise Exception(f"Failed to export cost centers: {e}")
+
+    def update(self, df: pd.DataFrame) -> str:
+
+        try:
+            # Set movement_type to MODIFICACION for all records
+            df['movement_type'] = '-36'
+            valid_df = self.meta4.validate(df=df,schema=CostCenterSchema)
+            self.batch_df = pd.concat([self.batch_df, valid_df], ignore_index=True)
+            return {"success": True, "message": "Cost centers updated successfully"}
+        except Exception as e:
+            raise Exception(f"Failed to update cost centers: {e}")
+
+    def delete(self, df: pd.DataFrame) -> str:
+
+        try:
+            # Set movement_type to BAJA for all records
+            df['movement_type'] = '-37'
+            valid_df = self.meta4.validate(df=df,schema=CostCenterSchema)
+            self.batch_df = pd.concat([self.batch_df, valid_df], ignore_index=True)
+            return {"success": True, "message": "Cost centers deleted successfully"}
+        except Exception as e:
+            raise Exception(f"Failed to delete cost centers: {e}")
+
+    def export(self) -> str:
+        """
+        Export cost center data to CSV with validation.
+        """
+        return self.meta4.export(df=self.batch_df, filename="cost_center_import.csv")
+
+    def get_batch_df(self) -> pd.DataFrame:
+        """
+        Get the current batch DataFrame containing all validated cost center records.
+        """
+        return self.batch_df
+
+    def clear_batch_df(self):
+        """
+        Clear the batch DataFrame.
+        """
+        self.batch_df = pd.DataFrame()

brynq_sdk_meta4/employees.py

@@ -0,0 +1,121 @@
+import pandas as pd
+from .schemas.employee import EmployeeSchema
+import os
+
+class Employees:
+    """
+    Handles all employee related operations in Meta4
+    """
+    def __init__(self, meta4):
+        self.meta4 = meta4
+        # Initialize batch_df with EmployeeSchema columns
+        schema_fields = EmployeeSchema.model_fields
+        column_names = [field.alias or name for name, field in schema_fields.items()]
+        self.batch_df = pd.DataFrame(columns=column_names)
+
+    def create(self, df: pd.DataFrame) -> str:
+        """
+        Create new employees (ALTA movement type).
+
+        Args:
+            df (pd.DataFrame): DataFrame containing employee data for creation
+
+        Returns:
+            str: Path to the generated CSV file
+
+        Raises:
+            Exception: If validation or export fails
+        """
+        try:
+            # Set movement_type to ALTA for all records
+            df['movement_type'] = '1'
+            validated_df = self.meta4.validate(df=df, schema=EmployeeSchema)
+
+            # Append validated DataFrame to batch_df
+            self.batch_df = pd.concat([self.batch_df, validated_df], ignore_index=True)
+
+            return {"success": True, "message": "Employees created successfully"}
+        except Exception as e:
+            raise Exception(f"Failed to create employees: {e}")
+
+    def update(self, df: pd.DataFrame) -> str:
+        """
+        Update existing employees (MODIFICACION movement type).
+
+        Args:
+            df (pd.DataFrame): DataFrame containing employee data for update
+
+        Returns:
+            str: Path to the generated CSV file
+
+        Raises:
+            Exception: If validation or export fails
+        """
+        try:
+            # Set movement_type to MODIFICACION for all records
+            df['movement_type'] = '3'
+            validated_df = self.meta4.validate(df=df, schema=EmployeeSchema)
+
+            # Append validated DataFrame to batch_df
+            self.batch_df = pd.concat([self.batch_df, validated_df], ignore_index=True)
+
+            return {"success": True, "message": "Employees updated successfully"}
+        except Exception as e:
+            raise Exception(f"Failed to update employees: {e}")
+
+    def delete(self, df: pd.DataFrame) -> str:
+        """
+        Delete/terminate employees (BAJA movement type).
+
+        Args:
+            df (pd.DataFrame): DataFrame containing employee data for termination
+
+        Returns:
+            str: Path to the generated CSV file
+
+        Raises:
+            Exception: If validation or export fails
+        """
+        try:
+            # Set movement_type to BAJA for all records
+            df['movement_type'] = '2'
+            validated_df = self.meta4.validate(df=df, schema=EmployeeSchema)
+
+            # Append validated DataFrame to batch_df
+            self.batch_df = pd.concat([self.batch_df, validated_df], ignore_index=True)
+
+            return {"success": True, "message": "Employees deleted successfully"}
+        except Exception as e:
+            raise Exception(f"Failed to delete employees: {e}")
+
+    def export(self) -> str:
+        """
+        Export employee data to CSV with validation (generic export).
+
+        Args:
+            df (pd.DataFrame): DataFrame containing employee data to validate and export
+
+        Returns:
+            str: Path to the generated CSV file
+
+        Raises:
+            Exception: If validation or export fails
+        """
+        return self.meta4.export(df=self.batch_df, filename="employee_import.csv")
+
+    def get_batch_df(self) -> pd.DataFrame:
+        """
+        Get the current batch DataFrame containing all validated employee records.
+
+        Returns:
+            pd.DataFrame: The batch DataFrame with all validated records
+        """
+        return self.batch_df
+
+    def clear_batch_df(self):
+        """
+        Clear the batch DataFrame.
+        """
+        schema_fields = EmployeeSchema.model_fields
+        column_names = [field.alias or name for name, field in schema_fields.items()]
+        self.batch_df = pd.DataFrame(columns=column_names)

brynq_sdk_meta4/jobs.py

@@ -0,0 +1,120 @@
+import pandas as pd
+from .schemas.job import JobSchema
+
+class Jobs:
+    """
+    Handles all job related operations in Meta4
+    """
+    def __init__(self, meta4):
+        self.meta4 = meta4
+        # Initialize batch_df with JobSchema columns
+        schema_fields = JobSchema.model_fields
+        column_names = [field.alias or name for name, field in schema_fields.items()]
+        self.batch_df = pd.DataFrame(columns=column_names)
+
+    def create(self, df: pd.DataFrame) -> str:
+        """
+        Create new jobs (CREATE movement type -28).
+
+        Args:
+            df (pd.DataFrame): DataFrame containing job data for creation
+
+        Returns:
+            str: Success message
+
+        Raises:
+            Exception: If validation fails
+        """
+        try:
+            # Set movement_type to CREATE for all records
+            df['movement_type'] = '-28'
+            validated_df = self.meta4.validate(df=df, schema=JobSchema)
+
+            # Append validated DataFrame to batch_df
+            self.batch_df = pd.concat([self.batch_df, validated_df], ignore_index=True)
+
+            return {"success": True, "message": "Jobs created successfully"}
+        except Exception as e:
+            raise Exception(f"Failed to create jobs: {e}")
+
+    def update(self, df: pd.DataFrame) -> str:
+        """
+        Update existing jobs (UPDATE movement type -29).
+
+        Args:
+            df (pd.DataFrame): DataFrame containing job data for update
+
+        Returns:
+            str: Success message
+
+        Raises:
+            Exception: If validation fails
+        """
+        try:
+            # Set movement_type to UPDATE for all records
+            df['movement_type'] = '-29'
+            validated_df = self.meta4.validate(df=df, schema=JobSchema)
+
+            # Append validated DataFrame to batch_df
+            self.batch_df = pd.concat([self.batch_df, validated_df], ignore_index=True)
+
+            return {"success": True, "message": "Jobs updated successfully"}
+        except Exception as e:
+            raise Exception(f"Failed to update jobs: {e}")
+
+    def delete(self, df: pd.DataFrame) -> str:
+        """
+        Delete jobs (DELETE movement type -29).
+
+        Args:
+            df (pd.DataFrame): DataFrame containing job data for deletion
+
+        Returns:
+            str: Success message
+
+        Raises:
+            Exception: If validation fails
+        """
+        try:
+            # Set movement_type to DELETE for all records
+            df['movement_type'] = '-29'
+            validated_df = self.meta4.validate(df=df, schema=JobSchema)
+
+            # Append validated DataFrame to batch_df
+            self.batch_df = pd.concat([self.batch_df, validated_df], ignore_index=True)
+
+            return {"success": True, "message": "Jobs deleted successfully"}
+        except Exception as e:
+            raise Exception(f"Failed to delete jobs: {e}")
+
+    def export(self) -> str:
+        """
+        Export job data to CSV with validation (generic export).
+
+        Args:
+            df (pd.DataFrame): DataFrame containing job data to validate and export
+
+        Returns:
+            str: Path to the generated CSV file
+
+        Raises:
+            Exception: If validation or export fails
+        """
+        return self.meta4.export(df=self.batch_df, filename="job_import.csv")
+
+    def get_batch_df(self) -> pd.DataFrame:
+        """
+        Get the current batch DataFrame containing all validated job records.
+
+        Returns:
+            pd.DataFrame: The batch DataFrame with all validated records
+        """
+        return self.batch_df
+
+    def clear_batch_df(self):
+        """
+        Clear the batch DataFrame.
+        """
+        schema_fields = JobSchema.model_fields
+        column_names = [field.alias or name for name, field in schema_fields.items()]
+        self.batch_df = pd.DataFrame(columns=column_names)

brynq_sdk_meta4/meta4.py

@@ -0,0 +1,165 @@
+import os
+import csv
+from typing import List, Optional, Literal
+import pandas as pd
+from brynq_sdk_ftp import SFTP
+from brynq_sdk_brynq import BrynQ
+from brynq_sdk_functions import Functions
+import pydantic
+from .employees import Employees
+from .cost_centers import CostCenters
+from .jobs import Jobs
+
+class Meta4(BrynQ):
+    """
+    Meta4 HR system client for BrynQ integrations.
+    Focuses on schema validation and CSV export functionality.
+    """
+
+    def __init__(self, system_type: Optional[Literal['source', 'target']] = None, output_path:str="outputs", debug=False):
+        """
+        Initialize Meta4 client.
+        """
+        super().__init__()
+        self.debug = debug
+
+        self.output_path = output_path
+        # SFTP client as a composition attribute
+        self.sftp = SFTP()
+        credentials = self.interfaces.credentials.get(system="meta-4", system_type=system_type)
+        credentials = credentials.get('data', credentials)
+
+        self.sftp._set_credentials(credentials)
+
+        # Initialize entity classes
+        self.employees = Employees(self)
+        self.cost_centers = CostCenters(self)
+        self.jobs = Jobs(self)
+
+    def validate(self, df: pd.DataFrame, schema: pydantic.BaseModel) -> pd.DataFrame:
+        """
+        Validate data against schema and return validated DataFrame.
+        """
+        try:
+                data_list = df.to_dict('records')
+
+                valid_data = []
+                invalid_data = []
+                for data_item in data_list:
+                    try:
+                        validated_item = schema(**data_item)
+                        valid_data.append(validated_item.model_dump(by_alias=True, mode="json"))
+                    except Exception as validation_error:
+                        invalid_data.append({
+                            'data': data_item,
+                            'error': str(validation_error)
+                        })
+
+                # Print invalid data count
+                if invalid_data:
+                    print(f" {len(invalid_data)} lines of {schema.__name__} data validation failed:")
+
+                # Convert to DataFrame
+                df = pd.DataFrame(valid_data)
+                return df
+        except Exception as e:
+            raise Exception(f"Failed to validate data: {e}")
+
+    def export(
+      self,
+        df: pd.DataFrame,
+        filename: str
+    ) -> dict:
+        """
+        Validate data against schema and export to CSV file.
+
+        Args:
+            schema_class: Pydantic schema class (e.g., EmployeeSchema, CostCenterSchema, JobSchema)
+            df: DataFrame containing data to validate and export
+
+        Returns:
+            dict: Dictionary containing filepath, valid count, invalid count, and invalid data list
+
+        Raises:
+            ValidationError: If data validation fails
+            Exception: If file writing fails
+        """
+        try:
+            os.makedirs(self.output_path, exist_ok=True)
+
+
+            # Export to CSV
+            df.to_csv(
+                f"{self.output_path}/{filename}",
+                index=False,
+                encoding="utf-8-sig",
+                sep=";",
+                quotechar='"',
+                quoting=csv.QUOTE_MINIMAL
+            )
+            return {
+                'filepath': f"{self.output_path}/{filename}",
+            }
+
+        except Exception as e:
+            raise Exception(f"Failed to export data for {filename}: {e}")
+
+    def upload(self, upload_path: str="/") -> List[str]:
+        """
+        Upload all CSV files from the output directory to the specified remote path.
+
+        This method scans the output directory for CSV files and uploads each one
+        to the remote server via SFTP. Files are uploaded to different directories
+        based on their filename:
+        - employee_import.csv -> ENTRADA folder
+        - Other files -> SALIDA folder
+
+        Args:
+            upload_path (str): Remote directory path where CSV files will be uploaded.
+                             Must be a valid directory path on the remote server.
+
+        Returns:
+            List[str]: List of successfully uploaded remote file paths.
+                      Each path includes the remote directory and filename.
+        Raises:
+            Exception: For any other upload-related errors.
+        """
+        try:
+
+            # Get list of CSV files in output directory
+            csv_files = [f for f in os.listdir(self.output_path) if f.endswith('.csv')]
+            uploaded_files = []
+
+            # Upload each CSV file
+            for csv_file in csv_files:
+                try:
+                    local_filepath = os.path.join(self.output_path, csv_file)
+
+                    # Determine upload directory based on filename
+                    if csv_file == "employee_import.csv":
+                        upload_dir = "ENTRADA/EMPLEADOS"
+                    else:
+                        upload_dir = "SALIDA"
+
+                    remote_filepath = os.path.join(upload_path, upload_dir, csv_file).replace('\\', '/')
+
+                    # Upload file using SFTP attribute
+                    self.sftp.upload_file(
+                        local_filepath=local_filepath,
+                        remote_filepath=remote_filepath
+                    )
+
+                    uploaded_files.append(remote_filepath)
+
+                except Exception as file_error:
+                    print(f"Failed to upload {csv_file}: {file_error}")
+                    # Continue with other files even if one fails
+                    continue
+
+            if not uploaded_files:
+                raise Exception("No files were successfully uploaded")
+
+            return f"The files successfully uploaded: {', '.join(uploaded_files)}"
+
+        except Exception as e:
+            raise Exception(f"Upload failed with unexpected error: {e}")

brynq_sdk_meta4/schemas/__init__.py

@@ -0,0 +1,9 @@
+from .employee import EmployeeSchema
+from .cost_center import CostCenterSchema
+from .job import JobSchema
+
+__all__ = [
+    'EmployeeSchema',
+    'CostCenterSchema',
+    'JobSchema'
+]

brynq_sdk_meta4/schemas/cost_center.py

@@ -0,0 +1,39 @@
+from pydantic import BaseModel, Field, model_validator
+from typing import Literal, Optional
+
+
+class CostCenterSchema(BaseModel):
+    """
+    Pydantic schema for Meta4 Cost Center data.
+    Based on EQU_Interfaz_Centros_Coste specification.
+    """
+
+    # Movement Information
+    movement_type: Literal["-36", "-37"] = Field(description="Tipo de movimiento", example="-36", alias="Tipo de movimiento", max_length=3)
+
+    # Cost Center Information
+    cost_center_id: Optional[str] = Field(None, description="ID Centro de Coste", example="C200", alias="ID Centro de Coste", max_length=50)
+    cost_center_name: Optional[str] = Field(None, description="Nombre Centro de Coste", example="Centro de Coste Principal", alias="Nombre Centro de Coste", max_length=62)
+
+    @model_validator(mode='after')
+    def validate_movement_requirements(self):
+        """Validate mandatory fields based on movement_type"""
+        if self.movement_type == "-36":
+            # All fields are mandatory for CREATE (-36)
+            mandatory_fields_create = ['cost_center_id', 'cost_center_name']
+            for field_name in mandatory_fields_create:
+                field_value = getattr(self, field_name, None)
+                if field_value is None or field_value == "":
+                    raise ValueError(f"{field_name} is mandatory for CREATE (-36) movement")
+        elif self.movement_type == "-37":
+            # Only cost_center_id is mandatory for UPDATE (-37)
+            mandatory_fields_update = ['cost_center_id']
+            for field_name in mandatory_fields_update:
+                field_value = getattr(self, field_name, None)
+                if field_value is None or field_value == "":
+                    raise ValueError(f"{field_name} is mandatory for UPDATE (-37) movement")
+        return self
+
+    class Config:
+        allow_population_by_field_name = True
+        populate_by_name = True