GeneralManager 0.17.0__py3-none-any.whl → 0.18.0__py3-none-any.whl

general_manager/measurement/measurementField.py

@@ -10,43 +10,53 @@ 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
+from typing import Any, cast
+
+
+class MeasurementFieldNotEditableError(ValidationError):
+    """Raised when attempting to modify a non-editable MeasurementField."""
+
+    def __init__(self, field_name: str) -> None:
+        """
+        Initialize the exception indicating an attempt to assign to a non-editable measurement field.
+
+        Parameters:
+            field_name (str): Name of the field that was attempted to be modified; used to compose the error message.
+        """
+        super().__init__(f"{field_name} is not editable.")
 
 
 class MeasurementField(models.Field):
     description = "Stores a measurement (value + unit) but exposes a single field API"
 
-    empty_values: ClassVar[tuple[object, ...]] = (None, "", [], (), {})
+    empty_values: tuple[object, ...] = (None, "", [], (), {})
 
     def __init__(
         self,
         base_unit: str,
-        *args: object,
+        *args: Any,
         null: bool = False,
         blank: bool = False,
         editable: bool = True,
-        **kwargs: object,
+        **kwargs: Any,
     ) -> None:
         """
         Configure a measurement field backed by separate value and unit columns.
 
         Parameters:
-            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`.
-
-        Returns:
-            None
+            base_unit (str): Canonical unit used to normalise stored measurements.
+            *args: Positional arguments forwarded to the base Field implementation.
+            null (bool): If True, the measurement may be stored as NULL in the database.
+            blank (bool): If True, forms may accept an empty value for this field.
+            editable (bool): If False, assignments through the model API are rejected.
+            **kwargs: Additional keyword arguments forwarded to the base Field implementation.
         """
         self.base_unit = base_unit
         self.base_dimension = ureg.parse_expression(self.base_unit).dimensionality
 
         self.editable = editable
-        self.value_field: models.DecimalField[Any]
-        self.unit_field: models.CharField[Any]
+        self.value_field: models.Field[Any, Any]
+        self.unit_field: models.Field[Any, Any]
         if null:
             self.value_field = models.DecimalField(
                 max_digits=30,
@@ -78,7 +88,13 @@ class MeasurementField(models.Field):
                 blank=blank,
             )
 
-        super().__init__(*args, null=null, blank=blank, editable=editable, **kwargs)
+        options: dict[str, Any] = {
+            **kwargs,
+            "null": null,
+            "blank": blank,
+            "editable": editable,
+        }
+        super().__init__(*args, **options)
 
     def contribute_to_class(
         self,
@@ -88,16 +104,13 @@ class MeasurementField(models.Field):
         **kwargs: object,
     ) -> None:
         """
-        Attach the measurement field and its backing columns to a Django model.
+        Attach the measurement field and its backing value and unit fields to the model and install the descriptor.
 
         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.
-
-        Returns:
-            None
+            cls: Model class receiving the field.
+            name: Attribute name to use on the model for this field.
+            private_only: Whether the field should be treated as private.
+            kwargs: Additional options forwarded to the base implementation.
         """
         super().contribute_to_class(cls, name, private_only=private_only, **kwargs)
         self.concrete = False
@@ -289,20 +302,18 @@ class MeasurementField(models.Field):
         value: Measurement | str | None,
     ) -> None:
         """
-        Assign a measurement to the model instance after validating compatibility.
+        Set a measurement on a model instance after validating editability, type, and unit compatibility.
 
         Parameters:
             instance (models.Model): Model instance receiving the value.
-            value (Measurement | str | None): Measurement value supplied by the caller.
-
-        Returns:
-            None
+            value (Measurement | str | None): A Measurement, a string parseable to a Measurement, or None to clear the field.
 
         Raises:
-            ValidationError: If the field is not editable, the value is invalid, or the units are incompatible.
+            MeasurementFieldNotEditableError: If the field is not editable.
+            ValidationError: If the value is not a Measurement (or valid parseable string), if currency unit rules are violated, or if the unit is incompatible with the field's base unit.
         """
         if not self.editable:
-            raise ValidationError(f"{self.name} is not editable.")
+            raise MeasurementFieldNotEditableError(self.name)
         if value is None:
             setattr(instance, self.value_attr, None)
             setattr(instance, self.unit_attr, None)

general_manager/permission/__init__.py

@@ -12,10 +12,19 @@ __all__ = list(PERMISSION_EXPORTS)
 _MODULE_MAP = PERMISSION_EXPORTS
 
 if TYPE_CHECKING:
-    from general_manager._types.permission import *  # noqa: F401,F403
+    from general_manager._types.permission import *  # noqa: F403
 
 
 def __getattr__(name: str) -> Any:
+    """
+    Resolve and return a lazily-exposed public attribute for this module.
+
+    Parameters:
+        name (str): The attribute name being accessed on the module.
+
+    Returns:
+        Any: The resolved attribute value associated with `name`.
+    """
     return resolve_export(
         name,
         module_all=__all__,

general_manager/permission/basePermission.py

@@ -2,20 +2,43 @@
 
 from __future__ import annotations
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any, Literal
-from general_manager.permission.permissionChecks import (
-    permission_functions,
-    permission_filter,
-)
+from typing import TYPE_CHECKING, Any, Literal, TypeAlias, cast
+from general_manager.permission.permissionChecks import permission_functions
 
-from django.contrib.auth.models import AnonymousUser, AbstractUser
+from django.contrib.auth.models import AnonymousUser, AbstractBaseUser, AbstractUser
 from general_manager.permission.permissionDataManager import PermissionDataManager
-from general_manager.permission.utils import validatePermissionString
+from general_manager.permission.utils import (
+    validatePermissionString,
+    PermissionNotFoundError,
+)
+import logging
 
 if TYPE_CHECKING:
     from general_manager.manager.generalManager import GeneralManager
     from general_manager.manager.meta import GeneralManagerMeta
 
+logger = logging.getLogger(__name__)
+
+UserLike: TypeAlias = AbstractBaseUser | AnonymousUser
+
+
+class PermissionCheckError(PermissionError):
+    """Raised when permission evaluation fails for a user."""
+
+    def __init__(self, user: UserLike, errors: list[str]) -> None:
+        """
+        Initialize a PermissionCheckError carrying the requesting user's identity and permission failure details.
+
+        Parameters:
+            user (UserLike): The user for whom permission evaluation failed; if the user has an `id`, it is included in the error message, otherwise the user is labeled "anonymous".
+            errors (list[str]): A list of error messages describing individual permission failures.
+        """
+        user_id = getattr(user, "id", None)
+        user_label = "anonymous" if user_id is None else f"id={user_id}"
+        super().__init__(
+            f"Permission denied for user {user_label} with errors: {errors}."
+        )
+
 
 class BasePermission(ABC):
     """Abstract base class defining CRUD permission checks for managers."""
@@ -23,7 +46,7 @@ class BasePermission(ABC):
     def __init__(
         self,
         instance: PermissionDataManager | GeneralManager | GeneralManagerMeta,
-        request_user: AbstractUser | AnonymousUser,
+        request_user: UserLike,
     ) -> None:
         """Initialise the permission context for a specific manager and user."""
         self._instance = instance
@@ -35,7 +58,7 @@ class BasePermission(ABC):
         return self._instance
 
     @property
-    def request_user(self) -> AbstractUser | AnonymousUser:
+    def request_user(self) -> UserLike:
         """Return the user being evaluated for permission checks."""
         return self._request_user
 
@@ -44,9 +67,21 @@ class BasePermission(ABC):
         cls,
         data: dict[str, Any],
         manager: type[GeneralManager],
-        request_user: AbstractUser | AnonymousUser | Any,
+        request_user: UserLike | Any,
     ) -> None:
-        """Validate create permissions for the supplied payload."""
+        """
+        Validate that the requesting user is allowed to create each attribute in the provided payload.
+
+        Checks create permission for every key in `data` using the given `manager`. If any attribute is not permitted, raises a PermissionCheckError that includes the evaluated user and a list of denial messages.
+
+        Parameters:
+            data (dict[str, Any]): Mapping of attribute names to the values intended for creation.
+            manager (type[GeneralManager]): Manager class that defines the model/schema against which permissions are checked.
+            request_user (UserLike | Any): User instance or user id (will be resolved to a user or AnonymousUser).
+
+        Raises:
+            PermissionCheckError: If one or more attributes in `data` are denied for the resolved `request_user`.
+        """
         request_user = cls.getUserWithId(request_user)
         errors = []
         permission_data = PermissionDataManager(permission_data=data, manager=manager)
@@ -54,22 +89,31 @@ class BasePermission(ABC):
         for key in data.keys():
             is_allowed = Permission.checkPermission("create", key)
             if not is_allowed:
-                errors.append(
+                logger.debug(
                     f"Permission denied for {key} with value {data[key]} for user {request_user}"
                 )
+                errors.append(f"Create permission denied for attribute '{key}'")
         if errors:
-            raise PermissionError(
-                f"Permission denied for user {request_user} with errors: {errors}"
-            )
+            raise PermissionCheckError(request_user, errors)
 
     @classmethod
     def checkUpdatePermission(
         cls,
         data: dict[str, Any],
         old_manager_instance: GeneralManager,
-        request_user: AbstractUser | AnonymousUser | Any,
+        request_user: UserLike | Any,
     ) -> None:
-        """Validate update permissions for the supplied payload."""
+        """
+        Validate whether the request_user can update the given fields on an existing manager instance.
+
+        Parameters:
+            data (dict[str, Any]): Mapping of attribute names to new values to be applied.
+            old_manager_instance (GeneralManager): Existing manager instance whose current state is used to evaluate update permissions.
+            request_user (UserLike | Any): User instance or user id; non-user values will be resolved to a User or AnonymousUser via getUserWithId.
+
+        Raises:
+            PermissionCheckError: Raised with a list of error messages when one or more fields are not permitted to be updated.
+        """
         request_user = cls.getUserWithId(request_user)
 
         errors = []
@@ -80,21 +124,31 @@ class BasePermission(ABC):
         for key in data.keys():
             is_allowed = Permission.checkPermission("update", key)
             if not is_allowed:
-                errors.append(
+                logger.debug(
                     f"Permission denied for {key} with value {data[key]} for user {request_user}"
                 )
+                errors.append(f"Update permission denied for attribute '{key}'")
         if errors:
-            raise PermissionError(
-                f"Permission denied for user {request_user} with errors: {errors}"
-            )
+            raise PermissionCheckError(request_user, errors)
 
     @classmethod
     def checkDeletePermission(
         cls,
         manager_instance: GeneralManager,
-        request_user: AbstractUser | AnonymousUser | Any,
+        request_user: UserLike | Any,
     ) -> None:
-        """Validate delete permissions for the supplied manager instance."""
+        """
+        Validate that the request_user has delete permission for every attribute of the given manager instance.
+
+        This resolves the provided request_user to a User/AnonymousUser, evaluates delete permission for each attribute present on manager_instance, collects any denied attributes into error messages, and raises PermissionCheckError if any permissions are denied.
+
+        Parameters:
+            manager_instance (GeneralManager): The manager object whose attributes will be checked for delete permission.
+            request_user (UserLike | Any): The user (or user id) to evaluate; non-user values will be resolved to AnonymousUser.
+
+        Raises:
+            PermissionCheckError: If one or more attributes are not permitted for deletion by request_user. The exception carries the user and the list of denial messages.
+        """
         request_user = cls.getUserWithId(request_user)
 
         errors = []
@@ -103,22 +157,32 @@ class BasePermission(ABC):
         for key in manager_instance.__dict__.keys():
             is_allowed = Permission.checkPermission("delete", key)
             if not is_allowed:
-                errors.append(
+                logger.debug(
                     f"Permission denied for {key} with value {getattr(manager_instance, key)} for user {request_user}"
                 )
+                errors.append(f"Delete permission denied for attribute '{key}'")
         if errors:
-            raise PermissionError(
-                f"Permission denied for user {request_user} with errors: {errors}"
-            )
+            raise PermissionCheckError(request_user, errors)
 
     @staticmethod
     def getUserWithId(
-        user: Any | AbstractUser | AnonymousUser,
-    ) -> AbstractUser | AnonymousUser:
-        """Return a ``User`` instance given a primary key or user object."""
-        from django.contrib.auth.models import User
+        user: Any | UserLike,
+    ) -> UserLike:
+        """
+        Resolve a user identifier or user-like object to a Django User or AnonymousUser instance.
+
+        If the input is already an AbstractBaseUser or AnonymousUser, it is returned unchanged. If the input is a primary key (or other value used to look up a User by id), the corresponding User is returned; if no such User exists, an AnonymousUser is returned.
+
+        Parameters:
+            user (Any | UserLike): A user object or a value to look up a User by primary key.
+
+        Returns:
+            UserLike: The resolved User instance, or an AnonymousUser when no matching User is found.
+        """
+        from django.contrib.auth import get_user_model
 
-        if isinstance(user, (AbstractUser, AnonymousUser)):
+        User = get_user_model()
+        if isinstance(user, (AbstractBaseUser, AnonymousUser)):
             return user
         try:
             return User.objects.get(id=user)
@@ -129,14 +193,14 @@ class BasePermission(ABC):
     def checkPermission(
         self,
         action: Literal["create", "read", "update", "delete"],
-        attriubte: str,
+        attribute: 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.
+            attribute (str): Attribute name subject to the permission check.
 
         Returns:
             bool: True when the action is allowed.
@@ -152,13 +216,27 @@ class BasePermission(ABC):
     def _getPermissionFilter(
         self, permission: str
     ) -> dict[Literal["filter", "exclude"], dict[str, str]]:
-        """Resolve a filter definition for the given permission string."""
+        """
+        Resolve the filter/exclude constraints associated with a permission expression.
+
+        Parameters:
+            permission (str): Permission expression of the form "<function_name>[:config,...]"; the leading name selects a permission function and the optional colon-separated values are passed as configuration.
+
+        Returns:
+            dict: A mapping with keys "filter" and "exclude", each a dict[str, str] describing query constraints to apply. If the resolved permission provides no constraints, both will be empty dicts.
+
+        Raises:
+            PermissionNotFoundError: If no permission function matches the leading name in `permission`.
+        """
         permission_function, *config = permission.split(":")
         if permission_function not in permission_functions:
-            raise ValueError(f"Permission {permission} not found")
+            raise PermissionNotFoundError(permission)
         permission_filter = permission_functions[permission_function][
             "permission_filter"
-        ](self.request_user, config)
+        ](
+            cast(AbstractUser | AnonymousUser, self.request_user),
+            config,
+        )
         if permission_filter is None:
             return {"filter": {}, "exclude": {}}
         return permission_filter
@@ -176,4 +254,8 @@ class BasePermission(ABC):
         Returns:
             bool: True when every sub-permission evaluates to True for the current user.
         """
-        return validatePermissionString(permission, self.instance, self.request_user)
+        return validatePermissionString(
+            permission,
+            self.instance,
+            cast(AbstractUser | AnonymousUser, self.request_user),
+        )

general_manager/permission/managerBasedPermission.py

@@ -19,6 +19,47 @@ type permission_type = Literal[
 ]
 
 
+class InvalidBasedOnConfigurationError(ValueError):
+    """Raised when the configured `__based_on__` attribute is missing or invalid."""
+
+    def __init__(self, attribute_name: str) -> None:
+        """
+        Initialize the exception for an invalid or missing based-on configuration attribute.
+
+        Parameters:
+            attribute_name (str): Name of the configured `__based_on__` attribute that is missing or invalid.
+        """
+        super().__init__(
+            f"Based on configuration '{attribute_name}' is not valid or does not exist."
+        )
+
+
+class InvalidBasedOnTypeError(TypeError):
+    """Raised when the `__based_on__` attribute does not resolve to a GeneralManager."""
+
+    def __init__(self, attribute_name: str) -> None:
+        """
+        Initialize the exception indicating that the configured based-on attribute does not resolve to a GeneralManager.
+
+        Parameters:
+            attribute_name (str): Name of the configured based-on attribute that failed type validation; included in the exception message.
+        """
+        super().__init__(f"Based on object {attribute_name} is not a GeneralManager.")
+
+
+class UnknownPermissionActionError(ValueError):
+    """Raised when an unsupported permission action is encountered."""
+
+    def __init__(self, action: str) -> None:
+        """
+        Initialize the exception for an unsupported permission action.
+
+        Parameters:
+            action (str): The permission action name that is not recognized; used to build the exception message "Action {action} not found."
+        """
+        super().__init__(f"Action {action} not found.")
+
+
 class notExistent:
     pass
 
@@ -72,33 +113,33 @@ class ManagerBasedPermission(BasePermission):
 
     def __getBasedOnPermission(self) -> Optional[BasePermission]:
         """
-        Retrieve the permission object referenced by ``__based_on__`` when configured.
+        Resolve and return a BasePermission instance from the manager attribute named by the class-level `__based_on__` configuration.
+
+        If `__based_on__` is None or not configured on this class, returns None. If the referenced attribute exists on the target instance but is None, resets permissions to skip based-on evaluation and returns None. If the referenced attribute resolves to a manager that exposes a valid `Permission` subclass, constructs and returns that permission with the corresponding manager instance and the current request user.
 
         Returns:
-            BasePermission | None: Permission instance for the related object, if applicable.
+            BasePermission | None: The resolved permission instance for the related manager, or `None` when no based-on permission applies.
 
         Raises:
-            ValueError: If the configured attribute does not exist on the instance.
-            TypeError: If the attribute does not resolve to a `GeneralManager`.
+            InvalidBasedOnConfigurationError: If the configured `__based_on__` attribute does not exist on the target instance.
+            InvalidBasedOnTypeError: If the configured attribute exists but does not resolve to a `GeneralManager` or subclass.
         """
         from general_manager.manager.generalManager import GeneralManager
 
-        __based_on__ = getattr(self, "__based_on__")
+        __based_on__ = self.__based_on__
         if __based_on__ is None:
             return None
 
         basis_object = getattr(self.instance, __based_on__, notExistent)
         if basis_object is notExistent:
-            raise ValueError(
-                f"Based on configuration '{__based_on__}' is not valid or does not exist."
-            )
+            raise InvalidBasedOnConfigurationError(__based_on__)
         if basis_object is None:
             self.__setPermissions(skip_based_on=True)
             return None
         if not isinstance(basis_object, GeneralManager) and not (
             isinstance(basis_object, type) and issubclass(basis_object, GeneralManager)
         ):
-            raise TypeError(f"Based on object {__based_on__} is not a GeneralManager")
+            raise InvalidBasedOnTypeError(__based_on__)
 
         Permission = getattr(basis_object, "Permission", None)
 
@@ -126,21 +167,24 @@ class ManagerBasedPermission(BasePermission):
     def checkPermission(
         self,
         action: permission_type,
-        attriubte: str,
+        attribute: str,
     ) -> bool:
         """
-        Determine whether the user has permission to perform ``action`` on ``attribute``.
+        Determine whether the request user is allowed to perform a CRUD action on a specific attribute.
 
         Parameters:
-            action (permission_type): CRUD operation being evaluated.
-            attriubte (str): Attribute name subject to the permission check.
+            action (permission_type): CRUD action to evaluate ("create", "read", "update", "delete").
+            attribute (str): Name of the attribute to check permission for.
 
         Returns:
-            bool: True when the action is permitted.
+            bool: True if the action is permitted on the attribute, False otherwise.
+
+        Raises:
+            UnknownPermissionActionError: If `action` is not one of "create", "read", "update", or "delete".
         """
         if (
             self.__based_on_permission
-            and not self.__based_on_permission.checkPermission(action, attriubte)
+            and not self.__based_on_permission.checkPermission(action, attribute)
         ):
             return False
 
@@ -153,11 +197,11 @@ class ManagerBasedPermission(BasePermission):
         elif action == "delete":
             permissions = self.__delete__
         else:
-            raise ValueError(f"Action {action} not found")
+            raise UnknownPermissionActionError(action)
 
         has_attribute_permissions = (
-            attriubte in self.__attribute_permissions
-            and action in self.__attribute_permissions[attriubte]
+            attribute in self.__attribute_permissions
+            and action in self.__attribute_permissions[attribute]
         )
 
         if not has_attribute_permissions:
@@ -167,7 +211,7 @@ class ManagerBasedPermission(BasePermission):
             attribute_permission = True
         else:
             attribute_permission = self.__checkSpecificPermission(
-                self.__attribute_permissions[attriubte][action]
+                self.__attribute_permissions[attribute][action]
             )
 
         permission = self.__checkSpecificPermission(permissions)
@@ -189,8 +233,15 @@ class ManagerBasedPermission(BasePermission):
     def getPermissionFilter(
         self,
     ) -> list[dict[Literal["filter", "exclude"], dict[str, str]]]:
-        """Return queryset filters inferred from class-level permission configuration."""
-        __based_on__ = getattr(self, "__based_on__")
+        """
+        Builds queryset filter and exclude mappings derived from this permission configuration.
+
+        If a based-on permission exists, its filters and excludes are included with each key prefixed by the name in __based_on__. Then appends filters produced from this class's read permissions via _getPermissionFilter.
+
+        Returns:
+            list[dict[Literal["filter", "exclude"], dict[str, str]]]: A list of dictionaries each containing "filter" and "exclude" mappings where keys are queryset lookups and values are lookup values.
+        """
+        __based_on__ = self.__based_on__
         filters: list[dict[Literal["filter", "exclude"], dict[str, str]]] = []
 
         if self.__based_on_permission is not None:

general_manager/permission/mutationPermission.py

@@ -3,7 +3,10 @@
 from __future__ import annotations
 from django.contrib.auth.models import AbstractUser, AnonymousUser
 from typing import Any
-from general_manager.permission.basePermission import BasePermission
+from general_manager.permission.basePermission import (
+    BasePermission,
+    PermissionCheckError,
+)
 
 from general_manager.permission.permissionDataManager import PermissionDataManager
 from general_manager.permission.utils import validatePermissionString
@@ -57,14 +60,14 @@ class MutationPermission:
         request_user: AbstractUser | AnonymousUser | Any,
     ) -> None:
         """
-        Validate that ``request_user`` may execute the mutation for the provided data.
+        Validate that the given user is authorized to perform the mutation described by `data`.
 
         Parameters:
-            data (dict[str, Any]): Mutation payload.
-            request_user (AbstractUser | AnonymousUser | Any): User or user ID.
+            data (dict[str, Any]): Mutation payload mapping field names to values.
+            request_user (AbstractUser | AnonymousUser | Any): A user object or a user identifier; if an identifier is provided it will be resolved to a user.
 
         Raises:
-            PermissionError: If any field-level permission check fails.
+            PermissionCheckError: Raised with the `request_user` and a list of field-level error messages when one or more fields fail their permission checks.
         """
         errors = []
         if not isinstance(request_user, (AbstractUser, AnonymousUser)):
@@ -76,20 +79,22 @@ class MutationPermission:
                     f"Permission denied for {key} with value {data[key]} for user {request_user}"
                 )
         if errors:
-            raise PermissionError(f"Permission denied with errors: {errors}")
+            raise PermissionCheckError(request_user, errors)
 
     def checkPermission(
         self,
         attribute: str,
     ) -> bool:
         """
-        Evaluate permissions for a specific attribute within the mutation payload.
+        Determine whether the request user is allowed to modify a specific attribute in the mutation payload.
+
+        Updates the instance's cached overall permission result based on the class-level mutate permissions.
 
         Parameters:
-            attribute (str): Attribute name being validated.
+            attribute (str): Name of the attribute to validate.
 
         Returns:
-            bool: True when permitted, False otherwise.
+            True if modification of the attribute is allowed, False otherwise.
         """
 
         has_attribute_permissions = attribute in self.__attribute_permissions