fairgraph 0.13.0__py3-none-any.whl

fairgraph/collection.py

@@ -0,0 +1,104 @@
+"""
+This module provides the Collection class, an extension to the openMINDS Collection
+that knows how to upload metadata to the KG.
+"""
+
+# Copyright 2018-2024 CNRS
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from importlib import import_module
+import os
+from time import sleep
+from uuid import uuid4
+from warnings import warn
+
+from openminds import Collection as OMCollection
+from .utility import ActivityLog
+from .errors import AuthenticationError
+
+
+class Collection(OMCollection):
+    """
+    A collection of metadata nodes that can be saved to
+    and loaded from disk, and uploaded to the KG.
+
+    Args
+    ----
+
+    *nodes (LinkedMetadata):
+        Nodes to store in the collection when creating it.
+        Child nodes that are referenced from the explicitly
+        listed nodes will also be added.
+    """
+
+    def load(self, *paths):
+        import_module("fairgraph.openminds")
+        super().load(*paths)
+
+    def upload(self, client, default_space=None, space_map=None, verbosity=0):
+        nodes_to_save = [
+            node
+            for node in self.sort_nodes_for_upload()
+            if not node.id.startswith("https://openminds.om-i.org/instances")
+        ]
+        activity_log = ActivityLog()
+
+        if verbosity == 1:
+            try:
+                tqdm = import_module("tqdm")
+            except ImportError:
+                warn("Unable to show progress bar, please install tqdm")
+            else:
+                nodes_to_save = tqdm.tqdm(nodes_to_save)
+
+        if os.path.exists(".kg_upload_log.txt"):
+            with open(".kg_upload_log.txt") as fp:
+                skip = fp.read().strip().split("\n")
+        else:
+            skip = None
+
+        for i, node in enumerate(nodes_to_save):
+            if not (skip and node.id in skip):
+                if verbosity == 2:
+                    print(f"[{100*i//len(nodes_to_save)}%] Saving {node.__class__.__name__} {node.id}")
+                if space_map:
+                    target_space = space_map.get(node.__class__, default_space)
+                else:
+                    target_space = default_space
+                original_node_id = node.id
+                try:
+                    node.save(
+                        client, space=target_space, recursive=False, ignore_duplicates=True, activity_log=activity_log
+                    )
+                except AuthenticationError as err:
+                    # client.refresh()
+                    print(err)
+                    break
+                except Exception as err:
+                    if "500" in str(err):
+                        sleep(5)
+                        node.save(
+                            client,
+                            space=target_space,
+                            recursive=False,
+                            ignore_duplicates=True,
+                            activity_log=activity_log,
+                        )
+                    else:
+                        raise
+                else:
+                    with open(".kg_upload_log.txt", "a") as fp:
+                        fp.write(f"{original_node_id}\n")
+
+        return activity_log

fairgraph/embedded.py

@@ -0,0 +1,122 @@
+"""
+This module provides the EmbeddedMetadata class, which is the base class
+for representations of structured metadata that do not have their own identifier,
+but are rather embedded within another metadata instance.
+"""
+
+# Copyright 2018-2024 CNRS
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+import logging
+from typing import Optional, TYPE_CHECKING, Union
+from warnings import warn
+
+from .utility import as_list, ActivityLog
+from .base import Resolvable, JSONdict
+from .node import ContainsMetadata
+
+if TYPE_CHECKING:
+    from .client import KGClient
+
+
+logger = logging.getLogger("fairgraph")
+
+
+class EmbeddedMetadata(ContainsMetadata, Resolvable):
+    """
+    Base class for metadata structures that are embedded in Knowledge Graph objects.
+
+    Args:
+        data (dict, optional): a JSON-LD document containing the KG representation of the metadata.
+        properties: the metadata properties (property names and values)
+    """
+
+    def __init__(self, data: Optional[JSONdict] = None, **properties):
+        super().__init__(data=data, **properties)
+
+    @property
+    def space(self) -> Union[str, None]:
+        """The KG space the metadata is stored in."""
+        return None
+
+    @property
+    def default_space(self) -> Union[str, None]:
+        """The KG space new metadata will be stored in if no space is specified."""
+        return None
+
+    def __repr__(self):
+        template_parts = (
+            "{}={{self.{}!r}}".format(prop.name, prop.name)
+            for prop in self.properties
+            if getattr(self, prop.name, None) is not None
+        )
+        template = "{self.__class__.__name__}(" + ", ".join(template_parts) + ")"
+        return template.format(self=self)
+
+    def __eq__(self, other):
+        return isinstance(other, self.__class__) and self.to_jsonld(embed_linked_nodes=False) == other.to_jsonld(
+            embed_linked_nodes=False
+        )
+
+    @classmethod
+    def from_jsonld(cls, data: JSONdict) -> Union[None, EmbeddedMetadata]:
+        """Create an instance of the class from a JSON-LD document."""
+        if "@id" in data:
+            warn("Expected embedded metadata, but received @id")
+            return None
+        deserialized_data = cls._deserialize_data(data)
+        return cls(data=data, **deserialized_data)
+
+    def save(
+        self,
+        client: KGClient,
+        space: Optional[str] = None,
+        recursive: bool = True,
+        activity_log: Optional[ActivityLog] = None,
+        replace: bool = False,
+        ignore_duplicates: bool = False,
+    ):
+        """
+        Save to the KG any sub-components of the metadata object that are KGObjects.
+        """
+        for prop in self.properties:
+            values = getattr(self, prop.name)
+            for value in as_list(values):
+                if isinstance(value, ContainsMetadata):
+                    if value.space:
+                        target_space = value.space
+                    elif (
+                        value.__class__.default_space == "controlled"
+                        and value.exists(client, ignore_duplicates=ignore_duplicates)
+                        and value.space == "controlled"
+                    ):
+                        continue
+                    elif space is None and self.space is not None:
+                        target_space = self.space
+                    else:
+                        assert space is not None  # for type checking
+                        target_space = space
+                    if target_space == "controlled":
+                        if value.exists(client, ignore_duplicates=ignore_duplicates) and value.space == "controlled":
+                            continue
+                        else:
+                            raise Exception("Cannot write to controlled space")
+                    value.save(
+                        client,
+                        space=target_space,
+                        recursive=recursive,
+                        activity_log=activity_log,
+                        ignore_duplicates=ignore_duplicates,
+                    )

fairgraph/errors.py

@@ -0,0 +1,47 @@
+"""
+Definition of specific Exceptions.
+"""
+
+# Copyright 2018-2024 CNRS
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+class ResourceExistsError(Exception):
+    """Raised when trying to create a resource that already exists in the Knowledge Graph"""
+
+    pass
+
+
+class AuthenticationError(Exception):
+    """Raised when there is a problem with authentication"""
+
+    pass
+
+
+class AuthorizationError(Exception):
+    """Raised when there is a problem with authorization"""
+
+    pass
+
+
+class ResolutionFailure(Exception):
+    """Raised when unable to resolve a link in the Knowledge Graph"""
+
+    pass
+
+
+class CannotBuildExistenceQuery(Exception):
+    """Raised when it is not possible to build an existence query"""
+
+    pass

fairgraph/fields.py

@@ -0,0 +1,11 @@
+from warnings import warn
+
+from .properties import Property as Field
+
+warn(
+    "The 'Field' class has been renamed to 'Property' "
+    "for consistency with openMINDS. "
+    "Use of 'Field' will still work until the next release, "
+    "when this alias will be removed.",
+    DeprecationWarning,
+)