folio-migration-tools 1.10.1__py3-none-any.whl → 1.10.3__py3-none-any.whl

folio_migration_tools/__init__.py

@@ -1,3 +1,5 @@
+"""FOLIO Migration Tools package for migrating library data to FOLIO LSP."""
+
 import importlib.metadata
 from typing import Protocol
 
@@ -5,6 +7,12 @@ __version__ = importlib.metadata.version("folio_migration_tools")
 
 
 class StrCoercible(Protocol):
-    def __repr__(self) -> str: ...
+    """Protocol for objects that can be coerced to string."""
+
+    def __repr__(self) -> str:
+        """Return repr(self)."""
+        ...
 
-    def __str__(self) -> str: ...
+    def __str__(self) -> str:
+        """Return str(self)."""
+        ...

folio_migration_tools/__main__.py

@@ -1,3 +1,10 @@
+"""Main entry point for the folio_migration_tools CLI.
+
+Provides the command-line interface for running migration tasks. Loads configuration
+files, validates parameters, instantiates appropriate task classes, and executes
+the migration workflow. Supports all transformation and loading tasks.
+"""
+
 from importlib import metadata
 import json
 import logging

folio_migration_tools/circulation_helper.py

@@ -1,3 +1,10 @@
+"""Helper utilities for circulation transactions migration.
+
+Provides the CirculationHelper class with methods for validating and posting
+circulation transactions (loans, requests). Handles patron and item lookups,
+loan policy validation, and error handling for circulation operations.
+"""
+
 import copy
 import json
 import logging
@@ -29,6 +36,13 @@ class CirculationHelper:
         service_point_id,
         migration_report: MigrationReport,
     ):
+        """Initialize CirculationHelper with FOLIO client and service point.
+
+        Args:
+            folio_client (FolioClient): FOLIO API client for circulation operations.
+            service_point_id: ID of the service point for check-outs and check-ins.
+            migration_report (MigrationReport): Report object for tracking statistics.
+        """
         self.folio_client = folio_client
         self.service_point_id = service_point_id
         self.missing_patron_barcodes: Set[str] = set()
@@ -72,15 +86,16 @@ class CirculationHelper:
             return {}
 
     def is_checked_out(self, legacy_loan: LegacyLoan) -> bool:
-        """Makes a deeper check to find out if the loan is already processed.
+        """Makes a deeper check to find out if the loan is already checked out in FOLIO.
+
         Looks up the item id, and then searches Loan Storage for any open loans.
         If there are open loans, returns True. Else False.
 
         Args:
-            legacy_loan (LegacyLoan): _description_
+            legacy_loan (LegacyLoan): The legacy loan object to check.
 
         Returns:
-            bool: _description_
+            bool: True if the loan is already checked out, False otherwise.
         """
         if item := self.get_item_by_barcode(legacy_loan.item_barcode):
             if self.get_active_loan_by_item_id(item["id"]):
@@ -113,16 +128,16 @@ class CirculationHelper:
             return {}
 
     def check_out_by_barcode(self, legacy_loan: LegacyLoan) -> TransactionResult:
-        """Checks out a legacy loan using the Endpoint /circulation/check-out-by-barcode
-        Adds all possible overrides in order to make the transaction go through
+        """Checks out a legacy loan using the Endpoint /circulation/check-out-by-barcode.
+
+        Adds all possible overrides in order to make the transaction go through.
 
         Args:
-            legacy_loan (LegacyLoan): _description_
+            legacy_loan (LegacyLoan): The legacy loan object to check.
 
         Returns:
-            TransactionResult: _description_
+            TransactionResult: The result of the check-out transaction.
         """
