fairgraph 0.13.0__py3-none-any.whl

fairgraph/kgproxy.py

@@ -0,0 +1,178 @@
+"""
+This module provides the KGProxy class, which represents a
+KGObject whose type and identifier are known but whose other metadata
+have not been retrieved from 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 __future__ import annotations
+import logging
+from typing import List, Optional, Tuple, Union, Dict, Any, TYPE_CHECKING
+
+from openminds.base import Link
+from openminds.registry import lookup
+
+from .errors import ResolutionFailure
+from .caching import object_cache
+from .base import RepresentsSingleObject
+
+if TYPE_CHECKING:
+    from .client import KGClient
+    from .kgobject import KGObject
+
+
+logger = logging.getLogger("fairgraph")
+
+
+class KGProxy(RepresentsSingleObject, Link):
+    """
+    Representation of an KGObject whose identifier, and possibly type, are known but whose
+    other metadata have not been retrieved from the KG.
+
+    Args:
+        cls (str, KGObject, List[KGObject]): the possible types of the associated KG object, defined by a KGObject subclass
+            or by the name of the subclass.
+        uri (URI): The global identifier of the KG object.
+        preferred_release_status (str, optional): The preferred scope used to resolve the proxy.
+            Valid values are "released", "in progress", or "any".
+
+    Example:
+        >>> import fairgraph.openminds
+        >>> proxy = KGProxy("openminds.core.Person", "https://kg.ebrains.eu/api/instances/bd554312-9829-4148-8803-cb873d0b32f9")
+        >>> person = proxy.resolve(kg_client)
+        >>> type(person)
+        <class 'fairgraph.openminds.core.actors.person.Person'>
+        >>> person.given_name
+        Andrew P.
+    """
+
+    # todo: rename uri to id, for consistency?
+
+    def __init__(
+        self,
+        classes: Union[str, KGObject, List[KGObject], Tuple[KGObject]],
+        uri: str,
+        preferred_release_status: str = "released",
+    ):
+        self.classes: List[KGObject]  # todo: make this a set?
+        if isinstance(classes, str):
+            resolved_cls = lookup(classes)
+            if TYPE_CHECKING:
+                assert isinstance(resolved_cls, KGObject)
+            self.classes = [resolved_cls]
+        elif isinstance(classes, (list, tuple)):
+            self.classes = list(classes)
+        else:
+            self.classes = [classes]
+        if TYPE_CHECKING:
+            assert all(isinstance(cls, KGObject) for cls in self.classes)
+        self.id = uri
+        self.preferred_release_status = preferred_release_status
+        self.remote_data = None
+        Link.__init__(self, self.id, allowed_types=self.classes)
+
+    @property
+    def type(self) -> List[str]:
+        """
+        Provide the global identifiers of the object type (as a list of URIs).
+        """
+        try:
+            return [cls.type_ for cls in self.classes]
+        except AttributeError as err:
+            raise AttributeError(f"{err} self.classes={self.classes}")
+
+    @property
+    def cls(self):
+        """
+        For backwards compatibility
+        """
+        if len(self.classes) == 1:
+            return self.classes[0]
+        else:
+            raise AttributeError("This KGProxy has multiple possible types, use the 'classes' attribute instead")
+
+    def to_jsonld(self, **kwargs):
+        return {"@id": self.id}
+
+    def resolve(
+        self,
+        client: KGClient,
+        release_status: Optional[str] = None,
+        use_cache: bool = True,
+        follow_links: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Retrieve the full metadata for the KGObject represented by this proxy.
+
+        Args:
+            client: a KGClient
+            release_status (str, optional): The scope of the lookup. Valid values are "released", "in progress", or "any".
+                If not provided, the "preferred_release_status" provided when creating the proxy object will be used.
+            use_cache (bool): Whether to use cached data if they exist. Defaults to True.
+            follow_links (dict): The links in the graph to follow. Defaults to None.
+
+        Returns:
+            a KGObject instance, of the appropriate subclass.
+        """
+        if use_cache and self.id in object_cache:
+            obj = object_cache[self.id]
+        else:
+            release_status = release_status or self.preferred_release_status
+            obj = None
+            for cls in self.classes:
+                # this is inefficient, we should just get the data from the id, then get the correct type from the data
+                try:
+                    obj = cls.from_uri(self.id, client, release_status=release_status)
+                except TypeError:
+                    pass
+                else:
+                    break
+            if obj is None:
+                raise ResolutionFailure(f"Cannot resolve proxy object of type {self.classes} with id {self.uuid}")
+            object_cache[self.id] = obj
+        if follow_links:
+            return obj.resolve(client, release_status=release_status, use_cache=use_cache, follow_links=follow_links)
+        else:
+            return obj
+
+    def __repr__(self):
+        return f"""{self.__class__.__name__}([{", ".join(cls.__name__ for cls in self.classes)}], id="{self.id.split('/')[-1]}")"""
+
+    def __eq__(self, other):
+        return (
+            isinstance(other, self.__class__) and set(self.classes).intersection(other.classes) and self.id == other.id
+        )
+
+    def __ne__(self, other):
+        return (
+            not isinstance(other, self.__class__) or set(self.classes).isdisjoint(other.classes) or self.id != other.id
+        )
+
+    @property
+    def uuid(self) -> str:
+        return self.id.split("/")[-1]
+
+    def delete(self, client: KGClient, ignore_not_found: bool = True):
+        """Delete the instance which this proxy represents"""
+        try:
+            obj = self.resolve(client, release_status="in progress")
+        except ResolutionFailure as err:
+            logger.warning(str(err))
+            obj = None
+        if obj:
+            obj.delete(client, ignore_not_found=ignore_not_found)
+        elif not ignore_not_found:
+            raise ResolutionFailure("Couldn't resolve object to delete")

