fairgraph 0.13.0__py3-none-any.whl

fairgraph/__init__.py

@@ -0,0 +1,61 @@
+"""
+Python client for the EBRAINS Knowledge Graph
+
+Authors: Andrew Davison et al., CNRS (see authors.rst)
+
+
+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 openminds import IRI
+from .client import KGClient
+from .kgobject import KGObject
+from .embedded import EmbeddedMetadata
+from .kgproxy import KGProxy
+from .kgquery import KGQuery
+from .collection import Collection
+from . import client, errors, openminds, utility
+
+__version__ = "0.13.0"
+
+utility.initialise_instances(
+    [
+        openminds.sands.BrainAtlas,
+        openminds.sands.BrainAtlasVersion,
+        openminds.sands.CommonCoordinateSpace,
+        openminds.sands.CommonCoordinateSpaceVersion,
+        openminds.core.ContentType,
+        openminds.core.License,
+        openminds.sands.ParcellationEntity,
+        openminds.sands.ParcellationEntityVersion,
+    ]
+    + openminds.controlled_terms.list_kg_classes()
+)
+
+
+def set_error_handling(value):
+    """Set error handling globally for all modules"""
+    for module in (
+        openminds.chemicals,
+        openminds.computation,
+        openminds.controlled_terms,
+        openminds.core,
+        openminds.ephys,
+        openminds.publications,
+        openminds.sands,
+        openminds.specimen_prep,
+        openminds.stimulation,
+    ):
+        module.set_error_handling(value)

fairgraph/base.py

@@ -0,0 +1,104 @@
+"""
+This module contains base classes that define interfaces
+and contain code common to sub-classes, to avoid code duplication.
+"""
+
+# 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
+from typing import TYPE_CHECKING, Optional, Dict, List, Any
+from enum import Enum
+import logging
+from warnings import warn
+
+from .errors import AuthorizationError
+
+if TYPE_CHECKING:
+    from .client import KGClient
+
+OPENMINDS_VERSION = "v4"
+
+logger = logging.getLogger("fairgraph")
+
+JSONdict = Dict[str, Any]  # see https://github.com/python/typing/issues/182 for some possible improvements
+
+
+class ErrorHandling(str, Enum):
+    error = "error"
+    warning = "warning"
+    log = "log"
+    none = "none"
+
+    @classmethod
+    def handle_violation(cls, value, errmsg=""):
+        if value == cls.error:
+            raise ValueError(errmsg)
+        elif value == cls.warning:
+            warn(errmsg)
+        elif value == cls.log:
+            logger.warning(errmsg)
+
+
+class Resolvable:  # all
+    def resolve(
+        self,
+        client: KGClient,
+        release_status: Optional[str] = None,
+        use_cache: bool = True,
+        follow_links: Optional[Dict[str, Any]] = None,
+    ):
+        pass
+
+
+class RepresentsSingleObject(Resolvable):  # KGObject, KGProxy
+    id: Optional[str]
+    remote_data: Optional[JSONdict]
+
+    def children(
+        self, client: KGClient, follow_links: Optional[Dict[str, Any]] = None
+    ) -> List[RepresentsSingleObject]:
+        pass
+
+    def is_released(self, client: KGClient, with_children: bool = False) -> bool:
+        """Release status of the node"""
+        try:
+            return client.is_released(self.id, with_children=with_children)
+        except AuthorizationError:
+            # for unprivileged users
+            if self.remote_data and "https://core.kg.ebrains.eu/vocab/meta/firstReleasedAt" in self.remote_data:
+                return True
+            return False
+
+    def release(self, client: KGClient, with_children: bool = False):
+        """Release this node (make it available in public search)."""
+        if not self.is_released(client, with_children=with_children):
+            if with_children:
+                for child in self.children(client):
+                    if not child.is_released(client, with_children=False):
+                        client.release(child.id)
+            return client.release(self.id)
+
+    def unrelease(self, client: KGClient, with_children: bool = False):
+        """Un-release this node (remove it from public search)."""
+        response = client.unrelease(self.id)
+        if with_children:
+            for child in self.children(client):
+                client.unrelease(child.id)
+        return response
+
+
+class SupportsQuerying:  # KGObject, KGQuery
+    pass

fairgraph/caching.py

@@ -0,0 +1,52 @@
+"""
+This module contains global caches for Knowledge Graph data and queries,
+to avoid making unnecessary API calls.
+"""
+
+# 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 collections import defaultdict
+from typing import Dict, Any, Tuple
+
+
+def generate_cache_key(qd: Dict[str, str]) -> Tuple:
+    """From a query dict, generate an object suitable as a key for caching"""
+    if not isinstance(qd, dict):
+        raise TypeError("generate_cache_key expects a query dict. You provided '{}'".format(qd))
+    cache_key = []
+    for key in sorted(qd):
+        value = qd[key]
+        if isinstance(value, (list, tuple)):
+            sub_key = []
+            for sub_value in value:
+                if isinstance(sub_value, dict):
+                    sub_key.append(generate_cache_key(sub_value))
+                else:
+                    sub_key.append(str(value))
+            cache_key.append(tuple(sub_key))
+        elif isinstance(value, dict):
+            cache_key.append((key, str(value)))
+        elif value.__class__.__name__ == "IRI":  # a bit hacky
+            cache_key.append((key, str(value)))
+        else:
+            if not isinstance(value, (str, int, float)):
+                errmsg = "Expected a string, integer or float for key '{}', not a {}"
+                raise TypeError(errmsg.format(key, type(value)))
+            cache_key.append((key, value))
+    return tuple(cache_key)
+
+
+object_cache: Dict[str, Any] = {}  # for caching based on object ids
+save_cache: Dict[type, Dict[Tuple, str]] = defaultdict(dict)  # for caching based on queries