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

folio_migration_tools/mapping_file_transformation/notes_mapper.py

@@ -1,3 +1,9 @@
+"""Mapper for transforming notes to FOLIO Notes format.
+
+Provides the NotesMapper class for mapping legacy notes to FOLIO Notes records.
+Handles note types, content, and object associations.
+"""
+
 import logging
 import i18n
 
@@ -20,6 +26,16 @@ class NotesMapper(MappingFileMapperBase):
         object_type: FOLIONamespaces,
         ignore_legacy_identifier: bool = False,
     ) -> None:
+        """Initialize NotesMapper for handling note transformations.
+
+        Args:
+            library_configuration (LibraryConfiguration): Library configuration.
+            task_configuration: Task configuration for note migration.
+            folio_client (FolioClient): FOLIO API client.
+            record_map (dict): Mapping configuration for note fields.
+            object_type (FOLIONamespaces): Type of object containing notes.
+            ignore_legacy_identifier (bool): Whether to ignore legacy identifiers.
+        """
         self.folio_client: FolioClient = folio_client
         self.setup_notes_schema()
         super().__init__(

folio_migration_tools/mapping_file_transformation/order_mapper.py

@@ -1,3 +1,10 @@
+"""Mapper for transforming order data to FOLIO Orders format.
+
+Provides the OrderMapper class for mapping legacy purchase order data to FOLIO
+Orders and PurchaseOrderLines. Handles composite orders with embedded lines,
+acquisition units, fund distributions, and vendor references.
+"""
+
 import json
 import logging
 import os
@@ -41,6 +48,23 @@ class CompositeOrderMapper(MappingFileMapperBase):
         funds_map,
         funds_expense_class_map=None,
     ):
+        """Initialize CompositeOrderMapper for purchase order transformations.
+
+        Args:
+            folio_client (FolioClient): FOLIO API client.
+            library_configuration (LibraryConfiguration): Library configuration.
+            task_configuration: Task configuration for orders migration.
+            composite_order_map (dict): Mapping configuration for order fields.
+            organizations_id_map (dict): Mapping of legacy to FOLIO organizations.
+            instance_id_map (dict): Mapping of legacy to FOLIO instances.
+            acquisition_method_map: Mapping of legacy to FOLIO acquisition methods.
+            payment_status_map: Mapping of legacy to FOLIO payment statuses.
+            receipt_status_map: Mapping of legacy to FOLIO receipt statuses.
+            workflow_status_map: Mapping of legacy to FOLIO workflow statuses.
+            location_map: Mapping of legacy to FOLIO locations.
+            funds_map: Mapping of legacy to FOLIO funds.
+            funds_expense_class_map: Mapping for fund expense classes.
+        """
         # Get organization schema
         self.composite_order_schema = CompositeOrderMapper.get_latest_acq_schemas_from_github(
             "folio-org", "mod-orders", "mod-orders", "composite_purchase_order"
@@ -139,19 +163,16 @@ class CompositeOrderMapper(MappingFileMapperBase):
 
     @staticmethod
     def get_latest_acq_schemas_from_github(owner, repo, module, object):
-        """
-        Given a repository owner, a repository, a module name and the name
-        of a FOLIO acquisition object, returns a schema for that object that
-        also includes the schemas of any other referenced acq objects.
+        """Fetch acquisition object schema from GitHub with referenced schemas.
 
         Args:
-            owner (_type_): _description_
-            repo (_type_): _description_
-            module (_type_): _description_
-            object (_type_): _description_
+            owner (str): GitHub repository owner.
+            repo (str): GitHub repository name.
+            module (str): Module name within the repository.
+            object (str): Object name whose schema is to be fetched.
 
         Returns:
-            _type_: _description_
+            Dict: _description_
         """
         try:
             # Authenticate when calling GitHub, using an API key stored in .env
@@ -206,22 +227,18 @@ class CompositeOrderMapper(MappingFileMapperBase):
 
     @staticmethod
     def get_submodules_of_latest_release(owner, repo, github_headers):
-        """
-        Given a repository owner and a repository, identifies the latest
-        release of the repository and returns the submodules associated with
-        this release.
+        """Get submodules associated with the latest release of a repository.
 
         Args:
-            owner (_type_): _description_
-            repo (_type_): _description_
-            github_headers (_type_): _description_
+            owner (str): GitHub repository owner.
+            repo (str): GitHub repository name.
+            github_headers (dict): Headers to use for GitHub API requests.
 
         Returns:
-            _type_: _description_
+            list: List of submodules associated with the latest release.
 
 
         """
-
         github_path = "https://api.github.com/repos"
 
         # Get metadata for the latest release
@@ -258,20 +275,16 @@ class CompositeOrderMapper(MappingFileMapperBase):
 
     @staticmethod
     def build_extended_object(object_schema, submodule_path, github_headers):
-        """
-        Takes an object schema (for example an organization) and the path to a
-        submodule repository and returns the same schema with the full schemas
-        of subordinate objects (for example aliases).
+        """Extend an object schema with full schemas of subordinate objects.
 
         Args:
-            object_schema (_type_): _description_
-            submodule_path (_type_): _description_
-            github_headers (_type_): _description_
+            object_schema (dict): The schema of the object to be extended.
+            submodule_path (str): The path to the submodule containing schemas.
+            github_headers (dict): Headers to use for GitHub API requests.
 
         Returns:
-            _type_: _description_
+            dict: The extended object schema.
         """
-
         supported_types = [
             "string",
             "boolean",

folio_migration_tools/mapping_file_transformation/organization_mapper.py

@@ -1,3 +1,10 @@
+"""Mapper for transforming organization data to FOLIO Organizations format.
+
+Provides the OrganizationMapper class for mapping legacy vendor/organization data
+to FOLIO Organization records. Handles embedded interfaces, contacts, categories,
+and extradata object creation.
+"""
+
 import json
 import logging
 import os
@@ -30,6 +37,18 @@ class OrganizationMapper(MappingFileMapperBase):
         email_categories_map,
         phone_categories_map,
     ):
+        """Initialize OrganizationMapper for organization transformations.
+
+        Args:
+            folio_client (FolioClient): FOLIO API client.
+            library_configuration (LibraryConfiguration): Library configuration.
+            task_config: Task configuration for organizations migration.
+            organization_map (dict): Mapping configuration for organization fields.
+            organization_types_map: Mapping of legacy to FOLIO organization types.
+            address_categories_map: Mapping of legacy to FOLIO address categories.
+            email_categories_map: Mapping of legacy to FOLIO email categories.
+            phone_categories_map: Mapping of legacy to FOLIO phone categories.
+        """
         # Build composite organization schema
         if os.environ.get("GITHUB_TOKEN"):
             logging.info("Using GITHUB_TOKEN environment variable for GitHub API Access")
@@ -119,15 +138,14 @@ class OrganizationMapper(MappingFileMapperBase):
         email_categories_map,
         phone_categories_map,
     ):
-        """
+        """Set up reference data mappings for organization categories and types.
 
         Args:
-            organization_types_map (_type_): _description_
-            address_categories_map (_type_): _description_
-            email_categories_map (_type_): _description_
-            phone_categories_map (_type_): _description_
+        organization_types_map (dict): Mapping for organization types.
+        address_categories_map (dict): Mapping for address categories.
+        email_categories_map (dict): Mapping for email categories.
+        phone_categories_map (dict): Mapping for phone categories.
         """
-
         categories_shared_args = (
             self.folio_client,
             "/organizations-storage/categories",
@@ -169,19 +187,16 @@ class OrganizationMapper(MappingFileMapperBase):
 
     @staticmethod
     def get_latest_acq_schemas_from_github(owner, repo, module, object):
-        """
-        Given a repository owner, a repository, a module name and the name
-        of a FOLIO acquisition object, returns a schema for that object that
-        also includes the schemas of any other referenced acq objects.
+        """Fetch acquisition object schema from GitHub with referenced schemas.
 
         Args:
-            owner (_type_): _description_
-            repo (_type_): _description_
-            module (_type_): _description_
-            object (_type_): _description_
+            owner (str): GitHub repository owner.
+            repo (str): GitHub repository name.
+            module (str): Module name within the repository.
+            object (str): Object name whose schema is to be fetched.
 
         Returns:
-            _type_: _description_
+            dict: The extended object schema.
         """
         try:
             # Authenticate when calling GitHub, using an API key stored in .env
@@ -232,20 +247,16 @@ class OrganizationMapper(MappingFileMapperBase):
 
     @staticmethod
     def get_submodules_of_latest_release(owner, repo, github_headers):
-        """
-        Given a repository owner and a repository, identifies the latest
-        release of the repository and returns the submodules associated with
-        this release.
+        """Get submodules associated with the latest release of a repository.
 
         Args:
-            owner (_type_): _description_
-            repo (_type_): _description_
-            github_headers (_type_): _description_
+            owner (str): GitHub repository owner.
+            repo (str): GitHub repository name.
+            github_headers (dict): Headers to use for GitHub API requests.
 
         Returns:
-            _type_: _description_
+            list: List of submodules associated with the latest release.
         """
-
         github_path = "https://api.github.com/repos"
 
         # Get metadata for the latest release
@@ -280,20 +291,16 @@ class OrganizationMapper(MappingFileMapperBase):
 
     @staticmethod
     def build_extended_object(object_schema, submodule_path, github_headers):
-        """
-        Takes an object schema (for example an organization) and the path to a
-        submodule repository and returns the same schema with the full schemas
-        of subordinate objects (for example aliases).
+        """Extend an object schema with full schemas of subordinate objects.
 
         Args:
-            object_schema (_type_): _description_
-            submodule_path (_type_): _description_
-            github_headers (_type_): _description_
+            object_schema (dict): The base object schema to extend.
+            submodule_path (str): Path to the submodule containing additional schemas.
+            github_headers (dict): Headers to use for GitHub API requests.
 
         Returns:
-            _type_: _description_
+            dict: The extended object schema.
         """
-
         supported_types = ["string", "boolean", "number", "integer", "text", "object", "array"]
 
         try:

folio_migration_tools/mapping_file_transformation/ref_data_mapping.py

@@ -1,3 +1,10 @@
+"""Reference data mapping utilities.
+
+Provides the RefDataMapping class for mapping legacy reference data values to FOLIO
+reference data UUIDs. Handles lookups in FOLIO, wildcard matching, and default values
+for common reference data types like locations, material types, and patron groups.
+"""
+
 import json
 import logging
 import sys
@@ -17,6 +24,16 @@ class RefDataMapping(object):
         key_type,
         blurb_id,
     ):
+        """Initialize RefDataMapping for reference data transformations.
+
+        Args:
+            folio_client (FolioClient): FOLIO API client for fetching reference data.
+            ref_data_path: API path to reference data endpoint.
+            array_name: Name of the data array in the API response.
+            the_map: Mapping configuration for data transformation.
+            key_type: Type of key being mapped.
+            blurb_id: Identifier for blurbs related to this mapping.
+        """
         self.name = array_name
         self.cache: dict = {}
         self.blurb_id = blurb_id

folio_migration_tools/mapping_file_transformation/user_mapper.py

@@ -1,3 +1,9 @@
+"""Mapper for transforming user/patron data to FOLIO Users format.
+
+Provides the UserMapper class for mapping legacy patron data to FOLIO User records
+using configured mapping files.
+"""
+
 import csv
 import json
 import logging
@@ -31,6 +37,16 @@ class UserMapper(MappingFileMapperBase):
         departments_mapping,
         groups_map,
     ):
+        """Initialize UserMapper for user transformations.
+
+        Args:
+            folio_client (FolioClient): FOLIO API client.
+            task_config: Task configuration for users migration.
+            library_config: Library configuration.
+            user_map: Mapping configuration for user fields.
+            departments_mapping: Mapping of legacy to FOLIO departments.
+            groups_map: Mapping of legacy to FOLIO user groups.
+        """
         try:
             user_schema = folio_client.get_from_github(
                 "folio-org", "mod-user-import", "/ramls/schemas/userdataimport.json"

folio_migration_tools/marc_rules_transformation/__init__.py

@@ -0,0 +1 @@
+"""MARC record transformation using FOLIO mapping rules."""

folio_migration_tools/marc_rules_transformation/conditions.py

@@ -1,3 +1,11 @@
+"""MARC rules conditions processing.
+
+A reimplementation of FOLIO's MARC transformation rules. Handles
+evaluation of rule conditions including field presence, indicator values, subfield
+patterns, and parameter validation. Supports complex boolean logic for controlling
+when transformation rules should be applied.
+"""
+
 import logging
 import re
 import traceback
@@ -36,6 +44,15 @@ class Conditions:
         folio_release: FolioRelease,
         default_call_number_type_name="",
     ):
+        """Initialize Conditions processor for MARC field transformation rules.
+
+        Args:
+            folio (FolioClient): FOLIO API client.
+            mapper (RulesMapperBase): Base mapper for rules processing.
+            object_type: Type of FOLIO object being transformed.
+            folio_release (FolioRelease): FOLIO release version.
+            default_call_number_type_name (str): Default call number type name.
+        """
         self.filter_chars = r"[.,\/#!$%\^&\*;:{}=\-_`~()]"
         self.filter_chars_dop = r"[.,\/#!$%\^&\*;:{}=\_`~()]"
         self.folio_release: FolioRelease = folio_release
@@ -161,10 +178,11 @@ class Conditions:
             return attr(legacy_id, value, parameter, marc_field)
 
     def condition_trim_punctuation(self, legacy_id, value, parameter, marc_field: field.Field):
-        """
-        Strip leading and trailing whitespace, as well as any trailing commas or periods, unless
-        the period is preceded by a single alpha character (eg. "John D."). Also preserves any
-        trailing "-" (eg. "1981-"). This condition was introduced in Poppy.
+        """Strip whitespace and trailing punctuation, preserving initials and hyphens.
+
+        Removes leading/trailing whitespace and trailing commas/periods, unless
+        the period is preceded by a single alpha character (eg. "John D.").
+        Also preserves any trailing "-" (eg. "1981-"). Introduced in Poppy.
         """
         pattern1 = re.compile(r"^(.*?)\s.[.]$")
         pattern2 = re.compile(r"^(.*?)\s.,[.]$")
@@ -314,7 +332,7 @@ class Conditions:
     def condition_remove_prefix_by_indicator(
         self, legacy_id, value, parameter, marc_field: field.Field
     ):
-        """Returns the index title according to the rules"""
+        """Returns the index title according to the rules."""
         ind2 = marc_field.indicator2
         reg_str = r"[\s:\/]{0,3}$"
         if ind2 not in map(str, range(1, 9)):
@@ -759,12 +777,11 @@ class Conditions:
     def condition_set_electronic_access_relations_id(
         self, legacy_id, value, parameter, marc_field: field.Field
     ):
-        """
-        This method handles the mapping of electronic access relationship IDs.
-        If the record type being mapped is FOLIO holdings, it provides an (optional) alternative
-        mapping based on a provided name parameter, bypassing the FOLIO MARC-to-Holdings mapping
-        engine behavior. This requires use of a supplemental mapping rules file in the
-        HoldingsMarcTransformer task definition containing the name parameter.
+        """Map electronic access relationship IDs with optional holdings-specific behavior.
+
+        For FOLIO holdings, provides an optional alternative mapping based on a name
+        parameter, bypassing the FOLIO MARC-to-Holdings mapping engine. Requires a
+        supplemental mapping rules file in the HoldingsMarcTransformer task definition.
         """
         if self.object_type == "holdings" and "name" in parameter:
             try:
@@ -808,7 +825,7 @@ class Conditions:
     def condition_set_note_staff_only_via_indicator(
         self, legacy_id, value, parameter, marc_field: field.Field
     ):
-        """Returns true of false depending on the first indicator"""
+        """Returns true of false depending on the first indicator."""
         # https://www.loc.gov/marc/bibliographic/bd541.html
         ind1 = marc_field.indicator1
         self.mapper.migration_report.add(
@@ -869,11 +886,10 @@ class Conditions:
             ) from e
 
     def condition_set_receipt_status(self, legacy_id, value, parameter, marc_field: field.Field):
-        """
-        This method maps the receipt status based on the 008 field.
-        This condition is not available in FOLIO's MARC mapping engine and
-        will require use of a supplemental mapping rules file in the
-        HoldingsMarcTransformer task definition.
+        """Map receipt status from MARC 008 field.
+
+        Requires a supplemental mapping rules file in HoldingsMarcTransformer
+        as this condition is not available in FOLIO's MARC mapping engine.
         """
         if len(value) < 7:
             self.mapper.migration_report.add(
@@ -911,11 +927,10 @@ class Conditions:
     def condition_set_acquisition_method(
         self, legacy_id, value, parameter, marc_field: field.Field
     ):
-        """
-        This method maps the acquisition method based on the 008 field.
-        This condition is not available in FOLIO's MARC mapping engine and
-        will require use of a supplemental mapping rules file in the
-        HoldingsMarcTransformer task definition.
+        """Map acquisition method from MARC 008 field.
+
+        Requires a supplemental mapping rules file in HoldingsMarcTransformer
+        as this condition is not available in FOLIO's MARC mapping engine.
         """
         if len(value) < 8:
             self.mapper.migration_report.add(
@@ -953,11 +968,10 @@ class Conditions:
             return ""
 
     def condition_set_retention_policy(self, legacy_id, value, parameter, marc_field: field.Field):
-        """
-        This method maps the retention policy based on the 008 field.
-        This condition is not available in FOLIO's MARC mapping engine and
-        will require use of a supplemental mapping rules file in the
-        HoldingsMarcTransformer task definition.
+        """Map retention policy from MARC 008 field.
+
+        Requires a supplemental mapping rules file in HoldingsMarcTransformer
+        as this condition is not available in FOLIO's MARC mapping engine.
         """
         if len(value) < 13:
             self.mapper.migration_report.add(
@@ -1037,11 +1051,11 @@ class Conditions:
             return ""
 
     def condition_set_ill_policy(self, legacy_id, value, parameter, marc_field: field.Field):
+        """Map ILL policy from MARC 008 field.
+
+        Requires a supplemental mapping rules file in HoldingsMarcTransformer
+        as this condition is not available in FOLIO's MARC mapping engine.
         """
-        This method maps the ILL policy based on the 008 field.
-        This condition is not available in FOLIO's MARC mapping engine and
-        will require use of a supplemental mapping rules file in the
-        HoldingsMarcTransformer task definition."""
         if len(value) < 21:
             self.mapper.migration_report.add(
                 "ILLPolicyMapping", i18n.t("008 is too short") + f": {value}"
@@ -1077,11 +1091,10 @@ class Conditions:
     def condition_set_digitization_policy(
         self, legacy_id, value, parameter, marc_field: field.Field
     ):
-        """
-        This method maps the digitization policy based on the 008 field.
-        This condition is not available in FOLIO's MARC mapping engine and
-        will require use of a supplemental mapping rules file in the
-        HoldingsMarcTransformer task definition.
+        """Map digitization policy from MARC 008 field.
+
+        Requires a supplemental mapping rules file in HoldingsMarcTransformer
+        as this condition is not available in FOLIO's MARC mapping engine.
         """
         if len(value) < 22:
             self.mapper.migration_report.add(

folio_migration_tools/marc_rules_transformation/holdings_statementsparser.py

@@ -1,3 +1,10 @@
+"""MARC holdings statements parser.
+
+Parses MARC21 holdings statements from fields 853-855, 863-865, 866-868 and converts
+them to FOLIO-compatible holdings statements. Handles enumeration, chronology, and
+holdings notes with proper formatting and validation.
+"""
+
 import calendar
 import contextlib
 import logging
@@ -20,7 +27,7 @@ class HoldingsStatementsParser:
         legacy_ids: List[str],
         dedupe_results: bool = True,
     ) -> dict:
-        """_summary_
+        """_summary_.
 
         Args:
             marc_record (Record): pymarc Record object
@@ -36,7 +43,6 @@ class HoldingsStatementsParser:
         Returns:
             dict: A dictionary containing parsed holdings statements and related information.
         """  # noqa: E501
-
         # Textual holdings statements
         return_dict: dict = {"statements": [], "migration_report": [], "hlm_stmts": []}
         HoldingsStatementsParser.get_textual_statements(
@@ -178,7 +184,7 @@ class HoldingsStatementsParser:
     def get_textual_statements(
         marc_record: Record, field_textual: str, return_dict: dict, legacy_ids: List[str]
     ):
-        """Returns the textual statements from the relevant marc fields
+        """Returns the textual statements from the relevant marc fields.
 
         Args:
             marc_record (Record): _description_

folio_migration_tools/marc_rules_transformation/hrid_handler.py

@@ -1,3 +1,10 @@
+"""HRID (Human Readable ID) handling for MARC transformations.
+
+Manages HRID generation and 001/003/035 field manipulation during MARC transformation.
+Supports both FOLIO-generated HRIDs and preservation of legacy 001 fields as HRIDs.
+Handles creation of 035 fields from previous 001/003 combinations.
+"""
+
 import json
 import logging
 from typing import Set
@@ -22,6 +29,14 @@ class HRIDHandler:
         migration_report: MigrationReport,
         deactivate035_from001: bool,
     ):
+        """Initialize HRID handler for managing FOLIO Human-Readable IDs.
+
+        Args:
+            folio_client (FolioClient): FOLIO API client.
+            handling (HridHandling): HRID handling configuration.
+            migration_report (MigrationReport): Report for tracking operations.
+            deactivate035_from001 (bool): Whether to deactivate 035 fields derived from 001.
+        """
         self.unique_001s: Set[str] = set()
         self.deactivate035_from001: bool = deactivate035_from001
         self.hrid_path = "/hrid-settings-storage/hrid-settings"
@@ -45,7 +60,7 @@ class HRIDHandler:
         marc_record: Record,
         legacy_ids: list[str],
     ) -> None:
-        """Create HRID if not mapped. Add hrid as MARC record 001
+        """Create HRID if not mapped. Add hrid as MARC record 001.
 
         Args:
             namespace (FOLIONamespaces): determening the type of hrid setting to update

folio_migration_tools/marc_rules_transformation/marc_file_processor.py

@@ -1,3 +1,10 @@
+"""MARC file processing orchestration.
+
+Orchestrates the processing of MARC records through the transformation pipeline.
+Handles record reading, validation, transformation via rules mappers, and output
+writing. Manages error handling, progress reporting, and batch processing.
+"""
+
 import logging
 import os
 import sys
@@ -29,6 +36,13 @@ class MarcFileProcessor:
         folder_structure: FolderStructure,
         created_objects_file: TextIO,
     ):
+        """Initialize MARC file processor for processing MARC records.
+
+        Args:
+            mapper (RulesMapperBase): MARC rules mapper for transformations.
+            folder_structure (FolderStructure): Folder structure for file paths.
+            created_objects_file (TextIO): File handle for writing created objects.
+        """
         self.object_type: FOLIONamespaces = folder_structure.object_type
         self.folder_structure: FolderStructure = folder_structure
         self.mapper: RulesMapperBase = mapper
@@ -51,7 +65,7 @@ class MarcFileProcessor:
             self.parent_hrids = {entity[1]: entity[2] for entity in mapper.parent_id_map.values()}
 
     def process_record(self, idx: int, marc_record: Record, file_def: FileDefinition):
-        """processes a marc holdings record and saves it
+        """Processes a marc holdings record and saves it.
 
         Args:
             idx (int): Index in file being parsed

folio_migration_tools/marc_rules_transformation/marc_reader_wrapper.py

@@ -1,3 +1,10 @@
+"""MARC record reader wrapper.
+
+Provides a wrapper around pymarc's MARCReader with enhanced error handling,
+encoding detection, and record validation. Supports multiple MARC file formats
+and handles corrupted records gracefully.
+"""
+
 import logging
 import sys
 from io import IOBase