GeneralManager 0.14.1__py3-none-any.whl → 0.15.1__py3-none-any.whl

general_manager/interface/readOnlyInterface.py

@@ -1,7 +1,9 @@
+"""Read-only interface that mirrors JSON datasets into Django models."""
+
 from __future__ import annotations
 import json
 
-from typing import Type, Any, Callable, TYPE_CHECKING
+from typing import Type, Any, Callable, TYPE_CHECKING, cast
 from django.db import models, transaction
 from general_manager.interface.databaseBasedInterface import (
     DBBasedInterface,
@@ -25,15 +27,21 @@ logger = logging.getLogger(__name__)
 
 
 class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
+    """Interface that reads static JSON data into a managed read-only model."""
+
     _interface_type = "readonly"
     _parent_class: Type[GeneralManager]
 
     @staticmethod
     def getUniqueFields(model: Type[models.Model]) -> set[str]:
         """
-        Return a set of field names that uniquely identify instances of the specified Django model.
-        
-        Considers fields marked as unique (excluding "id"), as well as fields defined in `unique_together` and `UniqueConstraint` constraints.
+        Return names of fields that uniquely identify instances of ``model``.
+
+        Parameters:
+            model (type[models.Model]): Django model inspected for uniqueness metadata.
+
+        Returns:
+            set[str]: Field names that participate in unique constraints.
         """
         opts = model._meta
         unique_fields: set[str] = set()
@@ -55,11 +63,7 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
 
     @classmethod
     def syncData(cls) -> None:
-        """
-        Synchronizes the associated Django model with JSON data from the parent class, ensuring the database records match the provided data exactly.
-        
-        Parses the JSON data, creates or updates model instances based on unique fields, and deactivates any database records not present in the JSON data. Raises a ValueError if required attributes are missing, if the JSON data is invalid, or if no unique fields are defined.
-        """
+        """Synchronise the backing model with the class-level JSON data."""
         if cls.ensureSchemaIsUpToDate(cls._parent_class, cls._model):
             logger.warning(
                 f"Schema for ReadOnlyInterface '{cls._parent_class.__name__}' is not up to date."
@@ -74,13 +78,17 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
                 f"For ReadOnlyInterface '{parent_class.__name__}' must set '_data'"
             )
 
-        # JSON-Daten parsen
+        # Parse JSON into Python structures
         if isinstance(json_data, str):
-            data_list = json.loads(json_data)
+            parsed_data = json.loads(json_data)
+            if not isinstance(parsed_data, list):
+                raise TypeError("_data JSON must decode to a list of dictionaries")
         elif isinstance(json_data, list):
-            data_list: list[Any] = json_data
+            parsed_data = json_data
         else:
-            raise ValueError("_data must be a JSON string or a list of dictionaries")
+            raise TypeError("_data must be a JSON string or a list of dictionaries")
+
+        data_list = cast(list[dict[str, Any]], parsed_data)
 
         unique_fields = cls.getUniqueFields(model)
         if not unique_fields:
@@ -88,7 +96,7 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
                 f"For ReadOnlyInterface '{parent_class.__name__}' must have at least one unique field."
             )
 
-        changes = {
+        changes: dict[str, list[models.Model]] = {
             "created": [],
             "updated": [],
             "deactivated": [],
@@ -137,19 +145,23 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
         new_manager_class: Type[GeneralManager], model: Type[models.Model]
     ) -> list[Warning]:
         """
-        Check if the database schema for a Django model matches its model definition.
-        
+        Check whether the database schema matches the model definition.
+
+        Parameters:
+            new_manager_class (type[GeneralManager]): Manager class owning the interface.
+            model (type[models.Model]): Django model whose table should be inspected.
+
         Returns:
-            A list of Django Warning objects describing schema issues, such as missing tables or column mismatches. Returns an empty list if the schema is up to date.
+            list[Warning]: Warnings describing schema mismatches; empty when up to date.
         """
 
         def table_exists(table_name: str) -> bool:
             """
             Determine whether a database table with the specified name exists.
-            
+
             Parameters:
                 table_name (str): Name of the database table to check.
-            
+
             Returns:
                 bool: True if the table exists, False otherwise.
             """
@@ -162,7 +174,7 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
         ) -> tuple[list[str], list[str]]:
             """
             Compares the fields of a Django model to the columns of a specified database table.
-            
+
             Returns:
                 A tuple containing two lists:
                     - The first list contains column names defined in the model but missing from the database table.
@@ -203,7 +215,7 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
     def readOnlyPostCreate(func: Callable[..., Any]) -> Callable[..., Any]:
         """
         Decorator for post-creation hooks that registers a new manager class as read-only.
-        
+
         After the wrapped post-creation function is executed, the newly created manager class is added to the meta-class's list of read-only classes, marking it as a read-only interface.
         """
 
@@ -211,10 +223,10 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
             new_class: Type[GeneralManager],
             interface_cls: Type[ReadOnlyInterface],
             model: Type[GeneralManagerBasisModel],
-        ):
+        ) -> None:
             """
             Registers a newly created manager class as read-only after executing the wrapped post-creation function.
-            
+
             This function appends the new manager class to the list of read-only classes in the meta system, ensuring it is recognized as a read-only interface.
             """
             from general_manager.manager.meta import GeneralManagerMeta
@@ -228,7 +240,7 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
     def readOnlyPreCreate(func: Callable[..., Any]) -> Callable[..., Any]:
         """
         Decorator for pre-creation hook functions that ensures the base model class is set to `GeneralManagerBasisModel`.
-        
+
         Wraps a pre-creation function, injecting `GeneralManagerBasisModel` as the `base_model_class` argument before the manager class is created.
         """
 
@@ -236,16 +248,18 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
             name: generalManagerClassName,
             attrs: attributes,
             interface: interfaceBaseClass,
-            base_model_class=GeneralManagerBasisModel,
-        ):
+            base_model_class: type[GeneralManagerBasisModel] = GeneralManagerBasisModel,
+        ) -> tuple[
+            attributes, interfaceBaseClass, type[GeneralManagerBasisModel] | None
+        ]:
             """
             Wraps a function to ensure the `base_model_class` argument is set to `GeneralManagerBasisModel` before invocation.
-            
+
             Parameters:
                 name: The name of the manager class being created.
                 attrs: Attributes for the manager class.
                 interface: The interface base class to use.
-            
+
             Returns:
                 The result of calling the wrapped function with `base_model_class` set to `GeneralManagerBasisModel`.
             """
@@ -259,11 +273,11 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
     def handleInterface(cls) -> tuple[classPreCreationMethod, classPostCreationMethod]:
         """
         Return the pre- and post-creation hook methods for integrating the interface with a manager meta-class system.
-        
+
         The returned tuple includes:
         - A pre-creation method that ensures the base model class is set for read-only operation.
         - A post-creation method that registers the manager class as read-only.
-        
+
         Returns:
             tuple: The pre-creation and post-creation hook methods for manager class lifecycle integration.
         """

general_manager/manager/__init__.py

@@ -1,3 +1,36 @@
-from .generalManager import GeneralManager
-from .input import Input
-from ..api.property import graphQlProperty
+"""Convenience re-exports for manager utilities."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from general_manager.utils.public_api import build_module_dir, resolve_export
+
+__all__ = [
+    "GeneralManager",
+    "Input",
+    "graphQlProperty",
+    "GeneralManagerMeta",
+    "GroupManager",
+]
+
+_MODULE_MAP = {
+    "GeneralManager": ("general_manager.manager.generalManager", "GeneralManager"),
+    "GeneralManagerMeta": ("general_manager.manager.meta", "GeneralManagerMeta"),
+    "Input": ("general_manager.manager.input", "Input"),
+    "GroupManager": ("general_manager.manager.groupManager", "GroupManager"),
+    "graphQlProperty": ("general_manager.api.property", "graphQlProperty"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    return resolve_export(
+        name,
+        module_all=__all__,
+        module_map=_MODULE_MAP,
+        module_globals=globals(),
+    )
+
+
+def __dir__() -> list[str]:
+    return build_module_dir(module_all=__all__, module_globals=globals())

general_manager/manager/generalManager.py

@@ -1,5 +1,5 @@
 from __future__ import annotations
-from typing import Type, Any, TYPE_CHECKING, Self
+from typing import TYPE_CHECKING, Any, Iterator, Self, Type
 from general_manager.manager.meta import GeneralManagerMeta
 
 from general_manager.api.property import GraphQLProperty
@@ -9,17 +9,24 @@ from general_manager.bucket.baseBucket import Bucket
 
 if TYPE_CHECKING:
     from general_manager.permission.basePermission import BasePermission
+    from general_manager.interface.baseInterface import InterfaceBase
 
 
 class GeneralManager(metaclass=GeneralManagerMeta):
     Permission: Type[BasePermission]
     _attributes: dict[str, Any]
+    Interface: Type["InterfaceBase"]
 
-    def __init__(self, *args: Any, **kwargs: Any):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         """
-        Initialize the manager by creating an interface instance with the provided arguments and storing its identification.
+        Instantiate the manager by delegating to the interface and record its identification.
 
-        The identification is registered with the dependency tracker for tracking purposes.
+        Parameters:
+            *args: Positional arguments forwarded to the interface constructor.
+            **kwargs: Keyword arguments forwarded to the interface constructor.
+
+        Returns:
+            None
         """
         self._interface = self.Interface(*args, **kwargs)
         self.__id: dict[str, Any] = self._interface.identification
@@ -27,15 +34,20 @@ class GeneralManager(metaclass=GeneralManagerMeta):
             self.__class__.__name__, "identification", f"{self.__id}"
         )
 
-    def __str__(self):
+    def __str__(self) -> str:
+        """Return a user-friendly representation showing the identification."""
         return f"{self.__class__.__name__}(**{self.__id})"
 
-    def __repr__(self):
+    def __repr__(self) -> str:
+        """Return a detailed representation of the manager instance."""
         return f"{self.__class__.__name__}(**{self.__id})"
 
     def __reduce__(self) -> str | tuple[Any, ...]:
         """
-        Support object serialization by returning a tuple containing the class and identification values for pickling.
+        Provide pickling support for the manager instance.
+
+        Returns:
+            tuple[Any, ...]: Reconstruction data consisting of the class and identification tuple.
         """
         return (self.__class__, tuple(self.__id.values()))
 
@@ -44,12 +56,16 @@ class GeneralManager(metaclass=GeneralManagerMeta):
         other: Self | Bucket[Self],
     ) -> Bucket[Self]:
         """
-        Returns a Bucket containing the union of this manager and another manager of the same class or a Bucket.
+        Merge this manager with another manager or bucket.
 
-        If `other` is a Bucket, the result is the union of the Bucket and this manager. If `other` is a manager of the same class, the result is a Bucket containing both managers. Raises a TypeError if `other` is not a supported type.
+        Parameters:
+            other (Self | Bucket[Self]): Manager instance or bucket to combine.
 
         Returns:
-            Bucket[Self]: A Bucket containing the combined managers.
+            Bucket[Self]: Bucket containing the union of both inputs.
+
+        Raises:
+            TypeError: If `other` is neither a compatible bucket nor manager.
         """
         if isinstance(other, Bucket):
             return other | self
@@ -63,19 +79,25 @@ class GeneralManager(metaclass=GeneralManagerMeta):
         other: object,
     ) -> bool:
         """
-        Check equality based on the identification dictionary.
+        Compare managers based on their identification values.
+
+        Parameters:
+            other (object): Object to compare against this manager.
 
-        Returns True if the other object is a GeneralManager with the same identification, otherwise False.
+        Returns:
+            bool: True when `other` is a manager with the same identification.
         """
         if not isinstance(other, GeneralManager):
             return False
         return self.identification == other.identification
 
     @property
-    def identification(self):
+    def identification(self) -> dict[str, Any]:
+        """Return the identification dictionary used to fetch the managed object."""
         return self.__id
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[tuple[str, Any]]:
+        """Iterate over attribute names and resolved values for the managed object."""
         for key, value in self._attributes.items():
             if callable(value):
                 yield key, value(self._interface)
@@ -95,17 +117,19 @@ class GeneralManager(metaclass=GeneralManagerMeta):
         **kwargs: Any,
     ) -> Self:
         """
-        Create a new managed object via the underlying interface and return a manager instance representing it.
-
-        Performs a permission check unless `ignore_permission` is True. All additional keyword arguments are passed to the interface's `create` method.
+        Create a new managed object through the interface.
 
         Parameters:
-            creator_id (int | None): Optional ID of the user creating the object.
-            history_comment (str | None): Optional comment for audit or history purposes.
-            ignore_permission (bool): If True, bypasses the permission check.
+            creator_id (int | None): Optional identifier of the creating user.
+            history_comment (str | None): Audit comment stored with the change.
+            ignore_permission (bool): When True, skip permission validation.
+            **kwargs (Any): Additional fields forwarded to the interface `create` method.
 
         Returns:
-            Self: Manager instance for the newly created object.
+            Self: Manager instance representing the created object.
+
+        Raises:
+            PermissionError: Propagated if the permission check fails.
         """
         if not ignore_permission:
             cls.Permission.checkCreatePermission(kwargs, cls, creator_id)
@@ -123,16 +147,19 @@ class GeneralManager(metaclass=GeneralManagerMeta):
         **kwargs: Any,
     ) -> Self:
         """
-        Update the managed object with new data and return a new manager instance reflecting the changes.
+        Update the managed object and return a fresh manager representing the new state.
 
         Parameters:
-            creator_id (int | None): Identifier of the user performing the update, if applicable.
-            history_comment (str | None): Optional comment describing the update.
-            ignore_permission (bool): If True, bypasses permission checks.
-            **kwargs: Fields and values to update on the managed object.
+            creator_id (int | None): Optional identifier of the user performing the update.
+            history_comment (str | None): Audit comment recorded with the update.
+            ignore_permission (bool): When True, skip permission validation.
+            **kwargs (Any): Field updates forwarded to the interface.
 
         Returns:
-            Self: A new manager instance representing the updated object.
+            Self: Manager instance reflecting the updated object.
+
+        Raises:
+            PermissionError: Propagated if the permission check fails.
         """
         if not ignore_permission:
             self.Permission.checkUpdatePermission(kwargs, self, creator_id)
@@ -151,15 +178,18 @@ class GeneralManager(metaclass=GeneralManagerMeta):
         ignore_permission: bool = False,
     ) -> Self:
         """
-        Deactivate the managed object and return a new manager instance representing its deactivated state.
+        Deactivate the managed object and return a manager for the resulting state.
 
         Parameters:
-            creator_id (int | None): Optional ID of the user performing the deactivation.
-            history_comment (str | None): Optional comment explaining the deactivation.
-            ignore_permission (bool): If True, bypasses permission checks.
+            creator_id (int | None): Optional identifier of the user performing the action.
+            history_comment (str | None): Audit comment recorded with the deactivation.
+            ignore_permission (bool): When True, skip permission validation.
 
         Returns:
-            Self: A new manager instance for the deactivated object.
+            Self: Manager instance representing the deactivated object.
+
+        Raises:
+            PermissionError: Propagated if the permission check fails.
         """
         if not ignore_permission:
             self.Permission.checkDeletePermission(self, creator_id)
@@ -171,13 +201,13 @@ class GeneralManager(metaclass=GeneralManagerMeta):
     @classmethod
     def filter(cls, **kwargs: Any) -> Bucket[Self]:
         """
-        Return a bucket of managed objects matching the specified filter criteria.
+        Return a bucket containing managers that satisfy the provided lookups.
 
         Parameters:
-            kwargs: Field lookups used to filter the managed objects.
+            **kwargs (Any): Django-style filter expressions forwarded to the interface.
 
         Returns:
-            Bucket[Self]: A collection of manager instances matching the filter conditions.
+            Bucket[Self]: Bucket of matching manager instances.
         """
         DependencyTracker.track(
             cls.__name__, "filter", f"{cls.__parse_identification(kwargs)}"
@@ -187,13 +217,13 @@ class GeneralManager(metaclass=GeneralManagerMeta):
     @classmethod
     def exclude(cls, **kwargs: Any) -> Bucket[Self]:
         """
-        Return a bucket of managed objects excluding those that match the specified criteria.
+        Return a bucket excluding managers that match the provided lookups.
 
         Parameters:
-            kwargs: Field-value pairs used to determine which objects to exclude.
+            **kwargs (Any): Django-style exclusion expressions forwarded to the interface.
 
         Returns:
-            Bucket[Self]: A collection of managed objects not matching the exclusion criteria.
+            Bucket[Self]: Bucket of manager instances that do not satisfy the lookups.
         """
         DependencyTracker.track(
             cls.__name__, "exclude", f"{cls.__parse_identification(kwargs)}"
@@ -202,25 +232,21 @@ class GeneralManager(metaclass=GeneralManagerMeta):
 
     @classmethod
     def all(cls) -> Bucket[Self]:
-        """
-        Return a bucket containing all managed objects of this class.
-        """
+        """Return a bucket containing every managed object of this class."""
         return cls.Interface.filter()
 
     @staticmethod
     def __parse_identification(kwargs: dict[str, Any]) -> dict[str, Any] | None:
         """
-        Return a dictionary with all GeneralManager instances in the input replaced by their identification dictionaries.
-
-        For each key-value pair in the input, any GeneralManager instance is replaced by its identification. Lists and tuples are processed recursively, substituting contained GeneralManager instances with their identifications. Returns None if the resulting dictionary is empty.
+        Replace manager instances within a filter mapping by their identifications.
 
         Parameters:
-            kwargs (dict[str, Any]): Dictionary to process.
+            kwargs (dict[str, Any]): Mapping containing potential manager instances.
 
         Returns:
-            dict[str, Any] | None: Processed dictionary with identifications, or None if empty.
+            dict[str, Any] | None: Mapping with managers substituted by identification dictionaries, or None if no substitutions occurred.
         """
-        output = {}
+        output: dict[str, Any] = {}
         for key, value in kwargs.items():
             if isinstance(value, GeneralManager):
                 output[key] = value.identification

general_manager/manager/groupManager.py

@@ -1,11 +1,7 @@
+"""Utility manager that aggregates grouped GeneralManager data."""
+
 from __future__ import annotations
-from typing import (
-    Type,
-    Any,
-    Generic,
-    get_args,
-    cast,
-)
+from typing import Any, Generic, Iterator, Type, cast, get_args
 from datetime import datetime, date, time
 from general_manager.api.graphql import GraphQLProperty
 from general_manager.measurement import Measurement
@@ -17,23 +13,37 @@ from general_manager.bucket.baseBucket import (
 
 
 class GroupManager(Generic[GeneralManagerType]):
-    """
-    This class is used to group the data of a GeneralManager.
-    It is used to create a new GeneralManager with the grouped data.
-    """
+    """Represent aggregated results for grouped GeneralManager records."""
 
     def __init__(
         self,
         manager_class: Type[GeneralManagerType],
         group_by_value: dict[str, Any],
         data: Bucket[GeneralManagerType],
-    ):
+    ) -> None:
+        """
+        Initialise a grouped manager with the underlying bucket and grouping keys.
+
+        Parameters:
+            manager_class (type[GeneralManagerType]): Manager subclass whose records were grouped.
+            group_by_value (dict[str, Any]): Key values describing this group.
+            data (Bucket[GeneralManagerType]): Bucket of records belonging to the group.
+
+        Returns:
+            None
+        """
         self._manager_class = manager_class
         self._group_by_value = group_by_value
         self._data = data
         self._grouped_data: dict[str, Any] = {}
 
     def __hash__(self) -> int:
+        """
+        Return a stable hash based on the manager class, keys, and grouped data.
+
+        Returns:
+            int: Hash value combining class, keys, and data.
+        """
         return hash(
             (
                 self._manager_class,
@@ -43,6 +53,15 @@ class GroupManager(Generic[GeneralManagerType]):
         )
 
     def __eq__(self, other: object) -> bool:
+        """
+        Compare grouped managers by manager class, keys, and grouped data.
+
+        Parameters:
+            other (object): Object to compare against.
+
+        Returns:
+            bool: True when both grouped managers describe the same data.
+        """
         return (
             isinstance(other, self.__class__)
             and self._manager_class == other._manager_class
@@ -51,9 +70,21 @@ class GroupManager(Generic[GeneralManagerType]):
         )
 
     def __repr__(self) -> str:
+        """
+        Return a debug representation showing grouped keys and data.
+
+        Returns:
+            str: Debug string summarising the grouped manager.
+        """
         return f"{self.__class__.__name__}({self._manager_class}, {self._group_by_value}, {self._data})"
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[tuple[str, Any]]:
+        """
+        Iterate over attribute names and their aggregated values.
+
+        Yields:
+            tuple[str, Any]: Attribute name and aggregated value pairs.
+        """
         for attribute in self._manager_class.Interface.getAttributes().keys():
             yield attribute, getattr(self, attribute)
         for attribute, attr_value in self._manager_class.__dict__.items():
@@ -61,6 +92,18 @@ class GroupManager(Generic[GeneralManagerType]):
                 yield attribute, getattr(self, attribute)
 
     def __getattr__(self, item: str) -> Any:
+        """
+        Lazily compute aggregated attribute values when accessed.
+
+        Parameters:
+            item (str): Attribute name requested by the caller.
+
+        Returns:
+            Any: Aggregated value stored for the given attribute.
+
+        Raises:
+            AttributeError: If the attribute cannot be resolved from group data.
+        """
         if item in self._group_by_value:
             return self._group_by_value[item]
         if item not in self._grouped_data.keys():
@@ -68,12 +111,24 @@ class GroupManager(Generic[GeneralManagerType]):
         return self._grouped_data[item]
 
     def combineValue(self, item: str) -> Any:
+        """
+        Aggregate attribute values across the grouped records.
+
+        Parameters:
+            item (str): Name of the attribute to aggregate.
+
+        Returns:
+            Any: Aggregated value corresponding to `item`.
+
+        Raises:
+            AttributeError: If the attribute is not defined on the manager or property set.
+        """
         if item == "id":
             return None
 
-        data_type = (
-            self._manager_class.Interface.getAttributeTypes().get(item, {}).get("type")
-        )
+        attribute_types = self._manager_class.Interface.getAttributeTypes()
+        attr_info = attribute_types.get(item)
+        data_type = attr_info["type"] if attr_info else None
         if data_type is None and item in self._manager_class.__dict__:
             attr_value = self._manager_class.__dict__[item]
             if isinstance(attr_value, GraphQLProperty):
@@ -83,7 +138,7 @@ class GroupManager(Generic[GeneralManagerType]):
                     if type_hints
                     else cast(type, attr_value.graphql_type_hint)
                 )
-        if data_type is None:
+        if data_type is None or not isinstance(data_type, type):
             raise AttributeError(f"{self.__class__.__name__} has no attribute {item}")
 
         total_data = []