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

general_manager/measurement/measurementField.py

@@ -1,3 +1,5 @@
+"""Custom Django model field storing values as unit-aware measurements."""
+
 from __future__ import annotations
 
 from django.db import models
@@ -6,50 +8,96 @@ from django.db.models.expressions import Col
 from decimal import Decimal
 import pint
 from general_manager.measurement.measurement import Measurement, ureg, currency_units
+from django.db.backends.base.base import BaseDatabaseWrapper
+from django.db.models import Lookup, Transform
+from typing import Any, ClassVar, cast
 
 
 class MeasurementField(models.Field):
     description = "Stores a measurement (value + unit) but exposes a single field API"
 
-    empty_values = (None, "", [], (), {})
+    empty_values: ClassVar[tuple[object, ...]] = (None, "", [], (), {})
 
     def __init__(
-        self, base_unit: str, *args, null=False, blank=False, editable=True, **kwargs
-    ):
+        self,
+        base_unit: str,
+        *args: object,
+        null: bool = False,
+        blank: bool = False,
+        editable: bool = True,
+        **kwargs: object,
+    ) -> None:
         """
-        Initialize a MeasurementField to store a numeric value and its unit with unit-aware validation.
+        Configure a measurement field backed by separate value and unit columns.
 
         Parameters:
-            base_unit (str): The canonical unit for the measurement, used for conversions and validation.
-            null (bool, optional): Whether the field allows NULL values. Defaults to False.
-            blank (bool, optional): Whether the field allows blank values. Defaults to False.
-            editable (bool, optional): Whether the field is editable in forms and admin. Defaults to True.
+            base_unit (str): Canonical unit used when normalising stored measurements.
+            args (tuple): Positional arguments forwarded to the base `Field` implementation.
+            null (bool): If True, the measurement may be stored as NULL.
+            blank (bool): If True, forms may submit an empty value.
+            editable (bool): If False, assignments through the API raise a validation error.
+            kwargs (dict): Additional keyword arguments forwarded to the base `Field`.
 
-        The field internally manages a DecimalField for the value and a CharField for the unit, both configured according to the provided options.
+        Returns:
+            None
         """
         self.base_unit = base_unit
         self.base_dimension = ureg.parse_expression(self.base_unit).dimensionality
 
-        nb = {}
-        if null:
-            nb["null"] = True
-        if blank:
-            nb["blank"] = True
-
         self.editable = editable
-        self.value_field = models.DecimalField(
-            max_digits=30, decimal_places=10, db_index=True, editable=editable, **nb
-        )
-        self.unit_field = models.CharField(max_length=30, editable=editable, **nb)
+        self.value_field: models.DecimalField[Any]
+        self.unit_field: models.CharField[Any]
+        if null:
+            self.value_field = models.DecimalField(
+                max_digits=30,
+                decimal_places=10,
+                db_index=True,
+                editable=editable,
+                null=True,
+                blank=blank,
+            )
+            self.unit_field = models.CharField(
+                max_length=30,
+                editable=editable,
+                null=True,
+                blank=blank,
+            )
+        else:
+            self.value_field = models.DecimalField(
+                max_digits=30,
+                decimal_places=10,
+                db_index=True,
+                editable=editable,
+                null=False,
+                blank=blank,
+            )
+            self.unit_field = models.CharField(
+                max_length=30,
+                editable=editable,
+                null=False,
+                blank=blank,
+            )
 
         super().__init__(*args, null=null, blank=blank, editable=editable, **kwargs)
 
-    def contribute_to_class(self, cls, name, private_only=False, **kwargs):
-        # Register myself first (so opts.get_field('height') works)
+    def contribute_to_class(
+        self,
+        cls: type[models.Model],
+        name: str,
+        private_only: bool = False,
+        **kwargs: object,
+    ) -> None:
         """
-        Registers the MeasurementField with the model class and attaches internal value and unit fields.
+        Attach the measurement field and its backing columns to a Django model.
+
+        Parameters:
+            cls (type[models.Model]): Model class receiving the field.
+            name (str): Attribute name of the field on the model.
+            private_only (bool): Whether the field should be treated as private.
+            kwargs (dict): Additional options forwarded to the base implementation.
 
-        This method sets up the composite field by creating and adding separate fields for the numeric value and unit to the model class, ensuring they are not duplicated. It also overrides the model attribute with the MeasurementField descriptor itself to manage access and assignment.
+        Returns:
+            None
         """
         super().contribute_to_class(cls, name, private_only=private_only, **kwargs)
         self.concrete = False
