tol-sdk 1.7.4__py3-none-any.whl → 1.7.5b2__py3-none-any.whl

tol/api_client/parser.py

@@ -6,12 +6,12 @@ from __future__ import annotations
 
 import typing
 from abc import ABC, abstractmethod
-from collections.abc import Mapping
-from typing import Any, Iterable, Optional
+from collections.abc import Iterable
+from typing import Any
 
 from dateutil.parser import parse as dateutil_parse
 
-from ..core import DataObject
+from ..core import DataObject, ReqFieldsTree
 
 if typing.TYPE_CHECKING:
     from ..core import DataSource
@@ -27,23 +27,12 @@ class Parser(ABC):
     instances
     """
 
-    def parse_iterable(
-        self,
-        transfers: Iterable[JsonApiResource]
-    ) -> Iterable[DataObject]:
-        """
-        Parses an `Iterable` of JSON:API transfer resources
-        """
-
-        return (
-            self.parse(t) for t in transfers
-        )
-
     @abstractmethod
-    def parse(self, transfer: JsonApiResource) -> DataObject:
+    def parse_json_doc(self, transfer: JsonApiDoc) -> Iterable[DataObject]:
         """
-        Parses an individual JSON:API transfer resource to a
-        `DataObject` instance
+        Parses a JSON:API document, which includes a `data` array and possibly
+        an `included` array of related objects, returning an list of
+        `DataObject`.
         """
 
     @abstractmethod
@@ -62,22 +51,75 @@ class Parser(ABC):
 
 
 class DefaultParser(Parser):
+    def __init__(
+        self,
+        data_source_dict: dict[str, DataSource],
+        requested_tree: ReqFieldsTree | None = None,
+    ) -> None:
+        self.__ds_dict = data_source_dict
+        self.__requested_tree = requested_tree
 
-    def __init__(self, data_source_dict: dict[str, DataSource]) -> None:
-        self.__dict = data_source_dict
-
-    def parse(self, transfer: JsonApiResource) -> DataObject:
+    def parse_json_doc(
+        self,
+        transfer: JsonApiDoc,
+    ) -> Iterable[DataObject]:
+        data_objects = list(self.__parse_iterable(transfer['data']))
+        if tree := self.__requested_tree:
+            included = DataObjectCatalog(self.__parse_iterable(transfer.get('included')))
+            for obj in data_objects:
+                self.__link_related_obejcts(tree, included, obj)
+        return data_objects
+
+    def __link_related_obejcts(
+        self,
+        tree: ReqFieldsTree,
+        included: DataObjectCatalog,
+        data_object: DataObject,
+    ) -> None:
+        """
+        Using the `ReqFieldsTree` recursively replaces related stub
+        `DataObject`s with `DataObject`s from the `incldued`
+        `DataObjectCatalog` which were built from the JSON:API "included"
+        array.
+        """
+        for name, sub_tree in tree.sub_trees():
+            if name in tree.to_one_names():
+                if (related := data_object._to_one_objects.get(name)) and (
+                    inc := included.fetch(related)
+                ):
+                    # Link the to-one object
+                    setattr(data_object, name, inc)
+                    self.__link_related_obejcts(sub_tree, included, inc)
+            elif related := data_object._to_many_objects.get(name):
+                # Link each to-many object
+                for i, rel in enumerate(related):
+                    if inc := included.fetch(rel):
+                        related[i] = inc
+                        self.__link_related_obejcts(sub_tree, included, inc)
+
+    def __parse_iterable(
+        self,
+        transfer: list[JsonApiResource],
+    ) -> Iterable[DataObject]:
+        if transfer:
+            if isinstance(transfer, list):
+                for json_res in transfer:
+                    yield self.__parse(json_res)
+            else:
+                yield self.__parse(transfer)
+
+    def __parse(self, transfer: JsonApiResource) -> DataObject:
         type_ = transfer['type']
         ds = self.__get_data_source(type_)
-        raw_attributes = transfer.get('attributes')
-
-        attributes = self.__convert_attributes(type_, raw_attributes)
+        attributes = self.__convert_attributes(type_, transfer.get('attributes'))
+        to_one, to_many = self.__parse_relationships(transfer.get('relationships'))
 
         return ds.data_object_factory(
-            transfer.get('type'),
+            type_,
             id_=transfer.get('id'),
             attributes=attributes,
-            to_one=self.__parse_to_ones(transfer)
+            to_one=to_one,
+            to_many=to_many,
         )
 
     def parse_stats(self, transfer: JsonApiResource) -> dict:
@@ -90,73 +132,54 @@ class DefaultParser(Parser):
         type_ = transfer.get('type')
         raw_stats = transfer.get('stats')
 
-        return [
-            self.__convert_group_stats(type_, raw_stat)
-            for raw_stat in raw_stats
-        ]
+        return [self.__convert_group_stats(type_, raw_stat) for raw_stat in raw_stats]
 
     def __get_data_source(self, type_: str) -> DataSource:
-        return self.__dict[type_]
-
-    def __parse_to_ones(
-        self,
-        transfer: JsonApiResource
-    ) -> dict[str, DataObject]:
-
-        return {
-            k: self.__parse_to_one(v)
-            for k, v in transfer.get('relationships', {}).items()
-            if self.__relationship_is_to_one(v)
-        }
-
-    def __parse_to_one(
-        self,
-        v: dict[str, Any] | None
-    ) -> DataObject | None:
-
-        if v is None:
-            return None
-        else:
-            return self.parse(v.get('data', {}))
-
-    def __relationship_is_to_one(
-        self,
-        relation: dict[str, Any] | None
-    ) -> bool:
-
-        if relation is None:
-            return True
-
-        return isinstance(
-            relation.get('data'),
-            Mapping
+        return self.__ds_dict[type_]
+
+    def __parse_relationships(
+        self, related: dict[str, JsonApiResource] | None
+    ) -> tuple[dict[str, DataObject | None], dict[str, list[DataObject]]]:
+        to_one = {}
+        to_many = {}
+        if related:
+            for name, value in related.items():
+                if value is None:
+                    # This must be a to-one relation because to-many relations
+                    # are never null.  (If the to-many has been fetched it
+                    # will be an empty list. If it has not been fetched it
+                    # will be a dict containing a "links" key.)
+                    to_one[name] = None
+                elif data := value.get('data'):
+                    if isinstance(data, list):
+                        to_many[name] = [self.__make_stub_data_object(x) for x in data]
+                    else:
+                        to_one[name] = None if data is None else self.__make_stub_data_object(data)
+        return to_one, to_many
+
+    def __make_stub_data_object(self, transfer: JsonApiResource):
+        type_ = transfer['type']
+        ds = self.__get_data_source(type_)
+        return ds.data_object_factory(
+            type_,
+            id_=transfer['id'],
+            stub=True,
         )
 
     def __convert_attributes(
-        self,
-        type_: str,
-        attributes: Optional[dict[str, Any]]
+        self, type_: str, attributes: dict[str, Any] | None
     ) -> dict[str, Any]:
-
         if not attributes:
             return {}
 
         datetime_keys = self.__get_datetime_keys(type_)
 
         return {
-            k: (
-                dateutil_parse(v)
-                if k in datetime_keys and v is not None
-                else v
-            )
+            k: (dateutil_parse(v) if k in datetime_keys and v is not None else v)
             for k, v in attributes.items()
         }
 
-    def __convert_stats(
-        self,
-        type_: str,
-        stats: Optional[dict[str, Any]]
-    ) -> dict[str, Any]:
+    def __convert_stats(self, type_: str, stats: dict[str, Any] | None) -> dict[str, Any]:
         # {'field': {'min': value, 'max': value}
         if not stats:
             return {}
@@ -167,9 +190,7 @@ class DefaultParser(Parser):
             fieldname: {
                 k: (
                     dateutil_parse(v, ignoretz=True)
-                    if fieldname in datetime_keys
-                    and v is not None
-                    and k in ['min', 'max']
+                    if fieldname in datetime_keys and v is not None and k in ['min', 'max']
                     else v
                 )
                 for k, v in fieldstats.items()
@@ -178,11 +199,8 @@ class DefaultParser(Parser):
         }
 
     def __convert_group_stats(
-        self,
-        type_: str,
-        raw_stats: dict[str, dict[str, Any]]
+        self, type_: str, raw_stats: dict[str, dict[str, Any]]
     ) -> dict[str, dict[str, Any]]:
-
         st = raw_stats.pop('stats')
         count = st.pop('count', None)
 
@@ -193,19 +211,41 @@ class DefaultParser(Parser):
 
         return raw_stats
 
-    def __get_datetime_keys(self, type_: str) -> list[str]:
+    def __get_datetime_keys(self, type_: str) -> set[str]:
+        """
+        Gets called on each object, which is somewhat inefficient.  Should be
+        cached for each object type, but don't want `self` in a cache because
+        it could leak memory.
+        """
         ds = self.__get_data_source(type_)
-        attribute_types = ds.attribute_types.get(
-            type_,
-            {}
-        )
+        attribute_types = ds.attribute_types.get(type_, {})
+
+        return {attr for attr, typ in attribute_types.items() if self.__type_is_datetime(typ)}
+
+    def __type_is_datetime(self, typ: str, /) -> bool:
+        lc_type = typ.lower()
+
+        return 'date' in lc_type or 'time' in lc_type
+
+
+class DataObjectCatalog:
+    """
+    A catalog of `DataObject`s keyed by their `type` and `id` attributes.
+    """
+
+    def __init__(self, data_obj_list: Iterable[DataObject] | None):
+        self.__obj_index = {}
+        if data_obj_list:
+            for obj in data_obj_list:
+                self.store(obj)
 
-        return [
-            k for k, v in attribute_types.items()
-            if self.__value_is_datetime(v)
-        ]
+    def __len__(self):
+        return len(self.__obj_index)
 
-    def __value_is_datetime(self, __v: str) -> bool:
-        lower_ = __v.lower()
+    def store(self, obj) -> None:
+        key = obj.type, obj.id
+        self.__obj_index[key] = obj
 
-        return 'date' in lower_ or 'time' in lower_
+    def fetch(self, obj) -> DataObject | None:
+        key = obj.type, obj.id
+        return self.__obj_index.get(key)

tol/api_client/view.py

@@ -2,18 +2,21 @@
 #
 # SPDX-License-Identifier: MIT
 
+from __future__ import annotations
+
 import urllib
 from abc import ABC, abstractmethod
+from collections.abc import Iterable
 from datetime import date
-from typing import Any, Dict, Iterable, List, Optional, Union
+from typing import Any
 
 from ..core import DataObject
 from ..core.requested_fields import ReqFieldsTree
 
-DocumentMeta = Dict[str, Any]
-DumpDict = Dict[str, Any]
-DumpDictMany = List[DumpDict]
-ResponseDict = Dict[str, Union[DumpDict, DumpDictMany]]
+DocumentMeta = dict[str, Any]
+DumpDict = dict[str, Any]
+DumpDictMany = list[DumpDict]
+ResponseDict = dict[str, DumpDict | DumpDictMany]
 
 
 class View(ABC):
@@ -26,7 +29,7 @@ class View(ABC):
     def dump(
         self,
         data_object: DataObject,
-        document_meta: Optional[DocumentMeta] = None,
+        document_meta: DocumentMeta | None = None,
     ) -> ResponseDict:
         """
         Create a JSON:API response for an individual DataObject result
