cognite-neat 0.123.26__py3-none-any.whl → 1.0.22__py3-none-any.whl

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

@@ -1,335 +0,0 @@
-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.26.dist-info/METADATA

@@ -1,144 +0,0 @@
-Metadata-Version: 2.4
-Name: cognite-neat
-Version: 0.123.26
-Summary: Knowledge graph transformation
-Project-URL: Documentation, https://cognite-neat.readthedocs-hosted.com/
-Project-URL: Homepage, https://cognite-neat.readthedocs-hosted.com/
-Project-URL: GitHub, https://github.com/cognitedata/neat
-Project-URL: Changelog, https://github.com/cognitedata/neat/releases
-Author-email: Nikola Vasiljevic <nikola.vasiljevic@cognite.com>, Anders Albert <anders.albert@cognite.com>, Rogerio Júnior <rogerio.junior@cognite.com>
-License-Expression: Apache-2.0
-License-File: LICENSE
-Requires-Python: >=3.10
-Requires-Dist: backports-strenum<2.0.0,>=1.2; python_version < '3.11'
-Requires-Dist: cognite-sdk<8.0.0,>=7.73.4
-Requires-Dist: elementpath<5.0.0,>=4.0.0
-Requires-Dist: exceptiongroup<2.0.0,>=1.1.3; python_version < '3.11'
-Requires-Dist: jsonpath-python<2.0.0,>=1.0.6
-Requires-Dist: mixpanel<5.0.0,>=4.10.1
-Requires-Dist: networkx<4.0.0,>=3.4.2
-Requires-Dist: openpyxl<4.0.0,>=3.0.10
-Requires-Dist: packaging<25.0,>=22.0
-Requires-Dist: pandas<3.0.0,>=1.5.3
-Requires-Dist: pydantic<3.0.0,>=2.0.0
-Requires-Dist: pyvis<1.0.0,>=0.3.2
-Requires-Dist: pyyaml<7.0.0,>=6.0.1
-Requires-Dist: rdflib<8.0.0,>=7.0.0
-Requires-Dist: requests<3.0.0,>=2.28.1
-Requires-Dist: rich[jupyter]<14.0.0,>=13.7.1
-Requires-Dist: tomli<3.0.0,>=2.0.1; python_version < '3.11'
-Requires-Dist: typing-extensions<5.0.0,>=4.8.0; python_version < '3.11'
-Requires-Dist: urllib3<3.0.0,>=1.26.15
-Provides-Extra: docs
-Requires-Dist: mistune==3.0.2; extra == 'docs'
-Requires-Dist: mkdocs-autorefs<1.0.0,>=0.5.0; extra == 'docs'
-Requires-Dist: mkdocs-git-authors-plugin<1.0.0,>=0.9.4; extra == 'docs'
-Requires-Dist: mkdocs-git-revision-date-localized-plugin; extra == 'docs'
-Requires-Dist: mkdocs-gitbook<1.0.0,>=0.0.1; extra == 'docs'
-Requires-Dist: mkdocs-glightbox<1.0.0,>=0.4.0; extra == 'docs'
-Requires-Dist: mkdocs-jupyter<1.0.0,>=0.25.1; extra == 'docs'
-Requires-Dist: mkdocs-material-extensions<2.0.0,>=1.3.1; extra == 'docs'
-Requires-Dist: mkdocs<2.0.0,>=1.4.0; extra == 'docs'
-Requires-Dist: mkdocstrings[python]<1.0.0,>=0.25.2; extra == 'docs'
-Requires-Dist: pymdown-extensions<11.0.0,>=10.14.3; extra == 'docs'
-Provides-Extra: google
-Requires-Dist: google-api-python-client<3.0.0,>=2.70.0; extra == 'google'
-Requires-Dist: google-auth-oauthlib<2.0.0,>=1.0.0; extra == 'google'
-Requires-Dist: gspread<6.0.0,>=5.0.0; extra == 'google'
-Provides-Extra: lxml
-Requires-Dist: lxml<6.0.0,>=5.3.0; extra == 'lxml'
-Provides-Extra: oxi
-Requires-Dist: oxrdflib<0.5.0,>=0.4.0; extra == 'oxi'
-Requires-Dist: pyoxigraph<0.5.0,>=0.4.3; extra == 'oxi'
-Description-Content-Type: text/markdown
-
-# kNowlEdge grAph Transformer (NEAT)
-
-[![release](https://img.shields.io/github/actions/workflow/status/cognitedata/neat/release.yaml?style=for-the-badge)](https://github.com/cognitedata/neat/actions/workflows/release.yaml)
-[![Documentation Status](https://readthedocs.com/projects/cognite-neat/badge/?version=latest&style=for-the-badge)](https://cognite-neat.readthedocs-hosted.com/en/latest/?badge=latest)
-[![Github](https://shields.io/badge/github-cognite/neat-green?logo=github&style=for-the-badge)](https://github.com/cognitedata/neat)
-[![PyPI](https://img.shields.io/pypi/v/cognite-neat?style=for-the-badge)](https://pypi.org/project/cognite-neat/)
-[![Downloads](https://img.shields.io/pypi/dm/cognite-neat?style=for-the-badge)](https://pypistats.org/packages/cognite-neat)
-[![Docker Pulls](https://img.shields.io/docker/pulls/cognite/neat?style=for-the-badge)](https://hub.docker.com/r/cognite/neat)
-[![GitHub](https://img.shields.io/github/license/cognitedata/neat?style=for-the-badge)](https://github.com/cognitedata/neat/blob/master/LICENSE)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge)](https://github.com/ambv/black)
-[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json&style=for-the-badge)](https://github.com/astral-sh/ruff)
-[![mypy](https://img.shields.io/badge/mypy-checked-000000.svg?style=for-the-badge&color=blue)](http://mypy-lang.org)
-
-NEAT is a domain expert centric and developer friendly solution for rapid:
-
-- data modeling
-- extraction, transformation and loading of instances
-- and ingestion of the models and instances (i.e. knowledge graphs) into [Cognite Data Fusion](https://www.cognite.com/en/product/cognite_data_fusion_industrial_dataops_platform)
-
-NEAT is using open and globally recognized standards maintained by the [World Wide Web Consortium (W3C)](https://www.w3.org/RDF/).
-NEAT represents an essential tool for creation of standardized, machine-actionable, linked and semantic (meta)data.
-
-> NEAT is a funny acronym derived from k**N**owl**Ed**ge gr**A**ph **T**ransformer produced using [ACRONIMIFY](https://acronymify.com/NEAT/?q=knowledge+graph+transformer).
-
-
-## History
-
-NEAT emerged from years of experience in semantic tooling and knowledge graph development. The foundation was laid in 2020 with [sheet2rdf](https://github.com/nikokaoja/sheet2rdf), an Excel-based tool that trained data stewards to build domain-specific knowledge graphs and supported CI/CD processes in the Dutch Covid program and european wind energy community.
-
-By mid of 2022, sheet2rdf was used in several POCs in Cognite. As Cognite's Data Modeling Service (DMS) development progressed, the need for simplified data modeling experience led to demonstration of proto-NEAT, known as [sheet2fdm](https://github.com/cognitedata/sheet2fdm), an extension of sheet2rdf, enabling semantic data model definitions in OWL, SHACL, Python and GraphQL (see e.g., [wind energy data model](https://cognitedata.github.io/wind-energy-data-model/)) using a simplified version of sheet2rdf Excel template.
-
-Presented in various forums in 2022, this approach paved the way for NEAT’s formal development in November 2022 to enable cost-saving and empowerment of Cognite customers to self-sufficiently maintain and onboard knowledge graphs to Cognite Data Fusion.
-
-## Authorship
-
-### Authors
-The plot below shows the NEAT authorship from the start until present day.
-
-![NEAT authorship](./artifacts/figs/authorship.png)
-
-#### Current authors
-- [Nikola Vasiljević](www.linkedin.com/in/thisisnikola)
-- [Anders Albert](https://www.linkedin.com/in/anders-albert-00790483/)
-- [Rogerio Júnior](https://www.linkedin.com/in/rogerio-saboia-j%C3%BAnior-087118a7/)
-
-#### Former authors
-- [Aleksandrs Livincovs](https://www.linkedin.com/in/aleksandrslivincovs/)
-- [Julia Graham](https://www.linkedin.com/in/julia-graham-959a78a7/)
-
-### Contributors
-We are very grateful for the contributions made by:
-
-
-- [Marie Solvik Lepoutre](https://www.linkedin.com/in/mslepoutre/), who improved RDF triples projections to Cognite Data Fusion
-- [Bård Henning Tvedt](https://www.linkedin.com/in/bhtvedt/), who implemented IMF importer
-- [Hassan Gomaa](https://www.linkedin.com/in/dr-hassan-gomaa-232638121/), who extended the DEXPI extractor
-- [Kristina Tomičić](https://www.linkedin.com/in/kristina-tomicic-6bb443108/), who implemented Data Model and Instances visualization
-
-
-## Sponsors
-NEAT is developed and maintained by Cognite. We are grateful for the past support of our sponsors, who funded us to develop NEAT and to make it open source.
-
-- [Statnett](https://www.statnett.no/) - the MIMIR team ([Ola Hagen Øyan](https://www.linkedin.com/in/ola-%C3%B8yan-b0205b19/), [Olav Westeng Alstad](https://www.linkedin.com/in/olav-w-alstad-52329191/),[Andreas Kimsås](https://www.linkedin.com/in/andreas-kims%C3%A5s-964a0b2/) and [Anders Willersrud](https://www.linkedin.com/in/anders-willersrud-13a20220/)) – who supported the development of NEAT from end of 2022 to mid of 2023 and its integration with Statnett's infrastructure, where NEAT was battle-tested as a tool for non-sematic experts to define data models and transform large knowledge graphs representing the entire Norwegian power grid system. Without Statnett's support NEAT would not exist in the first place, and would not be open-source.
-- [Aker Solutions](https://www.akersolutions.com/) – the IMod Team (currently lead by [Maria Kenderkova](https://www.linkedin.com/in/maria-kenderkova/)), who funded development of NEAT from mid of 2023 till end of 2024 (multi-level and role-based data modeling, support for ontologies, IMF, DEXPI, AML,...) , as well who were early adopters and embraced NEAT and who were patient with us when things did not work so well. Aker Solutions was instrumental to elevating NEAT to a product level, and who selflessly advocate for NEAT globally.
-
-
-## Installation
-
-```bash
-pip install cognite-neat
-```
-
-## Usage
-
-The user interface for `NEAT` is a notebook-based environment. Once you have set up your notebook
-environment, you start by creating a `CogniteClient` and instantiate a `NeatSession` object.
-
-```python
-from cognite.neat import NeatSession, get_cognite_client
-
-client = get_cognite_client(".env")
-
-neat = NeatSession(client)
-
-neat.read.cdf.data_model(("my_space", "MyDataModel", "v1"))
-```
-
-## Documentation
-
-For more information, see the [documentation](https://cognite-neat.readthedocs-hosted.com/en/latest/)