@@ -76,47 +124,72 @@ class MeasurementField(models.Field):
         setattr(cls, name, self)
 
     # ---- ORM Delegation ----
-    def get_col(self, alias, output_field=None):
+    def get_col(
+        self,
+        alias: str,
+        output_field: models.Field[object, object] | None = None,
+    ) -> Col:
         """
-        Returns a Django ORM column expression for the internal value field, enabling queries on the numeric part of the measurement.
+        Produce a column expression referencing the underlying value field.
+
+        Parameters:
+            alias (str): Table alias used within the query.
+            output_field (models.Field | None): Optional output field override.
+
+        Returns:
+            Col: ORM expression targeting the numeric component.
         """
         return Col(alias, self.value_field, output_field or self.value_field)  # type: ignore
 
-    def get_lookup(self, lookup_name):
+    def get_lookup(self, lookup_name: str) -> type[Lookup]:
         """
-        Return the lookup class for the specified lookup name, delegating to the internal value field.
+        Retrieve a lookup class from the underlying decimal field.
 
         Parameters:
-                lookup_name (str): The name of the lookup to retrieve.
+            lookup_name (str): Name of the lookup to resolve.
 
         Returns:
-                The lookup class corresponding to the given name, as provided by the internal decimal value field.
+            type[models.Lookup]: Lookup class implementing the requested comparison.
         """
-        return self.value_field.get_lookup(lookup_name)
+        return cast(type[Lookup], self.value_field.get_lookup(lookup_name))
 
-    def get_transform(self, lookup_name) -> models.Transform | None:
+    def get_transform(
+        self,
+        lookup_name: str,
+    ) -> type[Transform] | None:
         """
-        Delegates retrieval of a transform operation to the internal value field.
+        Return a transform callable provided by the underlying decimal field.
+
+        Parameters:
+            lookup_name (str): Name of the transform to resolve.
 
         Returns:
-            The transform corresponding to the given lookup name, or None if not found.
+            models.Transform | None: Transform class when available; otherwise None.
         """
-        return self.value_field.get_transform(lookup_name)
+        transform = self.value_field.get_transform(lookup_name)
+        return cast(type[Transform] | None, transform)
 
-    def db_type(self, connection) -> None:  # type: ignore
+    def db_type(self, connection: BaseDatabaseWrapper) -> None:  # type: ignore[override]
         """
-        Return None to indicate that MeasurementField does not correspond to a single database column.
+        Signal to Django that the field does not map to a single column.
+
+        Parameters:
+            connection (BaseDatabaseWrapper): Database connection used for schema generation.
 
-        This field manages its data using separate internal fields and does not require a direct database type.
+        Returns:
+            None
         """
         return None
 
     def run_validators(self, value: Measurement | None) -> None:
         """
-        Runs all validators on the provided Measurement value if it is not None.
+        Execute all configured validators when a measurement is provided.
 
         Parameters:
-            value (Measurement | None): The measurement to validate, or None to skip validation.
+            value (Measurement | None): Measurement instance that should satisfy field validators.
+
+        Returns:
+            None
         """
         if value is None:
             return
@@ -127,40 +200,46 @@ class MeasurementField(models.Field):
         self, value: Measurement | None, model_instance: models.Model | None = None
     ) -> Measurement | None:
         """
-        Validates and cleans a Measurement value for use in the model field.
-
-        Runs field-level validation and all configured validators on the provided value, returning it unchanged if valid.
+        Validate a measurement value before it is saved to the model.
 
         Parameters:
-            value (Measurement | None): The measurement value to validate and clean.
-            model_instance (models.Model | None): The model instance this value is associated with, if any.
+            value (Measurement | None): Measurement provided by forms or assignment.
+            model_instance (models.Model | None): Instance associated with the field, when available.
 
         Returns:
             Measurement | None: The validated measurement value, or None if the input was None.
+
+        Raises:
+            ValidationError: If validation fails due to null/blank constraints or validator errors.
         """
         self.validate(value, model_instance)
         self.run_validators(value)
         return value
 
-    def to_python(self, value):
+    def to_python(self, value: Measurement | str | None) -> Measurement | str | None:
         """
-        Returns the input value unchanged.
+        Convert database values back into Python objects.
+
+        Parameters:
+            value (Any): Value retrieved from the database.
 
-        This method is required by Django custom fields to convert database values to Python objects, but no conversion is performed for this field.
+        Returns:
+            Any: Original value without modification.
         """
         return value
 