fairgraph/kgquery.py

@@ -0,0 +1,151 @@
+"""
+This module provides the KGQuery class, which represents one or more
+KGObjects identified by a range of possible types and by some of their
+metadata, but whose specific identifier(s) is/are not known.
+"""
+
+# 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 Dict, List, Optional, Union, Any, TYPE_CHECKING
+
+from openminds.registry import lookup
+
+from .utility import as_list, expand_filter
+from .caching import object_cache
+from .base import Resolvable, SupportsQuerying
+
+if TYPE_CHECKING:
+    from .client import KGClient
+    from .kgobject import KGObject
+
+logger = logging.getLogger("fairgraph")
+
+
+class KGQuery(Resolvable, SupportsQuerying):
+    """
+    Representation of one or more KGObjects identified by a range of possible types
+    and by some of their metadata, but whose specific identifier(s) is/are not known.
+
+    It is possible that no KGObjects match the types/metadata.
+
+    Args:
+        classes (list of KGObject subclasses): a list of types to query.
+        filter (dict): key:value pairs that should be matched. All pairs must match.
+        preferred_release_status (str): The preferred scope used to resolve the query.
+            Valid values are "released", "in progress", or "any".
+
+    Example:
+        >>> import fairgraph.openminds.core as omcore
+        >>> from fairgraph.utility import as_list
+        >>> query = KGQuery([omcore.Person], {"family_name": "Amunts"})
+        >>> people = as_list(query.resolve(kg_client))
+        >>> len(people)
+        1
+        >>> people[0].family_name
+        Amunts
+    """
+
+    def __init__(
+        self,
+        classes: Union[str, KGObject, List[Union[str, KGObject]]],
+        filter: Dict[str, str],
+        preferred_release_status: str = "released",
+    ):
+        self.classes: List[KGObject] = []
+        for cls in as_list(classes):
+            if isinstance(cls, str):
+                resolved_cls = lookup(cls)
+                assert isinstance(resolved_cls, KGObject)
+                self.classes.append(resolved_cls)
+            else:
+                self.classes.append(cls)
+        self.filter = filter
+        self.preferred_release_status = preferred_release_status
+
+    def __repr__(self):
+        return f"""{self.__class__.__name__}([{", ".join(cls.__name__ for cls in self.classes)}], filter="{self.filter!r}")""".replace(
+            "https://kg.ebrains.eu/api/instances/", ""
+        )
+
+    def resolve(
+        self,
+        client: KGClient,
+        size: int = 10000,
+        from_index: int = 0,
+        space: Optional[str] = None,
+        release_status: Optional[str] = None,
+        use_cache: bool = True,
+        follow_links: Optional[Dict[str, Any]] = None,
+        with_reverse_properties: Optional[bool] = False,
+    ):
+        """
+        Retrieve the full metadata for the KGObject(s) represented by this query object.
+
+        Args:
+            client: a KGClient
+            from_index: The index of the first result to include in the response.
+            size: The maximum number of results to include in the response.
+            space: If specified, queries only in the given space.
+            release_status (str, optional): The scope of the query. Valid values are "released", "in progress", or "any".
+                If not provided, the "preferred_release_status" provided when creating the proxy object will be used.
+            use_cache (bool): Whether to use cached data if they exist. Defaults to True.
+            follow_links (dict): The links in the graph to follow. Defaults to None.
+            with_reverse_properties (dict): Whether to include reverse properties. Defaults to False.
+
+        Returns:
+            a KGObject instance, of the appropriate subclass.
+        """
+        release_status = release_status or self.preferred_release_status
+        objects: List[KGObject] = []
+        for cls in self.classes:
+            if hasattr(cls, "generate_query"):
+                # if cls is EmbeddedMetadata we cannot query it
+                query = cls.generate_query(
+                    client=client,
+                    filters=self.filter,
+                    space=space,
+                    follow_links=follow_links,
+                    with_reverse_properties=with_reverse_properties,
+                )
+                instances = client.query(
+                    query=query,
+                    size=size,
+                    from_index=from_index,
+                    release_status=release_status,
+                ).data
+                objects.extend(cls.from_jsonld(instance_data, client) for instance_data in instances)
+        for obj in objects:
+            object_cache[obj.id] = obj
+
+        if follow_links:
+            for obj in objects:
+                obj.resolve(client, release_status=release_status, use_cache=use_cache, follow_links=follow_links)
+
+        if len(objects) == 1:
+            return objects[0]
+        else:
+            return objects
+
+    def count(self, client: KGClient, space: Optional[str] = None, release_status: Optional[str] = None):
+        """
+        Return the number of objects that would be returned by resolving this query.
+        """
+        release_status = release_status or self.preferred_release_status
+        n = 0
+        for cls in self.classes:
+            n += cls.count(client, api="query", release_status=release_status, space=space, **self.filter)
+        return n