mapping-suite-sdk 0.1.0__py3-none-any.whl

mapping_suite_sdk/adapters/extractor.py

@@ -0,0 +1,141 @@
+import tempfile
+import zipfile
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Generator, Protocol
+
+
+class Extractor(Protocol):
+    """Protocol defining the interface for file extract operations.
+
+    This protocol establishes a contract for classes that provide temporary file
+    extraction capabilities with automatic cleanup. Implementations must provide
+    a context manager that handles the extraction process and cleanup.
+    """
+
+    @staticmethod
+    @contextmanager
+    def extract_temporary(source_path: Path) -> Generator[Path, None, None]:
+        """Extract content to a temporary directory and yield its path.
+
+        This context manager should handle the extraction of files to a temporary
+        location and ensure proper cleanup after use.
+
+        Args:
+            source_path: Path to the source file to extract
+
+        Yields:
+            Path: Path to the temporary directory containing the extracted contents
+
+        Raises:
+            NotImplementedError: When the method is not implemented by a concrete class
+        """
+        raise NotImplementedError
+
+
+class ArchiveExtractor(Extractor):
+    """Implementation of Extractor protocol for ZIP file operations.
+
+    This class provides functionality to:
+    - Extract ZIP files to a temporary directory with automatic cleanup
+    - Pack directories into ZIP files without including the root directory name
+    """
+
+    @staticmethod
+    @contextmanager
+    def extract_temporary(archive_path: Path) -> Generator[Path, None, None]:
+        """Extract a ZIP archive to a temporary directory and yield its path.
+
+        This context manager handles the extraction of ZIP files to a temporary
+        location and ensures proper cleanup after use.
+
+        Args:
+            archive_path: Path to the ZIP file to extract
+
+        Yields:
+            Path: Path to the temporary directory containing the extracted contents
+
+        Raises:
+            FileNotFoundError: If the archive file doesn't exist
+            ValueError: If the path is not a file
+            zipfile.BadZipFile: If the file is not a valid ZIP archive
+
+        Example:
+            >>> from pathlib import Path
+            >>> archive_path = Path("example.zip")
+            >>> with ArchiveExtractor.extract_temporary(archive_path) as temp_path:
+            ...     # Work with extracted files in temp_path
+            ...     pass  # Cleanup is automatic after the with block
+        """
+        if not archive_path.exists():
+            raise FileNotFoundError(f"ZIP file not found: {archive_path}")
+
+        if not archive_path.is_file():
+            raise ValueError(f"Specified path is not a file: {archive_path}")
+
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_dir_path = Path(temp_dir)
+
+            try:
+                with zipfile.ZipFile(archive_path) as zip_ref:
+                    zip_ref.extractall(temp_dir_path)
+                yield temp_dir_path
+
+            except Exception as e:
+                raise ValueError(f"Failed to extract ZIP file: {e}")
+
+    @staticmethod
+    def pack_directory(source_dir: Path, output_path: Path) -> Path:
+        """Pack a directory's contents into a ZIP file without including the root directory name.
+
+        Creates a ZIP file containing the contents of the specified directory.
+        Files and subdirectories will be packed without the root directory name.
+        For example, if packing a directory 'my_folder' containing 'file1.txt' and
+        'subfolder/file2.txt', the ZIP will contain 'file1.txt' and 'subfolder/file2.txt'
+        directly, without 'my_folder' at the start.
+
+        Args:
+            source_dir: Path to the directory to pack
+            output_path: Path where the ZIP file should be created.
+                        If it doesn't end with '.zip', the extension will be added.
+
+        Returns:
+            Path: Path to the created ZIP file
+
+        Raises:
+            FileNotFoundError: If the source directory doesn't exist
+            ValueError: If the source is not a directory or if ZIP creation fails
+
+        Example:
+            >>> from pathlib import Path
+            >>> source_dir = Path("folder_to_archive")
+            >>> output_path = Path("output/archive")
+            >>> zip_path = ArchiveExtractor.pack_directory(source_dir, output_path)
+        """
+        if not source_dir.exists():
+            raise FileNotFoundError(f"Source directory not found: {source_dir}")
+
+        if not source_dir.is_dir():
+            raise ValueError(f"Specified path is not a directory: {source_dir}")
+
+        # Ensure the output directory exists
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Ensure the output path has .zip extension
+        if not str(output_path).endswith('.zip'):
+            output_path = output_path.with_suffix('.zip')
+
+        try:
+            with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zip_ref:
+                # Get all files in the directory
+                for file_path in source_dir.rglob('*'):
+                    if file_path.is_file():  # Skip directories, they're created automatically
+                        # Calculate the path relative to the source directory
+                        relative_path = file_path.relative_to(source_dir)
+                        # Add the file to the ZIP with the relative path as its name
+                        zip_ref.write(file_path, relative_path)
+
+            return output_path
+
+        except Exception as e:
+            raise ValueError(f"Failed to create ZIP file: {e}")