@@ -36,7 +39,7 @@ class View(ABC):
     def dump_bulk(
         self,
         data_objects: Iterable[DataObject],
-        document_meta: Optional[DocumentMeta] = None,
+        document_meta: DocumentMeta | None = None,
     ) -> ResponseDict:
         """
         Create a JSON:API response for an Iterable of DataObject results
@@ -56,7 +59,7 @@ class DefaultView(View):
         self,
         requested_tree: ReqFieldsTree,
         prefix: str = '',
-        hop_limit: Optional[int] = None,
+        hop_limit: int | None = None,
     ) -> None:
         """
         Args:
@@ -77,14 +80,17 @@ class DefaultView(View):
     def dump(
         self,
         data_object: DataObject,
-        document_meta: Optional[DocumentMeta] = None,
+        document_meta: DocumentMeta | None = None,
     ) -> ResponseDict:
-        response = {
-            'data': self.__dump_object(
-                data_object,
-                tree=self.__requested_tree,
-            ),
-        }
+        included = IncludedDumps()
+        dumped = self.__dump_object(
+            data_object,
+            included,
+            tree=self.__requested_tree,
+        )
+        response = {'data': dumped}
+        if included:
+            response['included'] = included.as_list()
         if document_meta is not None:
             response['meta'] = document_meta
         return response