-
         t0_function = time.time()
         data = {
             "itemBarcode": legacy_loan.item_barcode,

folio_migration_tools/colors.py

@@ -1,3 +1,10 @@
+"""Terminal color codes for formatted console output.
+
+Defines ANSI escape codes for colorizing terminal output in migration reports
+and progress messages.
+"""
+
+
 class Bcolors:
     HEADER = "\033[95m"
     OKBLUE = "\033[94m"

folio_migration_tools/config_file_load.py

@@ -1,3 +1,10 @@
+"""Configuration file loading and merging utilities.
+
+Provides functions for loading JSON configuration files with support for
+inheriting from parent configurations. Handles deep merging of nested
+dictionaries and lists while preserving unique entries.
+"""
+
 import json
 from pathlib import Path
 

folio_migration_tools/custom_dict.py

@@ -1,7 +1,21 @@
+"""Custom CSV DictReader with case-insensitive field names.
+
+Provides the InsensitiveDictReader class that normalizes CSV field names to
+lowercase and strips whitespace, making CSV parsing more forgiving of
+inconsistent header formatting.
+"""
+
 import csv
 
 
 class InsensitiveDictReader(csv.DictReader):
+    """CSV DictReader with case-insensitive field names.
+
+    This class extends csv.DictReader to normalize field names by stripping
+    leading/trailing whitespace and converting them to lowercase. This allows
+    for more forgiving CSV parsing where header formatting may vary.
+    """
+
     # This class overrides the csv.fieldnames property, which converts all
     # fieldnames without leading and trailing
     # spaces and to lower case.
@@ -14,7 +28,10 @@ class InsensitiveDictReader(csv.DictReader):
 
 
 class InsensitiveDict(dict):
+    """Dictionary with case-insensitive key lookup."""
+
     # This class overrides the __getitem__ method to automatically strip()
     # and lower() the input key
     def __getitem__(self, key):
+        """Get item by key, normalizing to lowercase and stripped."""
         return dict.__getitem__(self, key.strip().lower())

folio_migration_tools/custom_exceptions.py

@@ -1,3 +1,11 @@
+"""Custom exception classes for migration transformations.
+
+Defines specialized exception types for different transformation error scenarios:
+- TransformationFieldMappingError: Non-critical data issues
+- TransformationRecordFailedError: Critical record-level failures
+- TransformationProcessError: Fatal configuration or process errors
+"""
+
 import logging
 import i18n
 
@@ -10,15 +18,25 @@ class TransformationError(Exception):
 
 class TransformationFieldMappingError(TransformationError):
     """Raised when the field mapping fails, but the error is not critical.
-    The issue should be logged for the library to act upon it"""
+
+    The issue should be logged for the library to act upon it
+    """
 
     def __init__(self, index_or_id="", message="", data_value: str | StrCoercible = ""):
+        """Initialize field mapping error with index, message, and data value.
+
+        Args:
+            index_or_id: Record identifier or row index from source data.
+            message: Descriptive error message.
+            data_value: The problematic data value.
+        """
         self.index_or_id = index_or_id or ""
         self.message = message
         self.data_value: str | StrCoercible = data_value
         super().__init__(self.message)
 
     def __str__(self):
+        """Return formatted error message with record context."""
         return (
             i18n.t("Data issue. Consider fixing the record. ")
             + f"\t{self.index_or_id}\t{self.message}\t{self.data_value}"
@@ -35,9 +53,16 @@ class TransformationFieldMappingError(TransformationError):
 
 
 class TransformationRecordFailedError(TransformationError):
-    """Raised when the field mapping fails, Error is critical and means transformation fails"""
+    """Raised when the field mapping fails, Error is critical and means transformation fails."""
 
     def __init__(self, index_or_id, message="", data_value=""):
+        """Initialize record failure error with context information.
+
+        Args:
+            index_or_id: Record identifier or row index from source data.
+            message: Descriptive error message about the failure.
+            data_value: The problematic data value.
+        """
         self.index_or_id = index_or_id
         self.message = message
         self.data_value: str | StrCoercible = data_value
@@ -45,6 +70,7 @@ class TransformationRecordFailedError(TransformationError):
         super().__init__(self.message)
 
     def __str__(self):
+        """Return formatted error message with record context."""
         return (
             f"Critical data issue. Record needs fixing"
             f"\t{self.index_or_id}\t{self.message}\t{self.data_value}"
@@ -61,8 +87,10 @@ class TransformationRecordFailedError(TransformationError):
 
 
 class TransformationProcessError(TransformationError):
-    """Raised when the transformation fails due to incorrect configuration,
-    mapping or reference data. This error should take the process to a halt."""
+    """Raised when the transformation fails due to incorrect configuration.
+
+    This error should take the process to a halt when mapping or reference data is incorrect.
+    """
 
     def __init__(
         self,
@@ -71,12 +99,20 @@ class TransformationProcessError(TransformationError):
         " Check configuration, mapping files and reference data",
         data_value: str | StrCoercible = "",
     ):
+        """Initialize process error with configuration or reference data context.
+
+        Args:
+            index_or_id: Record identifier or context for where error occurred.
+            message: Descriptive error message about the process failure.
+            data_value: The problematic data or configuration value.
+        """
         self.index_or_id = index_or_id
         self.message = message
         self.data_value = data_value
         super().__init__(self.message)
 
     def __str__(self):
+        """Return formatted error message with process context."""
         return (
             f"Critical Process issue. Check configuration, mapping files and reference data"
             f"\t{self.index_or_id}\t{self.message}\t{self.data_value}"

folio_migration_tools/extradata_writer.py

@@ -1,3 +1,10 @@
+"""Writer for extradata objects generated during transformation.
+
+Provides the ExtradataWriter class for buffering and writing extradata objects
+(e.g., organization interfaces, bound-with parts) to separate files during
+migration. Handles buffering, flushing, and file management.
+"""
+
 import json
 import logging
 import os
@@ -17,6 +24,11 @@ class ExtradataWriter:
         return cls.__instance
 
     def __init__(self, path_to_file: Path) -> None:
+        """Initialize the singleton extradata writer.
+
+        Args:
+            path_to_file (Path): Path to the file where extradata will be written.
+        """
         if type(self).__inited:
             return
         self.cache: List[str] = []

folio_migration_tools/folder_structure.py

@@ -1,3 +1,10 @@
+"""Folder structure management for migration tasks.
+
+Defines the FolderStructure class that manages the standardized directory layout
+for migration tasks. Creates and manages folders for source data, results, reports,
+logs, and mapping files. Handles path generation and validation.
+"""
+
 import logging
 import sys
 import time
@@ -15,6 +22,15 @@ class FolderStructure:
         iteration_identifier: str,
         add_time_stamp_to_file_names: bool,
     ):
+        """Initialize folder structure for a migration task iteration.
+
+        Args:
+            base_path (Path): Root folder for the migration.
+            object_type (FOLIONamespaces): Type of FOLIO object being migrated.
+            migration_task_name (str): Name of the migration task.
+            iteration_identifier (str): Identifier for this migration iteration.
+            add_time_stamp_to_file_names (bool): Whether to add timestamps to output files.
+        """
         logging.info("Validating folder structure")
 
         self.object_type: FOLIONamespaces = object_type

folio_migration_tools/helper.py

@@ -1,3 +1,10 @@
+"""General helper utilities for migration tasks.
+
+Provides the Helper class with static utility methods for data validation,
+mapping report generation, and common transformation operations used across
+multiple migration tasks.
+"""
+
 import json
 import logging
 

folio_migration_tools/holdings_helper.py

@@ -1,3 +1,10 @@
+"""Helper utilities specific to holdings transformations.
+
+Provides the HoldingsHelper class with methods for holdings-specific validations
+and transformations including location handling, call number processing, and
+holdings notes management.
+"""
+
 import json
 import logging
 import i18n
@@ -17,14 +24,13 @@ class HoldingsHelper:
         migration_report: MigrationReport,
         holdings_type_id_to_exclude_from_merging: str = "Not set",
     ) -> str:
-        """Creates a key from values determined by the fields_crieteria in a holding
-        record to determine uniquenes
+        """Create a unique key from holding field values for merging.
 
         fields_criterias are limited to the strings and UUID properties on the first level of
-        the object. If the property is not found, or empty, it will be ignored
+        the object. If the property is not found, or empty, it will be ignored.
 
-        IF the holdings type id is matched to holdings_type_id_to_exclude_from_merging,
-        the key will be added with a uuid to prevent merging of this holding
+        If the holdings type id is matched to holdings_type_id_to_exclude_from_merging,
+        the key will be added with a uuid to prevent merging of this holding.
 
         Args:
             holdings_record (dict): The Holdingsrecord

folio_migration_tools/i18n_config.py

@@ -1,3 +1,9 @@
+"""Internationalization configuration.
+
+Defines settings for the i18n library used for translation of user-facing messages
+in migration reports and logs. Configures translation file locations and formats.
+"""
+
 from pathlib import Path
 
 settings = {

folio_migration_tools/library_configuration.py

@@ -1,3 +1,10 @@
+"""Library and task configuration models.
+
+Defines Pydantic models for library-wide configuration (LibraryConfiguration) and
+file definitions (FileDefinition). Handles configuration validation, folder structure
+setup, and migration parameters like HRID handling and iteration identifiers.
+"""
+
 from enum import Enum
 from typing import Annotated
 
@@ -7,12 +14,14 @@ from pydantic.types import DirectoryPath
 
 class HridHandling(str, Enum):
     """Enum determining how the HRID generation should be handled.
+
+    Options:
         - default: Enumerates the HRID, building on the current value in the HRID settings
         - preserve001: Takes the 001 and uses this as the HRID.
 
     Args:
-        str (_type_): _description_
-        Enum (_type_): _description_
+        str (_type_): The type of HRID handling.
+        Enum (_type_): The enumeration of HRID handling options.
     """
 
     default = "default"
@@ -77,7 +86,7 @@ class FileDefinition(BaseModel):
 
 
 class IlsFlavour(str, Enum):
-    """ """
+    """Enum representing different ILS flavours for migration."""
 
     aleph = "aleph"
     voyager = "voyager"
@@ -92,6 +101,8 @@ class IlsFlavour(str, Enum):
 
 
 class FolioRelease(str, Enum):
+    """Enum representing different FOLIO releases."""
+
     ramsons = "ramsons"
     sunflower = "sunflower"
     trillium = "trillium"
@@ -99,6 +110,8 @@ class FolioRelease(str, Enum):
 
 
 class LibraryConfiguration(BaseModel):
+    """Pydantic model for tenant-level configuration."""
+
     gateway_url: Annotated[
         str,
         Field(
@@ -249,8 +262,9 @@ class LibraryConfiguration(BaseModel):
     @model_validator(mode="before")
     @classmethod
     def set_error_thresholds_for_debug(cls, values):
-        """If log_level_debug is true, set error thresholds to very high values to avoid
-        process shutdown during debugging.
+        """If log_level_debug is true, set error thresholds to very high values.
+
+        This avoids process shutdown during debugging.
         """
         if values.get("log_level_debug", False):
             values["failed_records_threshold"] = 10_000_000

folio_migration_tools/mapper_base.py

@@ -1,3 +1,10 @@
+"""Base class for all data mappers.
+
+Provides the MapperBase class with common functionality for transforming legacy
+data to FOLIO format. Handles reference data mapping, field validation, error
+handling, bound-with processing, and statistical code mapping.
+"""
+
 import ast
 import copy
 import json
@@ -41,6 +48,14 @@ class MapperBase:
         folio_client: FolioClient,
         parent_id_map: Dict[str, Tuple] | None = None,
     ):