mapping_suite_sdk/adapters/loader.py

@@ -0,0 +1,296 @@
+from pathlib import Path
+from typing import Any, List, Protocol
+
+from pydantic import TypeAdapter
+
+from mapping_suite_sdk.models.asset import TechnicalMappingSuite, VocabularyMappingSuite, TestDataSuite, \
+    SAPRQLTestSuite, SHACLTestSuite, TestResultSuite, RMLMappingAsset, \
+    ConceptualMappingPackageAsset, VocabularyMappingAsset, TestDataAsset, SPARQLQueryAsset, SHACLShapesAsset
+from mapping_suite_sdk.models.mapping_package import MappingPackage, MappingPackageMetadata, MappingPackageIndex
+
+### Paths relative to mapping package
+RELATIVE_TECHNICAL_MAPPING_SUITE_PATH = Path("transformation/mappings")
+RELATIVE_VOCABULARY_MAPPING_SUITE_PATH = Path("transformation/resources")
+RELATIVE_TEST_DATA_PATH = Path("test_data")
+RELATIVE_SPARQL_SUITE_PATH = Path("validation/sparql")
+RELATIVE_SHACL_SUITE_PATH = Path("validation/shacl")
+RELATIVE_SUITE_METADATA_PATH = Path("metadata.json")
+RELATIVE_CONCEPTUAL_MAPPING_PATH = Path("transformation/conceptual_mappings.xlsx")
+
+
+class MappingPackageAssetLoader(Protocol):
+    """Protocol defining the interface for mapping package asset loaders.
+
+    This protocol ensures that all asset loaders implement a consistent interface
+    for loading different components of a mapping package.
+    """
+
+    def load(self, package_folder_path: Path) -> Any:
+        """Load an asset from the specified package folder path.
+
+        Args:
+            package_folder_path (Path): Path to the mapping package folder.
+
+        Returns:
+            Any: The loaded asset.
+
+        Raises:
+            NotImplementedError: When the method is not implemented by a concrete class.
+        """
+        raise NotImplementedError
+
+
+class TechnicalMappingSuiteLoader(MappingPackageAssetLoader):
+    """Loader for technical mapping suite files.
+
+    Handles loading of RML and YARRRML mapping files from the technical mapping suite directory.
+    """
+
+    def load(self, package_folder_path: Path) -> TechnicalMappingSuite:
+        """Load technical mapping files from the package.
+
+        Args:
+            package_folder_path (Path): Path to the mapping package folder.
+
+        Returns:
+            TechnicalMappingSuite: Collection of loaded RML and YARRRML mapping files.
+        """
+        tm_files: List[RMLMappingAsset] = []
+
+        for tm_file in (package_folder_path / RELATIVE_TECHNICAL_MAPPING_SUITE_PATH).iterdir():
+            if tm_file.is_file():
+                tm_files.append(
+                    RMLMappingAsset(path=tm_file.relative_to(package_folder_path), content=tm_file.read_text()))
+
+        return TechnicalMappingSuite(path=RELATIVE_TECHNICAL_MAPPING_SUITE_PATH, files=tm_files)
+
+
+class VocabularyMappingSuiteLoader(MappingPackageAssetLoader):
+    """Loader for vocabulary mapping suite files.
+
+    Loads vocabulary mapping files that define term mappings and transformations.
+    """
+
+    def load(self, package_folder_path: Path) -> VocabularyMappingSuite:
+        """Load vocabulary mapping files from the package.
+
+        Args:
+            package_folder_path (Path): Path to the mapping package folder.
+
+        Returns:
+            VocabularyMappingSuite: Collection of loaded vocabulary mapping files.
+        """
+        files: List[VocabularyMappingAsset] = []
+
+        for file in (package_folder_path / RELATIVE_VOCABULARY_MAPPING_SUITE_PATH).iterdir():
+            if file.is_file():
+                files.append(
+                    VocabularyMappingAsset(path=file.relative_to(package_folder_path), content=file.read_text()))
+
+        return VocabularyMappingSuite(path=RELATIVE_VOCABULARY_MAPPING_SUITE_PATH, files=files)
+
+
+class TestDataSuitesLoader(MappingPackageAssetLoader):
+    """Loader for test data suites.
+
+    Handles loading of test data files organized in test suites.
+    """
+
+    def load(self, package_folder_path: Path) -> List[TestDataSuite]:
+        """Load test data suites from the package.
+
+        Args:
+            package_folder_path (Path): Path to the mapping package folder.
+
+        Returns:
+            List[TestDataSuite]: List of test data suites, each containing test files.
+        """
+        test_data_suites: List[TestDataSuite] = []
+        for ts_suite in (package_folder_path / RELATIVE_TEST_DATA_PATH).iterdir():
+            if ts_suite.is_dir():
+                test_data_suites.append(TestDataSuite(path=ts_suite.relative_to(package_folder_path),
+                                                      files=[TestDataAsset(path=ts_file.relative_to(package_folder_path),
+                                                                           content=ts_file.read_text()) for ts_file in
+                                                             ts_suite.iterdir() if ts_file.is_file()]))
+        return test_data_suites
+
+
+class SPARQLTestSuitesLoader(MappingPackageAssetLoader):
+    """Loader for SPARQL test suites.
+
+    Handles loading of SPARQL query files organized in validation suites.
+    """
+
+    def load(self, package_folder_path: Path) -> List[SAPRQLTestSuite]:
+        """Load SPARQL validation suites from the package.
+
+        Args:
+            package_folder_path (Path): Path to the mapping package folder.
+
+        Returns:
+            List[SAPRQLTestSuite]: List of SPARQL validation suites.
+        """
+        sparql_validation_suites: List[SAPRQLTestSuite] = []
+        for sparql_suite in (package_folder_path / RELATIVE_SPARQL_SUITE_PATH).iterdir():
+            if sparql_suite.is_dir():
+                sparql_validation_suites.append(SAPRQLTestSuite(path=sparql_suite.relative_to(package_folder_path),
+                                                                files=[SPARQLQueryAsset(
+                                                                    path=ts_file.relative_to(package_folder_path),
+                                                                    content=ts_file.read_text()) for ts_file
+                                                                    in
+                                                                    sparql_suite.iterdir() if ts_file.is_file()]))
+        return sparql_validation_suites
+
+
+class SHACLTestSuitesLoader(MappingPackageAssetLoader):
+    """Loader for SHACL test suites.
+
+    Handles loading of SHACL shape files organized in validation suites.
+    """
+
+    def load(self, package_folder_path: Path) -> List[SHACLTestSuite]:
+        """Load SHACL validation suites from the package.
+
+        Args:
+            package_folder_path (Path): Path to the mapping package folder.
+
+        Returns:
+            List[SHACLTestSuite]: List of SHACL validation suites.
+        """
+        shacl_validation_suites: List[SHACLTestSuite] = []
+        for shacl_suite in (package_folder_path / RELATIVE_SHACL_SUITE_PATH).iterdir():
+            if shacl_suite.is_dir():
+                shacl_validation_suites.append(SHACLTestSuite(path=shacl_suite.relative_to(package_folder_path),
+                                                              files=[SHACLShapesAsset(
+                                                                  path=ts_file.relative_to(package_folder_path),
+                                                                  content=ts_file.read_text()) for ts_file
+                                                                  in
+                                                                  shacl_suite.iterdir() if ts_file.is_file()]))
+        return shacl_validation_suites
+
+
+class MappingPackageMetadataLoader(MappingPackageAssetLoader):
+    """Loader for mapping package metadata.
+
+    Handles loading and parsing of the package metadata JSON file.
+    """
+
+    def load(self, package_folder_path: Path) -> MappingPackageMetadata:
+        """Load metadata from the package's metadata.json file.
+
+        Args:
+            package_folder_path (Path): Path to the mapping package folder.
+
+        Returns:
+            MappingPackageMetadata: Parsed metadata object.
+        """
+        metadata_file_path: Path = package_folder_path / RELATIVE_SUITE_METADATA_PATH
+        return TypeAdapter(MappingPackageMetadata).validate_json(metadata_file_path.read_text())
+
+
+class MappingPackageIndexLoader(MappingPackageAssetLoader):
+    """Loader for mapping package index.
+
+    [Not implemented] Handles loading of package index information.
+    """
+
+    def load(self, package_folder_path: Path) -> MappingPackageIndex:
+        """Load the mapping package index.
+
+        Args:
+            package_folder_path (Path): Path to the mapping package folder.
+
+        Returns:
+            MappingPackageIndex: The loaded package index.
+
+        Raises:
+            NotImplementedError: This loader is not yet implemented.
+        """
+        raise NotImplementedError
+
+
+class TestResultSuiteLoader(MappingPackageAssetLoader):
+    """Loader for test result suite.
+
+    [Not implemented] Handles loading of test execution results.
+    """
+
+    def load(self, package_folder_path: Path) -> TestResultSuite:
+        """Load test result suite.
+
+        Args:
+            package_folder_path (Path): Path to the mapping package folder.
+
+        Returns:
+            TestResultSuite: The loaded test results.
+
+        Raises:
+            NotImplementedError: This loader is not yet implemented.
+        """
+        raise NotImplementedError
+
+
+class ConceptualMappingFileLoader(MappingPackageAssetLoader):
+    """Loader for conceptual mapping files.
+
+    Handles loading of conceptual mapping Excel files.
+    """
+
+    def load(self, package_folder_path: Path) -> ConceptualMappingPackageAsset:
+        """Load the conceptual mapping Excel file.
+
+        Args:
+            package_folder_path (Path): Path to the mapping package folder.
+
+        Returns:
+            ConceptualMappingPackageAsset: The loaded conceptual mapping file.
+        """
+        cm_file_path: Path = package_folder_path / RELATIVE_CONCEPTUAL_MAPPING_PATH
+
+        return ConceptualMappingPackageAsset(
+            path=RELATIVE_CONCEPTUAL_MAPPING_PATH,
+            content=cm_file_path.read_bytes()
+        )
+
+
+class MappingPackageLoader(MappingPackageAssetLoader):
+    """Main loader for complete mapping packages.
+
+    Coordinates the loading of all components of a mapping package using specialized loaders.
+    """
+
+    def load(self, package_folder_path: Path) -> MappingPackage:
+        """Load all components of a mapping package.
+
+        This method orchestrates the loading of:
+        - Package metadata
+        - Conceptual mapping file
+        - Technical mapping suite
+        - Vocabulary mapping suite
+        - Test data suites
+        - SPARQL test suites
+        - SHACL test suites
+
+        Args:
+            package_folder_path (Path): Path to the mapping package folder.
+
+        Returns:
+            MappingPackage: Complete mapping package with all loaded components.
+        """
+        metadata = MappingPackageMetadataLoader().load(package_folder_path)
+        conceptual_mapping_file = ConceptualMappingFileLoader().load(package_folder_path)
+        technical_mapping_suite = TechnicalMappingSuiteLoader().load(package_folder_path)
+        vocabulary_mapping_suite = VocabularyMappingSuiteLoader().load(package_folder_path)
+        test_data_suites = TestDataSuitesLoader().load(package_folder_path)
+        test_suites_sparql = SPARQLTestSuitesLoader().load(package_folder_path)
+        test_suites_shacl = SHACLTestSuitesLoader().load(package_folder_path)
+
+        return MappingPackage(
+            metadata=metadata,
+            conceptual_mapping_file=conceptual_mapping_file,
+            technical_mapping_suite=technical_mapping_suite,
+            vocabulary_mapping_suite=vocabulary_mapping_suite,
+            test_data_suites=test_data_suites,
+            test_suites_sparql=test_suites_sparql,
+            test_suites_shacl=test_suites_shacl
+        )