@@ -92,16 +98,20 @@ class DefaultView(View):
     def dump_bulk(
         self,
         data_objects: Iterable[DataObject],
-        document_meta: Optional[DocumentMeta] = None,
+        document_meta: DocumentMeta | None = None,
     ) -> ResponseDict:
+        included = IncludedDumps()
         dumped = [
             self.__dump_object(
                 data_object,
+                included,
                 tree=self.__requested_tree,
             )
             for data_object in data_objects
         ]
         response = {'data': dumped}
+        if included:
+            response['included'] = included.as_list()
         if document_meta is not None:
             response['meta'] = document_meta
         return response
@@ -109,14 +119,20 @@ class DefaultView(View):
     def __dump_object(
         self,
         data_object: DataObject,
+        included: IncludedDumps,
         tree: ReqFieldsTree,
     ) -> DumpDict:
-        dump = {'type': data_object.type, 'id': data_object.id}
+        """
+        Returns a JSON:API resource object for the `data_object`, recursively
+        adding related objects as specified in the `tree: ReqFieldsTree`
+        argument.  Related objects are accumulated in the `incldued` array.
+        """
+        dump = {'type': data_object.type, 'id': null_or_str(data_object.id)}
         # Stub trees are created by requested_fields paths ending in ".id"
         if not tree.is_stub:
             self.__add_attributes(data_object, dump, tree)
         if tree.has_relationships:
-            self.__add_relationships(data_object, dump, tree)
+            self.__add_relationships(data_object, dump, included, tree)
         return dump
 
     def __add_attributes(
@@ -125,6 +141,10 @@ class DefaultView(View):
         dump: DumpDict,
         tree: ReqFieldsTree | None,
     ):
+        """
+        If attributes are specified in the `tree: ReqFieldsTree`, adds only
+        those to the dump.  Default is to add all attribtues.
+        """
         if tree and (attr_names := tree.attribute_names):
             # Only add requested attributes
             dump['attributes'] = self.__convert_attributes(
@@ -138,55 +158,110 @@ class DefaultView(View):
         self,
         data_object: DataObject,
         dump: DumpDict,
+        included: IncludedDumps,
         tree: ReqFieldsTree | None = None,
     ) -> DumpDict:
         rel_dict = self.__dump_to_one_relationships(
-            data_object, tree
-        ) | self.__dump_to_many_relationships(data_object, tree)
+            data_object, included, tree
+        ) | self.__dump_to_many_relationships(data_object, included, tree)
         if rel_dict:
             dump['relationships'] = rel_dict
 
     def __dump_to_one_relationships(
         self,
         data_object: DataObject,
+        included: IncludedDumps,
         tree: ReqFieldsTree,
     ) -> RelationshipDump:
         to_ones = {}
-        for name in tree.to_one_names():
-            if name in data_object._to_one_objects:
+        for rel in tree.to_one_names():
+            if rel in data_object._to_one_objects:
                 one_dump = None
-                if one := data_object._to_one_objects.get(name):
-                    if sub_tree := tree.get_sub_tree(name):
-                        one_dump = {'data': self.__dump_object(one, tree=sub_tree)}
-                    else:
-                        one_dump = {'data': {'type': one.type, 'id': one.id}}
-                to_ones[name] = one_dump
+                if one := data_object._to_one_objects.get(rel):
+                    one_dump = {'data': self.__dump_stub(one, rel)}
+                    if sub_tree := tree.get_sub_tree(rel):
+                        included.add_dump(self.__dump_object(one, included, tree=sub_tree))
+                to_ones[rel] = one_dump
         return to_ones
 
     def __dump_to_many_relationships(
         self,
         data_object: DataObject,
+        included: IncludedDumps,
         tree: ReqFieldsTree,
     ) -> RelationshipDump:
-        quoted_id = urllib.parse.quote(str(data_object.id), safe='')
+        oid = data_object.id
+        quoted_id = None if oid is None else urllib.parse.quote(str(oid), safe='')
         to_many = {}
-        for name in tree.to_many_names():
-            if sub_tree := tree.get_sub_tree(name):
-                to_many[name] = {
-                    'data': [
-                        self.__dump_object(x, tree=sub_tree) for x in getattr(data_object, name)
-                    ]
-                }
-            else:
-                link = f'{self.__prefix}/{data_object.type}/{quoted_id}/{name}'
-                to_many[name] = {'links': {'related': link}}
+        for rel in tree.to_many_names():
+            sub_tree = tree.get_sub_tree(rel)
+            if sub_tree and rel in data_object._to_many_objects:
+                many_obj = data_object._to_many_objects.get(rel)
+                to_many[rel] = [self.__dump_stub(x, rel) for x in many_obj]
+                for obj in many_obj:
+                    included.add_dump(self.__dump_object(obj, included, sub_tree))
+            elif quoted_id:
+                link = f'{self.__prefix}/{data_object.type}/{quoted_id}/{rel}'
+                to_many[rel] = {'links': {'related': link}}
         return to_many
 
+    def __dump_stub(self, obj: DataObject, rel_name: str) -> dict[str, str]:
+        """
+        Create a stub JSON:API object, known in the JSON:API spec as
+        a "resource identifier object".  Contains a sanity check for the `id`
+        attribute having a value.  If we want to support, for example,
+        storing related objects with auto-incremented IDs, we will need to
+        implement creating `lid` local IDs for linking to resource objects in
+        the `included` array.
+        """
+        if obj.id is None:
+            msg = (
+                f"Cannot serialise '{obj.type}' object in relation"
+                f" '{rel_name}' because it has no `id` attribute"
+            )
+            raise ValueError(msg)
+        return {'type': obj.type, 'id': str(obj.id)}
+
     def __convert_attributes(self, attributes: dict[str, Any]) -> dict[str, Any]:
         return {k: self.__convert_value(v) for k, v in attributes.items()}
 