+        """Initialize the mapper base with configuration and FOLIO client.
+
+        Args:
+            library_configuration (LibraryConfiguration): Library-specific configuration.
+            task_configuration (AbstractTaskConfiguration): Task-specific transformation settings.
+            folio_client (FolioClient): FOLIO API client for reference data and posting.
+            parent_id_map (Dict[str, Tuple] | None): Optional parent id map from prior transform.
+        """
         logging.info("MapperBase initiating")
         self.parent_id_map: dict[str, tuple] = parent_id_map or {}
         self.extradata_writer: ExtradataWriter = ExtradataWriter(Path(""))

folio_migration_tools/mapping_file_transformation/__init__.py

@@ -0,0 +1 @@
+"""Mappers for transforming CSV/JSON data using mapping configuration files."""

folio_migration_tools/mapping_file_transformation/courses_mapper.py

@@ -1,3 +1,10 @@
+"""Mapper for transforming course data to FOLIO Course Reserves format.
+
+Provides the CoursesMapper class for mapping legacy course data to FOLIO course
+records using configured mapping files. Handles course listings, instructors, and
+term/department references.
+"""
+
 import i18n
 from typing import Any
 from typing import Dict
@@ -27,6 +34,16 @@ class CoursesMapper(MappingFileMapperBase):
         library_configuration: LibraryConfiguration,
         task_configuration,
     ):
+        """Initialize CoursesMapper with mapping configurations.
+
+        Args:
+            folio_client (FolioClient): FOLIO API client.
+            course_map: Course mapping configuration.
+            terms_map: Academic terms mapping configuration.
+            departments_map: Department mapping configuration.
+            library_configuration (LibraryConfiguration): Library configuration.
+            task_configuration: Task configuration for course migration.
+        """
         self.folio_client: FolioClient = folio_client
         self.user_cache: dict = {}
         self.notes_mapper: NotesMapper = NotesMapper(

folio_migration_tools/mapping_file_transformation/holdings_mapper.py

@@ -1,3 +1,10 @@
+"""Mapper for transforming holdings data to FOLIO Holdings format.
+
+Provides the HoldingsMapper class for mapping legacy holdings data to FOLIO Holdings
+records using configured mapping files. Handles locations, call numbers, notes, and
+bound-with relationships.
+"""
+
 import ast
 import json
 import logging
@@ -35,6 +42,18 @@ class HoldingsMapper(MappingFileMapperBase):
         task_config: AbstractTaskConfiguration,
         statistical_codes_map=None,
     ):
+        """Initialize HoldingsMapper for holdings transformations.
+
+        Args:
+            folio_client (FolioClient): FOLIO API client.
+            holdings_map: Mapping configuration for holdings fields.
+            location_map: Mapping of legacy to FOLIO locations.
+            call_number_type_map: Mapping of legacy to FOLIO call number types.
+            instance_id_map: Mapping of legacy to FOLIO instance IDs.
+            library_configuration (LibraryConfiguration): Library configuration.
+            task_config (AbstractTaskConfiguration): Task configuration.
+            statistical_codes_map: Mapping of legacy to FOLIO statistical codes.
+        """
         holdings_schema = folio_client.get_holdings_schema()
         self.instance_id_map = instance_id_map
         super().__init__(

folio_migration_tools/mapping_file_transformation/item_mapper.py

@@ -1,3 +1,10 @@
+"""Mapper for transforming item data to FOLIO Items format.
+
+Provides the ItemMapper class for mapping legacy item data to FOLIO Item records
+using configured mapping files. Handles material types, loan types, statuses, and
+circulation notes.
+"""
+
 import json
 import logging
 import sys
@@ -44,6 +51,23 @@ class ItemMapper(MappingFileMapperBase):
         library_configuration: LibraryConfiguration,
         task_configuration: AbstractTaskConfiguration,
     ):
+        """Initialize ItemMapper for item transformations.
+
+        Args:
+            folio_client (FolioClient): FOLIO API client.
+            items_map: Mapping configuration for item fields.
+            material_type_map: Mapping of legacy to FOLIO material types.
+            loan_type_map: Mapping of legacy to FOLIO loan types.
+            location_map: Mapping of legacy to FOLIO locations.
+            call_number_type_map: Mapping of legacy to FOLIO call number types.
+            holdings_id_map: Mapping of legacy to FOLIO holdings IDs.
+            statistical_codes_map: Mapping of legacy to FOLIO statistical codes.
+            item_statuses_map: Mapping of legacy to FOLIO item statuses.
+            temporary_loan_type_mapping: Mapping for temporary loan types.
+            temporary_location_mapping: Mapping for temporary locations.
+            library_configuration (LibraryConfiguration): Library configuration.
+            task_configuration (AbstractTaskConfiguration): Task configuration.
+        """
         item_schema = folio_client.get_item_schema()
         super().__init__(
             folio_client,

folio_migration_tools/mapping_file_transformation/manual_fee_fines_mapper.py

@@ -1,3 +1,9 @@
+"""Mapper for transforming manual fee/fine data to FOLIO Accounts format.
+
+Provides the ManualFeeFinesMapper class for mapping legacy fee and fine data to FOLIO
+Account records. Handles fee/fine types, owners, amounts, and payment status.
+"""
+
 import json
 import logging
 import uuid
@@ -34,6 +40,18 @@ class ManualFeeFinesMapper(MappingFileMapperBase):
         service_point_map,
         ignore_legacy_identifier: bool = True,
     ):
+        """Initialize ManualFeeFinesMapper for fee/fine transformations.
+
+        Args:
+            folio_client (FolioClient): FOLIO API client.
+            library_configuration (LibraryConfiguration): Library configuration.
+            task_configuration: Task configuration for fee fines migration.
+            feefines_map: Mapping configuration for fee/fine fields.
+            feefines_owner_map: Mapping of legacy to FOLIO fee/fine owners.
+            feefines_type_map: Mapping of legacy to FOLIO fee/fine types.
+            service_point_map: Mapping of legacy to FOLIO service points.
+            ignore_legacy_identifier (bool): Whether to ignore legacy identifiers.
+        """
         self.folio_client: FolioClient = folio_client
         self.composite_feefine_schema = self.get_composite_feefine_schema()
         self.task_configuration = task_configuration

folio_migration_tools/mapping_file_transformation/mapping_file_mapper_base.py

@@ -1,3 +1,10 @@
+"""Base class for all mapping file-based data transformations.
+
+Provides the MappingFileMapperBase abstract class that all mapper classes inherit
+from. Handles common functionality for loading mapping files, validating mappings,
+and performing data transformations based on configured field mappings.
+"""
+
 import csv
 import itertools
 import json
@@ -38,6 +45,18 @@ class MappingFileMapperBase(MapperBase):
         task_config: AbstractTaskConfiguration,
         ignore_legacy_identifier=False,
     ):
+        """Initialize the base mapper for mapping file transformations.
+
+        Args:
+            folio_client (FolioClient): FOLIO API client.
+            schema: JSON schema for validation.
+            record_map: Mapping configuration from legacy to FOLIO fields.
+            statistical_codes_map: Mapping for statistical codes.
+            uuid_namespace (UUID): UUID namespace for deterministic IDs.
+            library_configuration (LibraryConfiguration): Library configuration.
+            task_config (AbstractTaskConfiguration): Task configuration.
+            ignore_legacy_identifier (bool): Whether to ignore legacy identifiers.
+        """
         super().__init__(library_configuration, task_config, folio_client)
         self.uuid_namespace = uuid_namespace
         self.ignore_legacy_identifier = ignore_legacy_identifier
@@ -685,12 +704,10 @@ class MappingFileMapperBase(MapperBase):
 
     @staticmethod
     def _get_delimited_file_reader(source_file, file_name: Path):
-        """
-            First, let's count:
-            * The total number of rows in the source file
-            * The total number of empty rows in the source file
+        """Count rows in source file and return counts with a DictReader.
 
-            Then, we'll return those counts and a csv.DictReader
+        Counts total rows and empty rows, then returns those counts
+        along with a csv.DictReader.
 
         Args:
             source_file (_type_): _description_
@@ -884,7 +901,7 @@ def weird_division(number, divisor):
 
 
 def set_deep(dictionary, key, value):
-    """sets a nested property in a dict given a dot notated address
+    """Sets a nested property in a dict given a dot notated address.
 
     Args:
         dictionary (_type_): a python dictionary ({"a":{"b":{"c":"value"}}})
@@ -901,7 +918,7 @@ def set_deep(dictionary, key, value):
 
 
 def set_deep2(dictionary, key, value):
-    """sets a nested property in a dict given a dot notated address
+    """Sets a nested property in a dict given a dot notated address.
 
     Args:
         dictionary (_type_): a python dictionary ({"a":{"b":{"c":"value"}}})
@@ -938,7 +955,7 @@ def set_deep2(dictionary, key, value):
 
 
 def get_deep(dictionary, keys, default=None):
-    """returns a nested property in a dict given a dot notated address
+    """Returns a nested property in a dict given a dot notated address.
 
     Args:
         dictionary (_type_): a python dictionary ({"a":{"b":{"c":"value"}}})
@@ -956,7 +973,7 @@ def get_deep(dictionary, keys, default=None):
 
 
 def in_deep(dictionary, keys):
-    """Checks if a property exists given a dot notated address
+    """Checks if a property exists given a dot notated address.
 
     Args:
         dictionary (_type_): a python dictionary ({"a":{"b":{"c":"value"}}})