mapping_suite_sdk/adapters/serialiser.py

@@ -0,0 +1,146 @@
+from pathlib import Path
+from typing import Any, List, Protocol
+
+from mapping_suite_sdk.adapters.loader import RELATIVE_TECHNICAL_MAPPING_SUITE_PATH, RELATIVE_VOCABULARY_MAPPING_SUITE_PATH, \
+    RELATIVE_SUITE_METADATA_PATH, RELATIVE_CONCEPTUAL_MAPPING_PATH
+from mapping_suite_sdk.models.asset import (
+    TechnicalMappingSuite, VocabularyMappingSuite, TestDataSuite,
+    SAPRQLTestSuite, SHACLTestSuite, ConceptualMappingPackageAsset
+)
+from mapping_suite_sdk.models.mapping_package import MappingPackage, MappingPackageMetadata
+
+
+class MappingPackageAssetSerialiser(Protocol):
+    """Protocol defining the interface for mapping package asset serialisers.
+
+    This protocol ensures that all asset serialisers implement a consistent interface
+    for serializing different components of a mapping package.
+    """
+
+    def serialize(self, package_folder_path: Path, asset: Any) -> None:
+        """Serialize an asset to the specified package folder path.
+
+        Args:
+            package_folder_path (Path): Path to the mapping package folder.
+            asset (Any): The asset to serialize.
+
+        Raises:
+            NotImplementedError: When the method is not implemented by a concrete class.
+        """
+        raise NotImplementedError
+
+
+class TechnicalMappingSuiteSerialiser(MappingPackageAssetSerialiser):
+    """Serialiser for technical mapping suite files."""
+
+    def serialize(self, package_folder_path: Path, asset: TechnicalMappingSuite) -> None:
+        suite_path = package_folder_path / RELATIVE_TECHNICAL_MAPPING_SUITE_PATH
+        suite_path.mkdir(parents=True, exist_ok=True)
+
+        for tm_file in asset.files:
+            file_path = package_folder_path / tm_file.path
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+            file_path.write_text(tm_file.content)
+
+
+class VocabularyMappingSuiteSerialiser(MappingPackageAssetSerialiser):
+    """Serialiser for vocabulary mapping suite files."""
+
+    def serialize(self, package_folder_path: Path, asset: VocabularyMappingSuite) -> None:
+        suite_path = package_folder_path / RELATIVE_VOCABULARY_MAPPING_SUITE_PATH
+        suite_path.mkdir(parents=True, exist_ok=True)
+
+        for vm_file in asset.files:
+            file_path = package_folder_path / vm_file.path
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+            file_path.write_text(vm_file.content)
+
+
+class TestDataSuitesSerialiser(MappingPackageAssetSerialiser):
+    """Serialiser for test data suites."""
+
+    def serialize(self, package_folder_path: Path, asset: List[TestDataSuite]) -> None:
+        for suite in asset:
+            suite_path = package_folder_path / suite.path
+            suite_path.mkdir(parents=True, exist_ok=True)
+
+            for test_file in suite.files:
+                file_path = package_folder_path / test_file.path
+                file_path.parent.mkdir(parents=True, exist_ok=True)
+                file_path.write_text(test_file.content)
+
+
+class SPARQLTestSuitesSerialiser(MappingPackageAssetSerialiser):
+    """Serialiser for SPARQL test suites."""
+
+    def serialize(self, package_folder_path: Path, asset: List[SAPRQLTestSuite]) -> None:
+        for suite in asset:
+            suite_path = package_folder_path / suite.path
+            suite_path.mkdir(parents=True, exist_ok=True)
+
+            for query_file in suite.files:
+                file_path = package_folder_path / query_file.path
+                file_path.parent.mkdir(parents=True, exist_ok=True)
+                file_path.write_text(query_file.content)
+
+
+class SHACLTestSuitesSerialiser(MappingPackageAssetSerialiser):
+    """Serialiser for SHACL test suites."""
+
+    def serialize(self, package_folder_path: Path, asset: List[SHACLTestSuite]) -> None:
+        for suite in asset:
+            suite_path = package_folder_path / suite.path
+            suite_path.mkdir(parents=True, exist_ok=True)
+
+            for shape_file in suite.files:
+                file_path = package_folder_path / shape_file.path
+                file_path.parent.mkdir(parents=True, exist_ok=True)
+                file_path.write_text(shape_file.content)
+
+
+class MappingPackageMetadataSerialiser(MappingPackageAssetSerialiser):
+    """Serialiser for mapping package metadata."""
+
+    def serialize(self, package_folder_path: Path, asset: MappingPackageMetadata) -> None:
+        metadata_path = package_folder_path / RELATIVE_SUITE_METADATA_PATH
+        metadata_path.parent.mkdir(parents=True, exist_ok=True)
+        metadata_path.write_text(asset.model_dump_json(by_alias=True))
+
+
+class ConceptualMappingFileSerialiser(MappingPackageAssetSerialiser):
+    """Serialiser for conceptual mapping files."""
+
+    def serialize(self, package_folder_path: Path, asset: ConceptualMappingPackageAsset) -> None:
+        file_path = package_folder_path / RELATIVE_CONCEPTUAL_MAPPING_PATH
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_bytes(asset.content)
+
+
+class MappingPackageSerialiser(MappingPackageAssetSerialiser):
+    """Main serialiser for complete mapping packages."""
+
+    def serialize(self, package_folder_path: Path, asset: MappingPackage) -> None:
+        """Serialize all components of a mapping package.
+
+        This method orchestrates the serialization of:
+        - Package metadata
+        - Conceptual mapping file
+        - Technical mapping suite
+        - Vocabulary mapping suite
+        - Test data suites
+        - SPARQL test suites
+        - SHACL test suites
+
+        Args:
+            package_folder_path (Path): Path to the mapping package folder.
+            asset (MappingPackage): Complete mapping package to serialize.
+        """
+
+        # Serialize each component
+        MappingPackageMetadataSerialiser().serialize(package_folder_path, asset.metadata)
+        ConceptualMappingFileSerialiser().serialize(package_folder_path, asset.conceptual_mapping_file)
+        TechnicalMappingSuiteSerialiser().serialize(package_folder_path, asset.technical_mapping_suite)
+        VocabularyMappingSuiteSerialiser().serialize(package_folder_path, asset.vocabulary_mapping_suite)
+        TestDataSuitesSerialiser().serialize(package_folder_path, asset.test_data_suites)
+        SPARQLTestSuitesSerialiser().serialize(package_folder_path, asset.test_suites_sparql)
+        SHACLTestSuitesSerialiser().serialize(package_folder_path, asset.test_suites_shacl)