-    def __convert_value(self, __v: Any) -> Any:
-        if isinstance(__v, date):
+    def __convert_value(self, val: Any, /) -> Any:
+        if isinstance(val, date):
             # `datetime` is a subclass of `date`
-            return __v.isoformat()
-        return __v
+            return val.isoformat()
+        return val
+
+
+def null_or_str(oid: Any, /):
+    """
+    Return `oid` as a string if it isn't `None`
+    """
+    return None if oid is None else str(oid)
+
+
+class IncludedDumps:
+    """
+    Maintains objects to be returned in the JSON:API `included` list, indexed
+    by tuples of `(type, id)`.
+    """
+
+    def __init__(self):
+        self.__type_id: dict[tuple[str, str], DumpDict] = {}
+
+    def __len__(self):
+        """
+        Implemented so that an `IncludedDumps` object returns true in boolean
+        context when it has entries.
+        """
+        return len(self.__type_id)
+
+    def as_list(self):
+        return list(self.__type_id.values())
+
+    def add_dump(self, dump: DumpDict):
+        """
+        Add a new DumpDict to the collection.
+        """
+        key = dump['type'], dump['id']
+        if key not in self.__type_id:
+            self.__type_id[key] = dump

tol/core/__init__.py

@@ -26,7 +26,8 @@ from .data_object import (  # noqa F401
 )
 from .data_object_converter import (  # noqa F401
     DataObjectToDataObjectOrUpdateConverter,
-    DefaultDataObjectToDataObjectConverter
+    DefaultDataObjectToDataObjectConverter,
+    SanitisingConverter
 )
 from .factory import core_data_object  # noqa F401
 from .http_client import HttpClient  # noqa F401

tol/core/data_object.py

@@ -6,8 +6,9 @@ from __future__ import annotations
 
 import typing
 from abc import ABC, abstractmethod
+from collections.abc import Iterable
 from dataclasses import dataclass
-from typing import Any, Iterable, Optional, Protocol, Union
+from typing import Any, Protocol
 
 if typing.TYPE_CHECKING:
     from .operator import Relational
@@ -44,7 +45,7 @@ class DataObject(_AnyKeyProtocol, ABC):
 
     @property
     @abstractmethod
-    def id(self) -> Optional[str]:  # noqa
+    def id(self) -> str | None:  # noqa
         """
         A unique ID by which to identify this object within
         its type.
@@ -61,7 +62,7 @@ class DataObject(_AnyKeyProtocol, ABC):
 
     @property
     @abstractmethod
-    def to_one_relationships(self) -> dict[str, Optional[DataObject]]:
+    def to_one_relationships(self) -> dict[str, DataObject | None]:
         """
         A dictionary of relationships, where this object refers to
         precisely one other.
@@ -77,20 +78,37 @@ class DataObject(_AnyKeyProtocol, ABC):
 
     @property
     @abstractmethod
-    def _host(self) -> Union[DataSource, Relational]:
+    def _host(self) -> DataSource | Relational:
         """
         The DataSource instance that manages DataObject instances of this type
         """
 
     @property
     @abstractmethod
-    def _to_one_objects(self) -> dict[str, Optional[DataObject]]:
+    def _to_one_objects(self) -> dict[str, DataObject | None]:
         """
-        The name: attribute mapping for `DataObject`s set on this instance.
+        The name: attribute mapping for to-one `DataObject`s set on this
+        instance.
 
-        N.B. - This is not equivalent to `to_one_relationships`, as that merges
-        both set `DataObject` instances and fetched relations from the
-        `DataSource`. Most users will not need (or want) to use this property.
+        Can used to inspect which relations are set on the object without
+        triggering auto-fetching of to-one related objects from the `_host`
+        `DataSource`.
+
+        Most users should use `to_one_relationships` instead.
+        """
+
+    @property
+    @abstractmethod
+    def _to_many_objects(self) -> dict[str, Iterable[DataObject]]:
+        """
+        The name: attribute mapping for to-many `DataObject`s set on this
+        instance.
+
+        Can used to inspect which relations are set on the object without
+        triggering auto-fetching of to-many related objects from the `_host`
+        `DataSource`.
+
+        Most users should use `to_many_relationships` instead.
         """
 
     def get_field_by_name(self, field_name: str) -> Any: