cognite-neat 0.123.22__py3-none-any.whl → 0.123.23__py3-none-any.whl

cognite/neat/_version.py

@@ -1,2 +1,2 @@
-__version__ = "0.123.22"
+__version__ = "0.123.23"
 __engine__ = "^2.0.4"

cognite/neat/core/_utils/auxiliary.py

@@ -161,3 +161,9 @@ def get_parameters_by_method(obj: object, prefix: str = "") -> dict[str, dict[st
 def get_parameters(obj: Callable) -> dict[str, type]:
     annotations = inspect.get_annotations(obj)
     return {name: annotations[name] for name in annotations if name != "return"}
+
+
+def filter_kwargs_by_method(kwargs: dict[str, Any], method: Callable) -> dict[str, Any]:
+    """Filter kwargs by method parameters."""
+    signature = inspect.signature(method)
+    return {k: v for k, v in kwargs.items() if k in signature.parameters}

cognite/neat/session/_session/_data_model/_routes.py

@@ -2,6 +2,7 @@ from cognite.neat.core._data_model.models.conceptual._verified import Conceptual
 from cognite.neat.core._data_model.models.physical._verified import PhysicalDataModel
 from cognite.neat.session._session._data_model._read import ReadAPI
 from cognite.neat.session._session._data_model._show import ShowAPI
+from cognite.neat.session._session._data_model._write import WriteAPI
 from cognite.neat.session._state import SessionState
 from cognite.neat.session.exceptions import session_class_wrapper
 
@@ -13,6 +14,7 @@ class DataModelAPI:
     def __init__(self, state: SessionState) -> None:
         self._state = state
         self.read = ReadAPI(state)
+        self.write = WriteAPI(state)
         self.show = ShowAPI(state)
 
     @property

cognite/neat/session/_session/_data_model/_write.py

@@ -0,0 +1,335 @@
+import warnings
+from pathlib import Path
+from typing import Any, Literal, cast, overload
+
+from cognite.client.data_classes.data_modeling import DataModelIdentifier
+
+from cognite.neat.core._client._api_client import NeatClient
+from cognite.neat.core._constants import COGNITE_MODELS
+from cognite.neat.core._data_model import exporters
+from cognite.neat.core._data_model._shared import VerifiedDataModel
+from cognite.neat.core._data_model.importers._dms2data_model import DMSImporter
+from cognite.neat.core._data_model.models.conceptual._verified import ConceptualDataModel
+from cognite.neat.core._data_model.models.physical._verified import PhysicalDataModel, PhysicalMetadata
+from cognite.neat.core._issues._base import IssueList
+from cognite.neat.core._issues._contextmanagers import catch_issues
+from cognite.neat.core._utils.auxiliary import filter_kwargs_by_method
+from cognite.neat.core._utils.reader._base import NeatReader
+from cognite.neat.core._utils.upload import UploadResultList
+from cognite.neat.session._state import SessionState
+from cognite.neat.session.exceptions import NeatSessionError, session_class_wrapper
+
+InternalWriterName = Literal["excel", "ontology", "shacl", "cdf", "yaml"]
+
+
+@session_class_wrapper
+class WriteAPI:
+    def __init__(self, state: SessionState) -> None:
+        self._state = state
+
+    def __call__(
+        self, name: str, io: str | Path | None = None, **kwargs: Any
+    ) -> str | UploadResultList | IssueList | None:
+        """Provides access to the writers for exporting data models to different formats.
+
+        Args:
+            name (str): The name of format (e.g. Excel) writer is handling.
+            io (str | Path | None): The input/output interface for the writer.
+            **kwargs (Any): Additional keyword arguments for the writer.
+
+        !!! note "kwargs"
+            Users must consult the documentation of the writer
+            to understand what keyword arguments are supported.
+        """
+
+        # Clean the input name once before matching.
+        clean_name: InternalWriterName | str = name.strip().lower()
+
+        match clean_name:
+            case "excel":
+                if io is None:
+                    raise NeatSessionError("'io' parameter is required for Excel format.")
+                return self.excel(cast(str | Path, io), **filter_kwargs_by_method(kwargs, self.excel))
+            case "cdf":
+                return self.cdf(**filter_kwargs_by_method(kwargs, self.cdf))
+            case "yaml":
+                return self.yaml(io, **filter_kwargs_by_method(kwargs, self.yaml))
+            case "ontology":
+                if io is None:
+                    raise NeatSessionError("'io' parameter is required for ontology format.")
+                self.ontology(cast(str | Path, io))
+                return None
+            case "shacl":
+                if io is None:
+                    raise NeatSessionError("'io' parameter is required for SHACL format.")
+                self.shacl(cast(str | Path, io))
+                return None
+            case _:
+                raise NeatSessionError(
+                    f"Unsupported data model writer: {name}. "
+                    "Please use one of the following: 'excel', 'cdf', 'yaml', 'ontology', 'shacl'."
+                )
+
+    def excel(
+        self,
+        io: str | Path,
+        *,
+        include_reference: bool | DataModelIdentifier = True,
+        include_properties: Literal["same-space", "all"] = "all",
+        add_empty_rows: bool = False,
+    ) -> IssueList | None:
+        """Export the verified data model to Excel.
+
+        Args:
+            io: The file path or file-like object to write the Excel file to.
+            include_reference: If True, the reference data model will be included. Defaults to True.
+                Note that this only applies if you have created the data model using the
+                create.enterprise_model(...), create.solution_model(), or create.data_product_model() methods.
+                You can also provide a DataModelIdentifier directly, which will be read from CDF
+            include_properties: The properties to include in the Excel file. Defaults to "all".
+                - "same-space": Only properties that are in the same space as the data model will be included.
+            add_empty_rows: If True, empty rows will be added between each component. Defaults to False.
+
+        Example:
+            Export conceptual data model to an Excel file
+            ```python
+            conceptual_dm_file_name = "conceptual_data_model.xlsx"
+            neat.data_model.write.excel(conceptual_dm_file_name)
+            ```
+
+        Example:
+            Read CogniteCore model, convert it to an enterprise model, and export it to an excel file
+            ```python
+            client = CogniteClient()
+            neat = NeatSession(client)
+
+            neat.data_model.read.cdf(("cdf_cdm", "CogniteCore", "v1"))
+            neat.data_model.create.enterprise_model(
+                data_model_id=("sp_doctrino_space", "ExtensionCore", "v1"),
+                org_name="MyOrg",
+            )
+            physical_dm_file_name = "physical_dm.xlsx"
+            neat.data_model.write.excel(physical_dm_file_name, include_reference=True)
+            ```
+
+        Example:
+            Read the data model ("my_space", "ISA95Model", "v5") and export it to an excel file with the
+            CogniteCore model in the reference sheets.
+            ```python
+            client = CogniteClient()
+            neat = NeatSession(client)
+
+            neat.data_model.read.cdf(("my_space", "ISA95Model", "v5"))
+            physical_dm_file_name = "physical_dm.xlsx"
+            neat.data_model.write.excel(physical_dm_file_name, include_reference=("cdf_cdm", "CogniteCore", "v1"))
+        """
+        reference_data_model_with_prefix: tuple[VerifiedDataModel, str] | None = None
+        include_properties = include_properties.strip().lower()
+        if include_properties not in ["same-space", "all"]:
+            raise NeatSessionError(
+                f"Invalid include_properties value: '{include_properties}'. Must be 'same-space' or 'all'."
+            )
+
+        if include_reference is not False:
+            if include_reference is True and self._state.last_reference is not None:
+                ref_data_model: ConceptualDataModel | PhysicalDataModel | None = self._state.last_reference
+            elif include_reference is True:
+                ref_data_model = None
+            else:
+                if not self._state.client:
+                    raise NeatSessionError("No client provided!")
+                ref_data_model = None
+                with catch_issues() as issues:
+                    ref_read = DMSImporter.from_data_model_id(self._state.client, include_reference).to_data_model()
+                    if ref_read.unverified_data_model is not None:
+                        ref_data_model = ref_read.unverified_data_model.as_verified_data_model()
+                if ref_data_model is None or issues.has_errors:
+                    issues.action = f"Read {include_reference}"
+                    return issues
+            if ref_data_model is not None:
+                prefix = "Ref"
+                if (
+                    isinstance(ref_data_model.metadata, PhysicalMetadata)
+                    and ref_data_model.metadata.as_data_model_id() in COGNITE_MODELS
+                ):
+                    prefix = "CDM"
+                reference_data_model_with_prefix = ref_data_model, prefix
+
+        exporter = exporters.ExcelExporter(
+            styling="maximal",
+            reference_data_model_with_prefix=reference_data_model_with_prefix,
+            add_empty_rows=add_empty_rows,
+            include_properties=cast(Literal["same-space", "all"], include_properties),
+        )
+        self._state.data_model_store.export_to_file(exporter, NeatReader.create(io).materialize_path())
+        return None
+
+    def cdf(
+        self,
+        *,
+        existing: Literal["fail", "skip", "update", "force", "recreate"] = "update",
+        dry_run: bool = False,
+        drop_data: bool = False,
+    ) -> UploadResultList:
+        """Export the verified DMS data model to CDF.
+
+        Args:
+            existing: What to do if the component already exists. Defaults to "update".
+                See the note below for more information about the options.
+            dry_run: If True, no changes will be made to CDF. Defaults to False.
+            drop_data: If existing is 'force' or 'recreate' and the operation will lead to data loss,
+                the component will be skipped unless drop_data is True. Defaults to False.
+                Note this only applies to spaces and containers if they contain data.
+
+        !!! note "Data Model creation modes"
+            - "fail": If any component already exists, the export will fail.
+            - "skip": If any component already exists, it will be skipped.
+            - "update": If any component already exists, it will be updated. For data models, views, and containers
+                this means combining the existing and new component. Fo example, for data models the new
+                views will be added to the existing views.
+            - "force": If any component already exists, and the update fails, it will be deleted and recreated.
+            - "recreate": All components will be deleted and recreated. The exception is spaces, which will be updated.
+
+        """
+
+        self._state._raise_exception_if_condition_not_met(
+            "Export DMS data model to CDF",
+            client_required=True,
+        )
+
+        exporter = exporters.DMSExporter(existing=existing, drop_data=drop_data)
+
+        result = self._state.data_model_store.export_to_cdf(exporter, cast(NeatClient, self._state.client), dry_run)
+        print("You can inspect the details with the .inspect.outcome.data_model(...) method.")
+        return result
+
+    @overload
+    def yaml(
+        self,
+        io: None,
+        *,
+        format: Literal["neat", "toolkit"] = "neat",
+        skip_system_spaces: bool = True,
+    ) -> str: ...
+
+    @overload
+    def yaml(
+        self,
+        io: str | Path,
+        *,
+        format: Literal["neat", "toolkit"] = "neat",
+        skip_system_spaces: bool = True,
+    ) -> None: ...
+
+    def yaml(
+        self,
+        io: str | Path | None = None,
+        *,
+        format: Literal["neat", "toolkit"] = "neat",
+        skip_system_spaces: bool = True,
+    ) -> str | None:
+        """Export the verified data model to YAML.
+
+        Args:
+            io: The file path or file-like object to write the YAML file to. Defaults to None.
+            format: The format of the YAML file. Defaults to "neat".
+            skip_system_spaces: If True, system spaces will be skipped. Defaults to True.
+
+        !!! note "YAML formats"
+            - "neat": This is the format Neat uses to store the data model.
+            - "toolkit": This is the format used by Cognite Toolkit, that matches the CDF API.
+
+        Returns:
+            str | None: If io is None, the YAML string will be returned. Otherwise, None will be returned.
+
+        Example:
+            Export to yaml file in the case of "neat" format
+            ```python
+            your_yaml_file_name = "neat_dm.yaml"
+            neat.data_model.write.yaml(your_yaml_file_name, format="neat")
+            ```
+
+        Example:
+            Export yaml files as a zip folder in the case of "toolkit" format
+            ```python
+            your_zip_folder_name = "toolkit_data_model_files.zip"
+            neat.data_model.write.yaml(your_zip_folder_name, format="toolkit")
+            ```
+
+        Example:
+            Export yaml files to a folder in the case of "toolkit" format
+            ```python
+            your_folder_name = "my_project/data_model_files"
+            neat.data_model.write.yaml(your_folder_name, format="toolkit")
+            ```
+        """
+
+        if format == "neat":
+            exporter = exporters.YAMLExporter()
+            if io is None:
+                return self._state.data_model_store.export(exporter)
+
+            self._state.data_model_store.export_to_file(exporter, NeatReader.create(io).materialize_path())
+        elif format == "toolkit":
+            if io is None:
+                raise NeatSessionError(
+                    "Please provide a zip file or directory path to write the YAML files to."
+                    "This is required for the 'toolkit' format."
+                )
+            user_path = NeatReader.create(io).materialize_path()
+            if user_path.suffix == "" and not user_path.exists():
+                user_path.mkdir(parents=True)
+            self._state.data_model_store.export_to_file(
+                exporters.DMSExporter(remove_cdf_spaces=skip_system_spaces), user_path
+            )
+        else:
+            raise NeatSessionError("Please provide a valid format. 'neat' or 'toolkit'")
+
+        return None
+
+    def ontology(self, io: str | Path) -> None:
+        """Write out data model as OWL ontology.
+
+        Args:
+            io: The file path to file-like object to write the session to.
+
+        Example:
+            Export the session to a file
+            ```python
+            ontology_file_name = "neat_session.ttl"
+            neat.data_model.write.ontology(ontology_file_name)
+            ```
+        """
+
+        filepath = self._prepare_ttl_filepath(io)
+        exporter = exporters.OWLExporter()
+        self._state.data_model_store.export_to_file(exporter, filepath)
+        return None
+
+    def shacl(self, io: str | Path) -> None:
+        """Write out data model as SHACL shapes.
+
+        Args:
+            io: The file path to file-like object to write the session to.
+
+        Example:
+            Export the session to a file
+            ```python
+            shacl_file_name = "neat_session.shacl.ttl"
+            neat.data_model.write.shacl(shacl_file_name)
+            ```
+        """
+
+        filepath = self._prepare_ttl_filepath(io)
+        exporter = exporters.SHACLExporter()
+        self._state.data_model_store.export_to_file(exporter, filepath)
+        return None
+
+    def _prepare_ttl_filepath(self, io: str | Path) -> Path:
+        """Ensures the filepath has a .ttl extension, adding it if missing."""
+        filepath = NeatReader.create(io).materialize_path()
+        if filepath.suffix != ".ttl":
+            warnings.filterwarnings("default")
+            warnings.warn("File extension is not .ttl, adding it to the file name", stacklevel=2)
+            filepath = filepath.with_suffix(".ttl")
+        return filepath

{cognite_neat-0.123.22.dist-info → cognite_neat-0.123.23.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cognite-neat
-Version: 0.123.22
+Version: 0.123.23
 Summary: Knowledge graph transformation
 Project-URL: Documentation, https://cognite-neat.readthedocs-hosted.com/
 Project-URL: Homepage, https://cognite-neat.readthedocs-hosted.com/

{cognite_neat-0.123.22.dist-info → cognite_neat-0.123.23.dist-info}/RECORD

@@ -1,5 +1,5 @@
 cognite/neat/__init__.py,sha256=12StS1dzH9_MElqxGvLWrNsxCJl9Hv8A2a9D0E5OD_U,193
-cognite/neat/_version.py,sha256=F_PTAPIzLmGDm4RPxIsNpijbHtxGJrALannZQ5hHcUY,47
+cognite/neat/_version.py,sha256=0ecHvh-Qq-gIDd9cT8TLmFo99So1sxYnycVfCgckPL8,47
 cognite/neat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cognite/neat/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cognite/neat/core/_config.py,sha256=WT1BS8uADcFvGoUYOOfwFOVq_VBl472TisdoA3wLick,280
@@ -145,7 +145,7 @@ cognite/neat/core/_store/_provenance.py,sha256=aMEsq27dZ4NZ6XEC8hA0fIDF13i1ZP3Qw
 cognite/neat/core/_store/exceptions.py,sha256=jcd1Gv65mfTdC4cipFAMWUNghEmdLS_lwPH1FB_ebxI,1656
 cognite/neat/core/_utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cognite/neat/core/_utils/auth.py,sha256=tP_diUZdtacUkM8TLlbSOyHlNcq9VGh-4o_7myWRU_o,14763
-cognite/neat/core/_utils/auxiliary.py,sha256=nQAvIysrtigDTefuxTRGFiNUUBYy-iSDJPhvw-6RB50,6859
+cognite/neat/core/_utils/auxiliary.py,sha256=FpeVlscVue4QFaUM3jt7LLiAMkiec6IvpYrPlDUzKM8,7112
 cognite/neat/core/_utils/collection_.py,sha256=zVrSmm4045pjw6Pt6y4VPTIJ4dXdMJPyOV70LdFyDBM,2376
 cognite/neat/core/_utils/graph_transformations_report.py,sha256=ORVH7lw357TPOq4elU5lH46Qx6GCLVrSj-1nX6Ggk1U,1235
 cognite/neat/core/_utils/io_.py,sha256=D2Mg8sOxfBoDg3fC0jBzaxO3vkXmr0QvZSgYIv6xRkM,386
@@ -187,14 +187,15 @@ cognite/neat/session/exceptions.py,sha256=z5jxwfVTXDCCFZKTTYVIaksNKqb9CMa2tyIZgy
 cognite/neat/session/_session/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cognite/neat/session/_session/_data_model/__init__.py,sha256=417QF6wm3r-bLTmhYGXL_5XnEFShCklLCoGg3YBOIqY,62
 cognite/neat/session/_session/_data_model/_read.py,sha256=B_mVOt_9uKzG5vbrZG2Uf5D0FQGjcCDEdfAhIp2veUI,7902
-cognite/neat/session/_session/_data_model/_routes.py,sha256=wF83vLtmgyGCM2zxnHq0m3-sPQXQamObc58u2kSN7nQ,1666
+cognite/neat/session/_session/_data_model/_routes.py,sha256=FtCMbqvji2KqAPDkZ4yXXp_Fuf6mSFTpNRyVfWOMzFE,1773
 cognite/neat/session/_session/_data_model/_show.py,sha256=yX4BTIeBzcCcllfJvGm8g4qy13heFmcJtpXPixI8T2o,5835
+cognite/neat/session/_session/_data_model/_write.py,sha256=qpb15cnGLknkDkxKndpdvLxhsmJ4XkXfuFD4-CDw0qE,14612
 cognite/neat/session/_state/README.md,sha256=o6N7EL98lgyWffw8IoEUf2KG5uSKveD5__TW45YzVjA,902
 cognite/neat/session/engine/__init__.py,sha256=D3MxUorEs6-NtgoICqtZ8PISQrjrr4dvca6n48bu_bI,120
 cognite/neat/session/engine/_import.py,sha256=1QxA2_EK613lXYAHKQbZyw2yjo5P9XuiX4Z6_6-WMNQ,169
 cognite/neat/session/engine/_interface.py,sha256=3W-cYr493c_mW3P5O6MKN1xEQg3cA7NHR_ev3zdF9Vk,533
 cognite/neat/session/engine/_load.py,sha256=g52uYakQM03VqHt_RDHtpHso1-mFFifH5M4T2ScuH8A,5198
-cognite_neat-0.123.22.dist-info/METADATA,sha256=cIvYIW2976HqHJSdiseJuSEG3om5ldv2Z-csEbZQt6Y,9172
-cognite_neat-0.123.22.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-cognite_neat-0.123.22.dist-info/licenses/LICENSE,sha256=W8VmvFia4WHa3Gqxq1Ygrq85McUNqIGDVgtdvzT-XqA,11351
-cognite_neat-0.123.22.dist-info/RECORD,,
+cognite_neat-0.123.23.dist-info/METADATA,sha256=f78SKr8-LucvAchjKK1niKDLVAWwdadAm5x4dOdl_5s,9172
+cognite_neat-0.123.23.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+cognite_neat-0.123.23.dist-info/licenses/LICENSE,sha256=W8VmvFia4WHa3Gqxq1Ygrq85McUNqIGDVgtdvzT-XqA,11351
+cognite_neat-0.123.23.dist-info/RECORD,,