GeneralManager 0.14.0__py3-none-any.whl → 0.15.0__py3-none-any.whl

general_manager/factory/factories.py

@@ -1,8 +1,10 @@
+"""Helpers for generating realistic factory values for Django models."""
+
 from __future__ import annotations
 from typing import Any, cast, TYPE_CHECKING
 from factory.declarations import LazyFunction
 from factory.faker import Faker
-import exrex
+import exrex  # type: ignore[import-untyped]
 from django.db import models
 from django.core.validators import RegexValidator
 import random
@@ -19,9 +21,16 @@ def getFieldValue(
     field: models.Field[Any, Any] | models.ForeignObjectRel,
 ) -> object:
     """
-    Generate a suitable fake or factory value for a given Django model field, for use in tests or data factories.
-    
-    Returns a value appropriate for the field type, including support for measurement, text, numeric, date/time, boolean, email, URL, IP address, UUID, duration, and character fields (with regex support). For relational fields (OneToOneField and ForeignKey), attempts to use a related model factory or select a random existing instance; raises ValueError if neither is available. Returns None for unsupported field types or with a 10% chance if the field allows null values.
+    Generate a realistic value for a Django model field.
+
+    Parameters:
+        field (models.Field | models.ForeignObjectRel): Field definition to generate a value for.
+
+    Returns:
+        object: Value appropriate for the field type.
+
+    Raises:
+        ValueError: If a related model lacks both a factory and existing instances.
     """
     if field.null:
         if random.choice([True] + 9 * [False]):
@@ -29,7 +38,7 @@ def getFieldValue(
 
     if isinstance(field, MeasurementField):
 
-        def _measurement():
+        def _measurement() -> Measurement:
             value = Decimal(random.randrange(0, 10_000_000)) / Decimal("100")  # two dp
             return Measurement(value, field.base_unit)
 
@@ -135,29 +144,45 @@ def getRelatedModel(
     field: models.ForeignObjectRel | models.Field[Any, Any],
 ) -> type[models.Model]:
     """
-    Return the related model class for a given Django relational field.
-    
+    Return the related model class for the given relational field.
+
+    Parameters:
+        field (models.Field | models.ForeignObjectRel): Relational field to inspect.
+
+    Returns:
+        type[models.Model]: Related model class.
+
     Raises:
-        ValueError: If the field does not have a related model defined.
+        ValueError: If the field does not declare a related model.
     """
     related_model = field.related_model
     if related_model is None:
         raise ValueError(f"Field {field.name} does not have a related model defined.")
     if related_model == "self":
         related_model = field.model
-    return related_model  # For unsupported field types
+    if not isinstance(related_model, type) or not issubclass(
+        related_model, models.Model
+    ):
+        raise TypeError(
+            f"Related model for {field.name} must be a Django model class, got {related_model!r}"
+        )
+    return cast(type[models.Model], related_model)
 
 
 def getManyToManyFieldValue(
     field: models.ManyToManyField,
 ) -> list[models.Model]:
     """
-    Generate a list of model instances to associate with a ManyToMany field for testing or factory purposes.
-    
-    If a related model factory is available, creates new instances as needed. Otherwise, selects from existing instances. Raises a ValueError if neither a factory nor existing instances are available.
-    
+    Produce sample related instances for a ManyToMany field.
+
+    Parameters:
+        field (models.ManyToManyField): Field definition whose values should be generated.
+
     Returns:
-        list[models.Model]: A list of related model instances for the ManyToMany field.
+        list[models.Model]: List of related instances to assign to the field.
+
+    Raises:
+        ValueError: If neither factories nor existing instances are available.
     """
     related_factory = None
     related_model = getRelatedModel(field)

general_manager/factory/factoryMethods.py

@@ -1,3 +1,5 @@
+"""Convenience helpers for defining factory_boy lazy attributes."""
+
 from typing import Any, Optional
 from factory.declarations import LazyFunction, LazyAttribute, LazyAttributeSequence
 import random
@@ -13,12 +15,26 @@ fake = Faker()
 def LazyMeasurement(
     min_value: int | float, max_value: int | float, unit: str
 ) -> LazyFunction:
+    """
+    Return a lazy factory producing ``Measurement`` values in the given range.
+
+    Parameters:
+        min_value (int | float): Minimum magnitude.
+        max_value (int | float): Maximum magnitude.
+        unit (str): Measurement unit.
+    """
     return LazyFunction(
-        lambda: Measurement(str(random.uniform(min_value, max_value))[:10], unit)
+        lambda: Measurement(f"{random.uniform(min_value, max_value):.6f}", unit)
     )
 
 
 def LazyDeltaDate(avg_delta_days: int, base_attribute: str) -> LazyAttribute:
+    """Return a lazy attribute that offsets a base date by a random delta.
+
+    Parameters:
+        avg_delta_days (int): Average number of days to offset.
+        base_attribute (str): Name of the attribute providing the base date.
+    """
     return LazyAttribute(
         lambda obj: (getattr(obj, base_attribute) or date.today())
         + timedelta(days=random.randint(avg_delta_days // 2, avg_delta_days * 3 // 2))
@@ -26,6 +42,7 @@ def LazyDeltaDate(avg_delta_days: int, base_attribute: str) -> LazyAttribute:
 
 
 def LazyProjectName() -> LazyFunction:
+    """Return a lazy factory producing a pseudo-random project-style name."""
     return LazyFunction(
         lambda: (
             f"{fake.word().capitalize()} "
@@ -37,28 +54,39 @@ def LazyProjectName() -> LazyFunction:
 
 
 def LazyDateToday() -> LazyFunction:
+    """Return a lazy factory that yields today's date."""
     return LazyFunction(lambda: date.today())
 
 
 def LazyDateBetween(start_date: date, end_date: date) -> LazyAttribute:
+    """Return a lazy attribute producing dates within the supplied range."""
     delta = (end_date - start_date).days
+    if delta < 0:
+        start_date, end_date = end_date, start_date
+        delta = -delta
     return LazyAttribute(
         lambda obj: start_date + timedelta(days=random.randint(0, delta))
     )
 
 
 def LazyDateTimeBetween(start: datetime, end: datetime) -> LazyAttribute:
+    """Return a lazy attribute producing datetimes within the supplied range."""
     span = (end - start).total_seconds()
+    if span < 0:
+        start, end = end, start
+        span = -span
     return LazyAttribute(
         lambda obj: start + timedelta(seconds=random.randint(0, int(span)))
     )
 
 
 def LazyInteger(min_value: int, max_value: int) -> LazyFunction:
+    """Return a lazy factory yielding random integers within the bounds."""
     return LazyFunction(lambda: random.randint(min_value, max_value))
 
 
 def LazyDecimal(min_value: float, max_value: float, precision: int = 2) -> LazyFunction:
+    """Return a lazy factory yielding Decimal values within the bounds."""
     fmt = f"{{:.{precision}f}}"
     return LazyFunction(
         lambda: Decimal(fmt.format(random.uniform(min_value, max_value)))
@@ -66,28 +94,34 @@ def LazyDecimal(min_value: float, max_value: float, precision: int = 2) -> LazyF
 
 
 def LazyChoice(options: list[Any]) -> LazyFunction:
+    """Return a lazy factory selecting a random element from the options."""
     return LazyFunction(lambda: random.choice(options))
 
 
 def LazySequence(start: int = 0, step: int = 1) -> LazyAttributeSequence:
+    """Return a lazy attribute sequence starting at ``start`` with ``step`` increments."""
     return LazyAttributeSequence(lambda obj, n: start + n * step)
 
 
 def LazyBoolean(trues_ratio: float = 0.5) -> LazyFunction:
+    """Return a lazy factory yielding booleans with the given true ratio."""
     return LazyFunction(lambda: random.random() < trues_ratio)
 
 
 def LazyUUID() -> LazyFunction:
+    """Return a lazy factory producing UUID4 strings."""
     return LazyFunction(lambda: str(uuid.uuid4()))
 
 
 def LazyFakerName() -> LazyFunction:
+    """Return a lazy factory producing names using Faker."""
     return LazyFunction(lambda: fake.name())
 
 
 def LazyFakerEmail(
     name: Optional[str] = None, domain: Optional[str] = None
 ) -> LazyFunction:
+    """Return a lazy factory producing email addresses with optional overrides."""
     if not name and not domain:
         return LazyFunction(lambda: fake.email(domain=domain))
     if not name:
@@ -98,12 +132,15 @@ def LazyFakerEmail(
 
 
 def LazyFakerSentence(number_of_words: int = 6) -> LazyFunction:
+    """Return a lazy factory producing fake sentences."""
     return LazyFunction(lambda: fake.sentence(nb_words=number_of_words))
 
 
 def LazyFakerAddress() -> LazyFunction:
+    """Return a lazy factory producing fake postal addresses."""
     return LazyFunction(lambda: fake.address())
 
 
 def LazyFakerUrl() -> LazyFunction:
+    """Return a lazy factory producing fake URLs."""
     return LazyFunction(lambda: fake.url())

general_manager/interface/__init__.py

@@ -0,0 +1,36 @@
+"""Public interface classes for GeneralManager implementations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from general_manager.utils.public_api import build_module_dir, resolve_export
+
+__all__ = [
+    "InterfaceBase",
+    "DBBasedInterface",
+    "DatabaseInterface",
+    "ReadOnlyInterface",
+    "CalculationInterface",
+]
+
+_MODULE_MAP = {
+    "InterfaceBase": "general_manager.interface.baseInterface",
+    "DBBasedInterface": "general_manager.interface.databaseBasedInterface",
+    "DatabaseInterface": "general_manager.interface.databaseInterface",
+    "ReadOnlyInterface": "general_manager.interface.readOnlyInterface",
+    "CalculationInterface": "general_manager.interface.calculationInterface",
+}
+
+
+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/interface/baseInterface.py

@@ -1,3 +1,5 @@
+"""Abstract interface layer shared by all GeneralManager implementations."""
+
 from __future__ import annotations
 from abc import ABC, abstractmethod
 from typing import (
@@ -9,6 +11,7 @@ from typing import (
     ClassVar,
     Callable,
     TypedDict,
+    cast,
 )
 from datetime import datetime
 from django.conf import settings
@@ -43,11 +46,7 @@ type classPostCreationMethod = Callable[
 
 
 class AttributeTypedDict(TypedDict):
-    """
-    This class is used to define the type of the attributes dictionary.
-    It is used to define the type of the attributes dictionary in the
-    GeneralManager class.
-    """
+    """Describe metadata captured for each interface attribute."""
 
     type: type
     default: Any
@@ -57,29 +56,49 @@ class AttributeTypedDict(TypedDict):
 
 
 class InterfaceBase(ABC):
+    """Common base API for interfaces backing GeneralManager classes."""
+
     _parent_class: Type[GeneralManager]
     _interface_type: ClassVar[str]
     input_fields: dict[str, Input]
 
-    def __init__(self, *args: Any, **kwargs: Any):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """
+        Construct the interface using the supplied identification arguments.
+
+        Parameters:
+            *args: Positional arguments passed to the interface constructor.
+            **kwargs: Keyword arguments passed to the interface constructor.
+
+        Returns:
+            None
+        """
         identification = self.parseInputFieldsToIdentification(*args, **kwargs)
         self.identification = self.formatIdentification(identification)
 
     def parseInputFieldsToIdentification(
         self,
         *args: Any,
-        **kwargs: dict[str, Any],
+        **kwargs: Any,
     ) -> dict[str, Any]:
         """
-        Parse and validate input arguments into a dictionary of input field values.
+        Parse raw arguments into a validated identification mapping.
 
-        Positional and keyword arguments are mapped to input field names, with normalization of argument names (e.g., removing trailing `_id`). Ensures all required fields are present and no unexpected arguments are provided. Processes input fields in dependency order, casting and validating each value. Raises a `TypeError` for missing or unexpected arguments and a `ValueError` if circular dependencies are detected.
+        Parameters:
+            *args (Any): Positional arguments matched to the interface's input field order.
+            **kwargs (dict[str, Any]): Keyword arguments supplied by the caller.
 
         Returns:
-            dict[str, Any]: A dictionary mapping input field names to their validated and cast values.
+            dict[str, Any]: Mapping of input field names to validated values.
+
+        Raises:
+            TypeError: If required inputs are missing, unexpected inputs are provided, or a value fails type checking.
+            ValueError: If circular dependencies prevent resolution of the inputs.
         """
-        identification = {}
-        kwargs = args_to_kwargs(args, self.input_fields.keys(), kwargs)
+        identification: dict[str, Any] = {}
+        kwargs = cast(
+            dict[str, Any], args_to_kwargs(args, self.input_fields.keys(), kwargs)
+        )
         # Check for extra arguments
         extra_args = set(kwargs.keys()) - set(self.input_fields.keys())
         if extra_args:
@@ -94,7 +113,7 @@ class InterfaceBase(ABC):
             raise TypeError(f"Missing required arguments: {', '.join(missing_args)}")
 
         # process input fields with dependencies
-        processed = set()
+        processed: set[str] = set()
         while len(processed) < len(self.input_fields):
             progress_made = False
             for name, input_field in self.input_fields.items():
@@ -117,6 +136,15 @@ class InterfaceBase(ABC):
 
     @staticmethod
     def formatIdentification(identification: dict[str, Any]) -> dict[str, Any]:
+        """
+        Normalise identification data by replacing manager instances with their IDs.
+
+        Parameters:
+            identification (dict[str, Any]): Raw identification mapping possibly containing manager instances.
+
+        Returns:
+            dict[str, Any]: Identification mapping with nested managers replaced by their identifications.
+        """
         from general_manager.manager.generalManager import GeneralManager
 
         for key, value in identification.items():
@@ -141,9 +169,19 @@ class InterfaceBase(ABC):
         self, name: str, value: Any, identification: dict[str, Any]
     ) -> None:
         """
-        Validates the type and allowed values of an input field.
+        Validate a single input value against its definition.
+
+        Parameters:
+            name (str): Input field name being processed.
+            value (Any): Value provided by the caller.
+            identification (dict[str, Any]): Partially resolved identification mapping used to evaluate dependencies.
 
-        Ensures that the provided value matches the expected type for the specified input field. In debug mode, also checks that the value is among the allowed possible values if defined, supporting both callables and iterables. Raises a TypeError for invalid types or possible value definitions, and a ValueError if the value is not permitted.
+        Returns:
+            None
+
+        Raises:
+            TypeError: If the value has the wrong type or possible values are misconfigured.
+            ValueError: If the value is not permitted by the configured `possible_values`.
         """
         input_field = self.input_fields[name]
         if not isinstance(value, input_field.type):
@@ -173,31 +211,37 @@ class InterfaceBase(ABC):
 
     @classmethod
     def create(cls, *args: Any, **kwargs: Any) -> Any:
+        """Create a new record via the underlying data source."""
         raise NotImplementedError
 
     def update(self, *args: Any, **kwargs: Any) -> Any:
+        """Update the underlying record."""
         raise NotImplementedError
 
     def deactivate(self, *args: Any, **kwargs: Any) -> Any:
+        """Deactivate the underlying record."""
         raise NotImplementedError
 
     @abstractmethod
     def getData(self, search_date: datetime | None = None) -> Any:
+        """Return data materialised for the manager object."""
         raise NotImplementedError
 
     @classmethod
     @abstractmethod
     def getAttributeTypes(cls) -> dict[str, AttributeTypedDict]:
+        """Return metadata describing each attribute exposed on the manager."""
         raise NotImplementedError
 
     @classmethod
     @abstractmethod
     def getAttributes(cls) -> dict[str, Any]:
+        """Return attribute values exposed via the interface."""
         raise NotImplementedError
 
     @classmethod
     def getGraphQLProperties(cls) -> dict[str, GraphQLProperty]:
-        """Return GraphQL properties defined on the parent manager."""
+        """Return GraphQLProperty descriptors defined on the parent manager class."""
         if not hasattr(cls, "_parent_class"):
             return {}
         return {
@@ -209,11 +253,13 @@ class InterfaceBase(ABC):
     @classmethod
     @abstractmethod
     def filter(cls, **kwargs: Any) -> Bucket[Any]:
+        """Return a bucket filtered by the provided lookup expressions."""
         raise NotImplementedError
 
     @classmethod
     @abstractmethod
     def exclude(cls, **kwargs: Any) -> Bucket[Any]:
+        """Return a bucket excluding records that match the provided lookup expressions."""
         raise NotImplementedError
 
     @classmethod
@@ -225,13 +271,11 @@ class InterfaceBase(ABC):
         classPostCreationMethod,
     ]:
         """
-        This method returns a pre and a post GeneralManager creation method
-        and is called inside the GeneralManagerMeta class to initialize the
-        Interface.
-        The pre creation method is called before the GeneralManager instance
-        is created to modify the kwargs.
-        The post creation method is called after the GeneralManager instance
-        is created to modify the instance and add additional data.
+        Return hooks executed around GeneralManager class creation.
+
+        Returns:
+            tuple[classPreCreationMethod, classPostCreationMethod]:
+                Callables executed before and after the manager class is created.
         """
         raise NotImplementedError
 
@@ -239,13 +283,13 @@ class InterfaceBase(ABC):
     @abstractmethod
     def getFieldType(cls, field_name: str) -> type:
         """
-        Returns the type of the specified input field.
+        Return the declared Python type for an input field.
 
-        Args:
-            field_name: The name of the input field.
+        Parameters:
+            field_name (str): Name of the input field.
 
         Returns:
-            The Python type associated with the given field name.
+            type: Python type associated with the field.
 
         Raises:
             NotImplementedError: This method must be implemented by subclasses.

general_manager/interface/calculationInterface.py

@@ -1,3 +1,5 @@
+"""Interface implementation for calculation-style GeneralManager classes."""
+
 from __future__ import annotations
 from datetime import datetime
 from typing import Any
@@ -18,6 +20,7 @@ from general_manager.bucket.calculationBucket import CalculationBucket
 
 
 class CalculationInterface(InterfaceBase):
+    """Interface exposing calculation inputs without persisting data."""
     _interface_type = "calculation"
     input_fields: dict[str, Input]
 
@@ -44,6 +47,7 @@ class CalculationInterface(InterfaceBase):
 
     @classmethod
     def getAttributes(cls) -> dict[str, Any]:
+        """Return attribute accessors that cast values using the configured inputs."""
         return {
             name: lambda self, name=name: cls.input_fields[name].cast(
                 self.identification.get(name)
@@ -53,14 +57,17 @@ class CalculationInterface(InterfaceBase):
 
     @classmethod
     def filter(cls, **kwargs: Any) -> CalculationBucket:
+        """Return a calculation bucket filtered by the given parameters."""
         return CalculationBucket(cls._parent_class).filter(**kwargs)
 
     @classmethod
     def exclude(cls, **kwargs: Any) -> CalculationBucket:
+        """Return a calculation bucket excluding items matching the parameters."""
         return CalculationBucket(cls._parent_class).exclude(**kwargs)
 
     @classmethod
     def all(cls) -> CalculationBucket:
+        """Return a calculation bucket containing all combinations."""
         return CalculationBucket(cls._parent_class).all()
 
     @staticmethod
@@ -68,12 +75,15 @@ class CalculationInterface(InterfaceBase):
         name: generalManagerClassName, attrs: attributes, interface: interfaceBaseClass
     ) -> tuple[attributes, interfaceBaseClass, None]:
         """
-        Prepare and return updated attributes and a new interface class for GeneralManager creation.
+        Prepare interface attributes prior to GeneralManager class creation.
 
-        Collects all `Input` instances from the provided interface class, sets the interface type in the attributes, dynamically creates a new interface class with an `input_fields` attribute, and adds this class to the attributes dictionary.
+        Parameters:
+            name (generalManagerClassName): Name of the new manager class.
+            attrs (attributes): Attribute dictionary for the manager being created.
+            interface (interfaceBaseClass): Base interface definition.
 
         Returns:
-            tuple: A tuple containing the updated attributes dictionary, the new interface class, and None.
+            tuple[attributes, interfaceBaseClass, None]: Updated attributes, interface class, and related model (None).
         """
         input_fields: dict[str, Input[Any]] = {}
         for key, value in vars(interface).items():
@@ -96,18 +106,16 @@ class CalculationInterface(InterfaceBase):
         interface_class: newlyCreatedInterfaceClass,
         model: relatedClass,
     ) -> None:
+        """Link the generated interface to the manager class after creation."""
         interface_class._parent_class = new_class
 
     @classmethod
     def handleInterface(cls) -> tuple[classPreCreationMethod, classPostCreationMethod]:
         """
-        This method returns a pre and a post GeneralManager creation method
-        and is called inside the GeneralManagerMeta class to initialize the
-        Interface.
-        The pre creation method is called before the GeneralManager instance
-        is created to modify the kwargs.
-        The post creation method is called after the GeneralManager instance
-        is created to modify the instance and add additional data.
+        Return the pre- and post-creation hooks used by ``GeneralManagerMeta``.
+
+        Returns:
+            tuple[classPreCreationMethod, classPostCreationMethod]: Hook functions invoked around manager creation.
         """
         return cls._preCreate, cls._postCreate