-    def get_prep_value(self, value):
+    def get_prep_value(self, value: Measurement | str | None) -> Decimal | None:
         """
-        Prepare a value for database storage by converting a Measurement to its decimal magnitude in the base unit.
+        Serialise a measurement for storage by converting it to the base unit magnitude.
 
-        If the input is a string, it is parsed into a Measurement. If the value cannot be converted to the base unit due to dimensionality mismatch, a ValidationError is raised. Only Measurement instances or None are accepted.
+        Parameters:
+            value (Measurement | str | None): Value provided by the model or form.
 
         Returns:
-            Decimal: The numeric value of the measurement in the base unit, or None if the input is None.
+            Decimal | None: Decimal magnitude in the base unit, or None when no value is supplied.
 
         Raises:
-            ValidationError: If the value is not a Measurement or cannot be converted to the base unit.
+            ValidationError: If the value cannot be interpreted as a compatible measurement.
         """
         if value is None:
             return None
@@ -182,12 +261,14 @@ class MeasurementField(models.Field):
         self, instance: models.Model | None, owner: None = None
     ) -> MeasurementField | Measurement | None:
         """
-        Retrieve the measurement value from the model instance, reconstructing it as a `Measurement` object with the stored unit.
+        Resolve the field value on an instance, reconstructing the measurement when possible.
+
+        Parameters:
+            instance (models.Model | None): Model instance owning the field, or None when accessed on the class.
+            owner (type[models.Model] | None): Model class owning the descriptor.
 
         Returns:
-            Measurement: The measurement with its original unit if both value and unit are present.
-            None: If either the value or unit is missing.
-            MeasurementField: If accessed from the class rather than an instance.
+            MeasurementField | Measurement | None: Descriptor when accessed on the class, reconstructed measurement for instances, or None when incomplete.
         """
         if instance is None:
             return self
@@ -202,11 +283,23 @@ class MeasurementField(models.Field):
             qty_orig = qty_base
         return Measurement(qty_orig.magnitude, str(qty_orig.units))
 
-    def __set__(self, instance, value):
+    def __set__(
+        self,
+        instance: models.Model,
+        value: Measurement | str | None,
+    ) -> None:
         """
-        Assigns a measurement value to the model instance, validating type, unit compatibility, and editability.
+        Assign a measurement to the model instance after validating compatibility.
+
+        Parameters:
+            instance (models.Model): Model instance receiving the value.
+            value (Measurement | str | None): Measurement value supplied by the caller.
+
+        Returns:
+            None
 
-        If the value is a string, attempts to parse it as a Measurement. Ensures the unit matches the expected base unit's dimensionality or currency status. Stores the numeric value (converted to the base unit) and the original unit string in the instance. Raises ValidationError if the value is invalid or incompatible.
+        Raises:
+            ValidationError: If the field is not editable, the value is invalid, or the units are incompatible.
         """
         if not self.editable:
             raise ValidationError(f"{self.name} is not editable.")
@@ -253,10 +346,17 @@ class MeasurementField(models.Field):
         self, value: Measurement | None, model_instance: models.Model | None = None
     ) -> None:
         """
-        Validates a measurement value against null and blank constraints and applies all field validators.
+        Enforce null/blank constraints and run validators on the provided value.
+
+        Parameters:
+            value (Measurement | None): Measurement value under validation.
+            model_instance (models.Model | None): Instance owning the field; unused but provided for API compatibility.
+
+        Returns:
+            None
 
         Raises:
-            ValidationError: If the value is None and the field does not allow nulls, or if the value is blank and the field does not allow blanks, or if any validator fails.
+            ValidationError: If the value violates constraint or validator requirements.
         """
         if value is None:
             if not self.null:

general_manager/permission/__init__.py

@@ -1 +1,32 @@
-from .managerBasedPermission import ManagerBasedPermission
+"""Permission helpers for GeneralManager mutations and actions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from general_manager.utils.public_api import build_module_dir, resolve_export
+
+__all__ = [
+    "BasePermission",
+    "ManagerBasedPermission",
+    "MutationPermission",
+]
+
+_MODULE_MAP = {
+    "BasePermission": ("general_manager.permission.basePermission", "BasePermission"),
+    "ManagerBasedPermission": ("general_manager.permission.managerBasedPermission", "ManagerBasedPermission"),
+    "MutationPermission": ("general_manager.permission.mutationPermission", "MutationPermission"),
+}
+
+
+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/permission/basePermission.py

@@ -1,3 +1,5 @@
+"""Base permission contract used by GeneralManager instances."""
+
 from __future__ import annotations
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any, Literal
@@ -16,21 +18,25 @@ if TYPE_CHECKING:
 
 
 class BasePermission(ABC):
+    """Abstract base class defining CRUD permission checks for managers."""
 
     def __init__(
         self,
         instance: PermissionDataManager | GeneralManager | GeneralManagerMeta,
         request_user: AbstractUser | AnonymousUser,
     ) -> None:
+        """Initialise the permission context for a specific manager and user."""
         self._instance = instance
         self._request_user = request_user
 
     @property
     def instance(self) -> PermissionDataManager | GeneralManager | GeneralManagerMeta:
+        """Return the object against which permission checks are performed."""
         return self._instance
 
     @property
     def request_user(self) -> AbstractUser | AnonymousUser:
+        """Return the user being evaluated for permission checks."""
         return self._request_user
 
     @classmethod
@@ -40,6 +46,7 @@ class BasePermission(ABC):
         manager: type[GeneralManager],
         request_user: AbstractUser | AnonymousUser | Any,
     ) -> None:
+        """Validate create permissions for the supplied payload."""
         request_user = cls.getUserWithId(request_user)
         errors = []
         permission_data = PermissionDataManager(permission_data=data, manager=manager)
@@ -62,6 +69,7 @@ class BasePermission(ABC):
         old_manager_instance: GeneralManager,
         request_user: AbstractUser | AnonymousUser | Any,
     ) -> None:
+        """Validate update permissions for the supplied payload."""
         request_user = cls.getUserWithId(request_user)
 
         errors = []
@@ -86,6 +94,7 @@ class BasePermission(ABC):
         manager_instance: GeneralManager,
         request_user: AbstractUser | AnonymousUser | Any,
     ) -> None:
+        """Validate delete permissions for the supplied manager instance."""
         request_user = cls.getUserWithId(request_user)
 
         errors = []
@@ -106,9 +115,7 @@ class BasePermission(ABC):
     def getUserWithId(
         user: Any | AbstractUser | AnonymousUser,
     ) -> AbstractUser | AnonymousUser:
-        """
-        Returns the user with the given id
-        """
+        """Return a ``User`` instance given a primary key or user object."""
         from django.contrib.auth.models import User
 
         if isinstance(user, (AbstractUser, AnonymousUser)):
@@ -124,22 +131,28 @@ class BasePermission(ABC):
         action: Literal["create", "read", "update", "delete"],
         attriubte: str,
     ) -> bool:
+        """
+        Determine whether the given action is permitted on the specified attribute.
+
+        Parameters:
+            action (Literal["create", "read", "update", "delete"]): Operation being checked.
+            attriubte (str): Attribute name subject to the permission check.
+
+        Returns:
+            bool: True when the action is allowed.
+        """
         raise NotImplementedError
 
     def getPermissionFilter(
         self,
     ) -> list[dict[Literal["filter", "exclude"], dict[str, str]]]:
-        """
-        Returns the filter for the permission
-        """
+        """Return the filter/exclude constraints associated with this permission."""
         raise NotImplementedError
 
     def _getPermissionFilter(
         self, permission: str
     ) -> dict[Literal["filter", "exclude"], dict[str, str]]:
-        """
-        Returns the filter for the permission
-        """
+        """Resolve a filter definition for the given permission string."""
         permission_function, *config = permission.split(":")
         if permission_function not in permission_functions:
             raise ValueError(f"Permission {permission} not found")
@@ -155,8 +168,12 @@ class BasePermission(ABC):
         permission: str,
     ) -> bool:
         """
-        Validates a permission string which can be a combination of multiple permissions
-        separated by "&" (e.g. "isAuthenticated&isMatchingKeyAccount").
-        This means that all sub_permissions must be true.
+        Validate complex permission expressions joined by ``&`` operators.
+
+        Parameters:
+            permission (str): Permission expression (for example, ``isAuthenticated&isMatchingKeyAccount``).
+
+        Returns:
+            bool: True when every sub-permission evaluates to True for the current user.
         """
         return validatePermissionString(permission, self.instance, self.request_user)

general_manager/permission/managerBasedPermission.py

@@ -1,3 +1,5 @@
+"""Default permission implementation leveraging manager configuration."""
+
 from __future__ import annotations
 from typing import TYPE_CHECKING, Literal, Optional, Dict
 from general_manager.permission.basePermission import BasePermission
@@ -22,6 +24,8 @@ class notExistent:
 
 
 class ManagerBasedPermission(BasePermission):
+    """Permission implementation driven by class-level configuration lists."""
+
     __based_on__: Optional[str] = None
     __read__: list[str]
     __create__: list[str]
@@ -34,9 +38,11 @@ class ManagerBasedPermission(BasePermission):
         request_user: AbstractUser,
     ) -> None:
         """
-        Initializes the ManagerBasedPermission with a manager instance and the requesting user.
-        
-        Configures default CRUD permissions, collects attribute-specific permissions, and sets up any related "based on" permission for cascading checks.
+        Initialise the permission object and gather default and attribute-level rules.
+
+        Parameters:
+            instance (PermissionDataManager | GeneralManager): Target data used for permission evaluation.
+            request_user (AbstractUser): User whose permissions are being checked.
         """
         super().__init__(instance, request_user)
         self.__setPermissions()
@@ -51,12 +57,7 @@ class ManagerBasedPermission(BasePermission):
         }
 
     def __setPermissions(self, skip_based_on: bool = False) -> None:
-
-        """
-        Assigns default permission lists for CRUD actions based on the presence of a related permission attribute.
-        
-        If the permission is based on another attribute and `skip_based_on` is False, all default permissions are set to empty lists. Otherwise, read permissions default to `["public"]` and write permissions to `["isAuthenticated"]`. Class-level overrides are respected if present.
-        """
+        """Populate CRUD permissions using class-level defaults and overrides."""
         default_read = ["public"]
         default_write = ["isAuthenticated"]
 
@@ -71,14 +72,14 @@ class ManagerBasedPermission(BasePermission):
 
     def __getBasedOnPermission(self) -> Optional[BasePermission]:
         """
-        Retrieves the permission object associated with the `__based_on__` attribute, if present and valid.
-        
+        Retrieve the permission object referenced by ``__based_on__`` when configured.
+
         Returns:
-            An instance of the related `BasePermission` subclass if the `__based_on__` attribute exists on the instance and its `Permission` class is a subclass of `BasePermission`; otherwise, returns `None`.
-        
+            BasePermission | None: Permission instance for the related object, if applicable.
+
         Raises:
-            ValueError: If the `__based_on__` attribute is missing from the instance.
-            TypeError: If the `__based_on__` attribute is not a `GeneralManager` or its subclass.
+            ValueError: If the configured attribute does not exist on the instance.
+            TypeError: If the attribute does not resolve to a `GeneralManager`.
         """
         from general_manager.manager.generalManager import GeneralManager
 
@@ -115,6 +116,7 @@ class ManagerBasedPermission(BasePermission):
     def __getAttributePermissions(
         self,
     ) -> dict[str, dict[permission_type, list[str]]]:
+        """Collect attribute-level permission overrides defined on the class."""
         attribute_permissions = {}
         for attribute in self.__class__.__dict__:
             if not attribute.startswith("__"):
@@ -126,6 +128,16 @@ class ManagerBasedPermission(BasePermission):
         action: permission_type,
         attriubte: str,
     ) -> bool:
+        """
+        Determine whether the user has permission to perform ``action`` on ``attribute``.
+
+        Parameters:
+            action (permission_type): CRUD operation being evaluated.
+            attriubte (str): Attribute name subject to the permission check.
+
+        Returns:
+            bool: True when the action is permitted.
+        """
         if (
             self.__based_on_permission
             and not self.__based_on_permission.checkPermission(action, attriubte)
@@ -166,11 +178,7 @@ class ManagerBasedPermission(BasePermission):
         self,
         permissions: list[str],
     ) -> bool:
-        """
-        Return True if no permissions are required or if at least one permission string is valid for the user.
-        
-        If the permissions list is empty, access is granted. Otherwise, returns True if any permission string in the list is validated for the user; returns False if none are valid.
-        """
+        """Return True if any permission expression in the list evaluates to True."""
         if not permissions:
             return True
         for permission in permissions:
@@ -181,17 +189,15 @@ class ManagerBasedPermission(BasePermission):
     def getPermissionFilter(
         self,
     ) -> list[dict[Literal["filter", "exclude"], dict[str, str]]]:
-        """
-        Returns the filter for the permission
-        """
+        """Return queryset filters inferred from class-level permission configuration."""
         __based_on__ = getattr(self, "__based_on__")
         filters: list[dict[Literal["filter", "exclude"], dict[str, str]]] = []
 
         if self.__based_on_permission is not None:
             base_permissions = self.__based_on_permission.getPermissionFilter()
-            for permission in base_permissions:
-                filter = permission.get("filter", {})
-                exclude = permission.get("exclude", {})
+            for base_permission in base_permissions:
+                filter = base_permission.get("filter", {})
+                exclude = base_permission.get("exclude", {})
                 filters.append(
                     {
                         "filter": {