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

general_manager/interface/databaseInterface.py

@@ -2,8 +2,9 @@
 
 from __future__ import annotations
 from typing import (
-    Type,
     Any,
+    Type,
+    cast,
 )
 from django.db import models, transaction
 from simple_history.utils import update_change_reason  # type: ignore
@@ -14,6 +15,52 @@ from general_manager.interface.databaseBasedInterface import (
 from django.db.models import NOT_PROVIDED
 
 
+class InvalidFieldValueError(ValueError):
+    """Raised when assigning a value incompatible with the model field."""
+
+    def __init__(self, field_name: str, value: object) -> None:
+        """
+        Initialize an InvalidFieldValueError for a specific model field and value.
+
+        Parameters:
+            field_name (str): Name of the field that received an invalid value.
+            value (object): The invalid value provided; included in the exception message.
+
+        """
+        super().__init__(f"Invalid value for {field_name}: {value}.")
+
+
+class InvalidFieldTypeError(TypeError):
+    """Raised when assigning a value with an unexpected type."""
+
+    def __init__(self, field_name: str, error: Exception) -> None:
+        """
+        Initialize the InvalidFieldTypeError with the field name and the originating exception.
+
+        Parameters:
+            field_name (str): Name of the model field that received an unexpected type.
+            error (Exception): The original exception or error encountered for the field.
+
+        Notes:
+            The exception's message is formatted as "Type error for {field_name}: {error}."
+        """
+        super().__init__(f"Type error for {field_name}: {error}.")
+
+
+class UnknownFieldError(ValueError):
+    """Raised when keyword arguments reference fields not present on the model."""
+
+    def __init__(self, field_name: str, model_name: str) -> None:
+        """
+        Initialize an UnknownFieldError indicating a field name is not present on a model.
+
+        Parameters:
+            field_name (str): The field name that was not found on the model.
+            model_name (str): The name of the model in which the field was expected.
+        """
+        super().__init__(f"{field_name} does not exist in {model_name}.")
+
+
 class DatabaseInterface(DBBasedInterface[GeneralManagerModel]):
     """CRUD-capable interface backed by a concrete Django model."""
 
@@ -24,23 +71,24 @@ class DatabaseInterface(DBBasedInterface[GeneralManagerModel]):
         cls, creator_id: int | None, history_comment: str | None = None, **kwargs: Any
     ) -> int:
         """
-        Create a new model instance and return its primary key.
+        Create a new model instance using the provided field values.
 
         Parameters:
-            creator_id (int | None): Identifier of the user creating the instance.
-            history_comment (str | None): Optional comment stored in the history log.
-            **kwargs (Any): Field values used to populate the model.
+            creator_id (int | None): ID of the user to record as the change author, or None to leave unset.
+            history_comment (str | None): Optional comment to attach to the instance history.
+            **kwargs: Field values used to populate the model; many-to-many relations may be provided as `<field>_id_list`.
 
         Returns:
             int: Primary key of the newly created instance.
 
         Raises:
-            ValueError: If unknown fields are supplied.
-            ValidationError: Propagated when model validation fails.
+            UnknownFieldError: If kwargs contain names that do not correspond to model fields.
+            ValidationError: If model validation fails during save.
         """
-        cls._checkForInvalidKwargs(cls._model, kwargs=kwargs)
-        kwargs, many_to_many_kwargs = cls._sortKwargs(cls._model, kwargs)
-        instance = cls.__setAttrForWrite(cls._model(), kwargs)
+        model_cls = cast(type[GeneralManagerModel], cls._model)
+        cls._checkForInvalidKwargs(model_cls, kwargs=kwargs)
+        kwargs, many_to_many_kwargs = cls._sortKwargs(model_cls, kwargs)
+        instance = cls.__setAttrForWrite(model_cls(), kwargs)
         pk = cls._save_with_history(instance, creator_id, history_comment)
         cls.__setManyToManyAttributes(instance, many_to_many_kwargs)
         return pk
@@ -49,23 +97,24 @@ class DatabaseInterface(DBBasedInterface[GeneralManagerModel]):
         self, creator_id: int | None, history_comment: str | None = None, **kwargs: Any
     ) -> int:
         """
-        Update the current model instance and return its primary key.
+        Update this instance with the provided field values.
 
         Parameters:
-            creator_id (int | None): Identifier of the user performing the update.
-            history_comment (str | None): Optional comment stored in the history log.
-            **kwargs (Any): Field updates applied to the model.
+            creator_id (int | None): ID of the user recording the change; used to set `changed_by_id`.
+            history_comment (str | None): Optional comment to attach to the instance's change history.
+            **kwargs (Any): Field names and values to apply to the instance; many-to-many updates may be supplied using the `<relation>_id_list` convention.
 
         Returns:
             int: Primary key of the updated instance.
 
         Raises:
-            ValueError: If unknown fields are supplied.
-            ValidationError: Propagated when model validation fails.
+            UnknownFieldError: If any provided kwarg does not correspond to a model field.
+            ValidationError: If model validation fails during save.
         """
-        self._checkForInvalidKwargs(self._model, kwargs=kwargs)
-        kwargs, many_to_many_kwargs = self._sortKwargs(self._model, kwargs)
-        instance = self.__setAttrForWrite(self._model.objects.get(pk=self.pk), kwargs)
+        model_cls = cast(type[GeneralManagerModel], self._model)
+        self._checkForInvalidKwargs(model_cls, kwargs=kwargs)
+        kwargs, many_to_many_kwargs = self._sortKwargs(model_cls, kwargs)
+        instance = self.__setAttrForWrite(model_cls.objects.get(pk=self.pk), kwargs)
         pk = self._save_with_history(instance, creator_id, history_comment)
         self.__setManyToManyAttributes(instance, many_to_many_kwargs)
         return pk
@@ -83,7 +132,8 @@ class DatabaseInterface(DBBasedInterface[GeneralManagerModel]):
         Returns:
             int: Primary key of the deactivated instance.
         """
-        instance = self._model.objects.get(pk=self.pk)
+        model_cls = cast(type[GeneralManagerModel], self._model)
+        instance = model_cls.objects.get(pk=self.pk)
         instance.is_active = False
         if history_comment:
             history_comment = f"{history_comment} (deactivated)"
@@ -128,14 +178,20 @@ class DatabaseInterface(DBBasedInterface[GeneralManagerModel]):
         kwargs: dict[str, Any],
     ) -> GeneralManagerModel:
         """
-        Populate non-relational fields on the instance before saving.
+        Populate non-relational fields on an instance and prepare values for writing.
+
+        Converts any GeneralManager value to its `id` and appends `_id` to the attribute name, skips values equal to `NOT_PROVIDED`, sets each attribute on the instance, and translates underlying `ValueError`/`TypeError` from attribute assignment into `InvalidFieldValueError` and `InvalidFieldTypeError` respectively.
 
         Parameters:
-            instance (GeneralManagerModel): Model instance that will receive the values.
-            kwargs (dict[str, Any]): Key-value pairs to assign to the instance.
+            instance (GeneralManagerModel): The model instance to modify.
+            kwargs (dict[str, Any]): Mapping of attribute names to values to apply.
 
         Returns:
-            GeneralManagerModel: Instance with updated attributes.
+            GeneralManagerModel: The same instance with attributes updated.
+
+        Raises:
+            InvalidFieldValueError: If setting an attribute raises a `ValueError`.
+            InvalidFieldTypeError: If setting an attribute raises a `TypeError`.
         """
         from general_manager.manager.generalManager import GeneralManager
 
@@ -147,10 +203,10 @@ class DatabaseInterface(DBBasedInterface[GeneralManagerModel]):
                 continue
             try:
                 setattr(instance, key, value)
-            except ValueError as e:
-                raise ValueError(f"Invalid value for {key}: {value}") from e
-            except TypeError as e:
-                raise TypeError(f"Type error for {key}: {e}") from e
+            except ValueError as error:
+                raise InvalidFieldValueError(key, value) from error
+            except TypeError as error:
+                raise InvalidFieldTypeError(key, error) from error
         return instance
 
     @staticmethod
@@ -158,39 +214,41 @@ class DatabaseInterface(DBBasedInterface[GeneralManagerModel]):
         model: Type[models.Model], kwargs: dict[str, Any]
     ) -> None:
         """
-        Ensure provided keyword arguments map to known fields or attributes.
+        Validate that each key in `kwargs` corresponds to an attribute or field on `model`.
 
         Parameters:
-            model (type[models.Model]): Django model being validated.
-            kwargs (dict[str, Any]): Keyword arguments supplied by the caller.
+            model (type[models.Model]): The Django model class to validate against.
+            kwargs (dict[str, Any]): Mapping of keyword names to values; keys ending with `_id_list` are validated after stripping that suffix.
 
         Raises:
-            ValueError: If an unknown field name is encountered.
+            UnknownFieldError: If any provided key (after removing a trailing `_id_list`) does not match a model attribute or field name.
         """
         attributes = vars(model)
         field_names = {f.name for f in model._meta.get_fields()}
         for key in kwargs:
             temp_key = key.split("_id_list")[0]  # Remove '_id_list' suffix
             if temp_key not in attributes and temp_key not in field_names:
-                raise ValueError(f"{key} does not exist in {model.__name__}")
+                raise UnknownFieldError(key, model.__name__)
 
     @staticmethod
     def _sortKwargs(
         model: Type[models.Model], kwargs: dict[Any, Any]
     ) -> tuple[dict[str, Any], dict[str, list[Any]]]:
         """
-        Split keyword arguments into simple fields and many-to-many relations.
+        Separate provided kwargs into simple model-field arguments and many-to-many relation arguments.
+
+        This function removes keys targeting many-to-many relations from the input kwargs and returns them separately. A many-to-many key is identified by the suffix "_id_list" whose base name matches a many-to-many field on the given model.
 
         Parameters:
-            model (type[models.Model]): Model whose relation metadata is inspected.
-            kwargs (dict[Any, Any]): Keyword arguments supplied by the caller.
+            model (Type[models.Model]): Django model whose many-to-many field names are inspected.
+            kwargs (dict[Any, Any]): Mapping of keyword arguments to partition; keys matching many-to-many relations are removed in-place.
 
         Returns:
-            tuple[dict[str, Any], dict[str, list[Any]]]: Tuple containing simple-field kwargs and many-to-many kwargs.
+            tuple[dict[str, Any], dict[str, list[Any]]]: A tuple where the first element is the original kwargs dict with many-to-many keys removed, and the second element maps the removed many-to-many keys to their values.
         """
         many_to_many_fields = [field.name for field in model._meta.many_to_many]
         many_to_many_kwargs: dict[Any, Any] = {}
-        for key, value in list(kwargs.items()):
+        for key, _value in list(kwargs.items()):
             many_to_many_key = key.split("_id_list")[0]
             if many_to_many_key in many_to_many_fields:
                 many_to_many_kwargs[key] = kwargs.pop(key)

general_manager/interface/models.py

@@ -58,7 +58,7 @@ class GeneralManagerBasisModel(models.Model):
     """Abstract base model providing shared fields for GeneralManager storage."""
 
     _general_manager_class: ClassVar[Type[GeneralManager]]
-    is_active = models.BooleanField(default=True)
+    is_active = models.BooleanField(default=True)  # type: ignore[var-annotated]
     history = HistoricalRecords(inherit=True)
 
     class Meta:
@@ -70,7 +70,7 @@ class GeneralManagerModel(GeneralManagerBasisModel):
 
     changed_by = models.ForeignKey(
         settings.AUTH_USER_MODEL, on_delete=models.PROTECT, null=True, blank=True
-    )
+    )  # type: ignore[var-annotated]
     changed_by_id: int | None
 
     @property
@@ -83,12 +83,12 @@ class GeneralManagerModel(GeneralManagerBasisModel):
     @_history_user.setter
     def _history_user(self, value: AbstractUser | None) -> None:
         """
-        Set the user responsible for the most recent change to the model instance.
+        Assign the given user as the author of the most recent change recorded for this model instance.
 
         Parameters:
-            value (AbstractUser): The user to associate with the latest modification.
+            value (AbstractUser | None): The user to associate with the latest modification, or `None` to clear the recorded user.
         """
-        setattr(self, "changed_by", value)
+        self.changed_by = value
 
     class Meta:  # type: ignore
         abstract = True

general_manager/interface/readOnlyInterface.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 import json
 
-from typing import Type, Any, Callable, TYPE_CHECKING, cast
+from typing import Type, Any, Callable, TYPE_CHECKING, cast, ClassVar
 from django.db import models, transaction
 from general_manager.interface.databaseBasedInterface import (
     DBBasedInterface,
@@ -15,7 +15,6 @@ from general_manager.interface.databaseBasedInterface import (
     interfaceBaseClass,
 )
 from django.db import connection
-from typing import ClassVar
 from django.core.checks import Warning
 import logging
 
@@ -26,22 +25,78 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+class MissingReadOnlyDataError(ValueError):
+    """Raised when a ReadOnlyInterface lacks the required `_data` attribute."""
+
+    def __init__(self, interface_name: str) -> None:
+        """
+        Exception raised when a ReadOnlyInterface is missing the required `_data` attribute.
+
+        Parameters:
+            interface_name (str): Name of the interface class; used to construct the exception message.
+        """
+        super().__init__(
+            f"ReadOnlyInterface '{interface_name}' must define a '_data' attribute."
+        )
+
+
+class MissingUniqueFieldError(ValueError):
+    """Raised when a ReadOnlyInterface has no unique fields defined."""
+
+    def __init__(self, interface_name: str) -> None:
+        """
+        Initialize an error for a read-only interface that defines no unique fields.
+
+        Parameters:
+            interface_name (str): Name of the interface class missing at least one unique field; this name is included in the exception message.
+        """
+        super().__init__(
+            f"ReadOnlyInterface '{interface_name}' must declare at least one unique field."
+        )
+
+
+class InvalidReadOnlyDataFormatError(TypeError):
+    """Raised when the `_data` JSON does not decode to a list of dictionaries."""
+
+    def __init__(self) -> None:
+        """
+        Exception raised when the `_data` JSON does not decode to a list of dictionaries.
+
+        Initializes the exception with the message "_data JSON must decode to a list of dictionaries."
+        """
+        super().__init__("_data JSON must decode to a list of dictionaries.")
+
+
+class InvalidReadOnlyDataTypeError(TypeError):
+    """Raised when the `_data` attribute is neither JSON string nor list."""
+
+    def __init__(self) -> None:
+        """
+        Initialize the InvalidReadOnlyDataTypeError with a standard error message.
+
+        Raises a TypeError indicating that the `_data` attribute must be either a JSON string or a list of dictionaries.
+        """
+        super().__init__("_data must be a JSON string or a list of dictionaries.")
+
+
 class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
     """Interface that reads static JSON data into a managed read-only model."""
 
-    _interface_type = "readonly"
-    _parent_class: Type[GeneralManager]
+    _interface_type: ClassVar[str] = "readonly"
+    _parent_class: ClassVar[Type["GeneralManager"]]
 
     @staticmethod
     def getUniqueFields(model: Type[models.Model]) -> set[str]:
         """
-        Return names of fields that uniquely identify instances of ``model``.
+        Determine which fields on the given Django model uniquely identify its instances.
+
+        The result includes fields declared with `unique=True` (excluding a primary key named "id"), any fields in `unique_together` tuples, and fields referenced by `UniqueConstraint` objects.
 
         Parameters:
-            model (type[models.Model]): Django model inspected for uniqueness metadata.
+            model (type[models.Model]): Django model to inspect.
 
         Returns:
-            set[str]: Field names that participate in unique constraints.
+            set[str]: Names of fields that participate in unique constraints for the model.
         """
         opts = model._meta
         unique_fields: set[str] = set()
@@ -63,7 +118,17 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
 
     @classmethod
     def syncData(cls) -> None:
-        """Synchronise the backing model with the class-level JSON data."""
+        """
+        Synchronize the Django model with the parent manager's class-level `_data` JSON.
+
+        Parses the parent class's `_data` (JSON string or list of dicts), ensures the model schema is up to date, and within a single transaction creates, updates, or deactivates model instances to match the parsed data. Newly created or updated instances are marked `is_active = True`; existing active instances absent from the data are marked `is_active = False`. Logs a summary when any changes occur.
+
+        Raises:
+            MissingReadOnlyDataError: If the parent manager class does not define `_data`.
+            InvalidReadOnlyDataFormatError: If `_data` is a JSON string that does not decode to a list of dictionaries.
+            InvalidReadOnlyDataTypeError: If `_data` is neither a string nor a list.
+            MissingUniqueFieldError: If the model exposes no unique fields to identify records.
+        """
         if cls.ensureSchemaIsUpToDate(cls._parent_class, cls._model):
             logger.warning(
                 f"Schema for ReadOnlyInterface '{cls._parent_class.__name__}' is not up to date."
@@ -74,27 +139,23 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
         parent_class = cls._parent_class
         json_data = getattr(parent_class, "_data", None)
         if json_data is None:
-            raise ValueError(
-                f"For ReadOnlyInterface '{parent_class.__name__}' must set '_data'"
-            )
+            raise MissingReadOnlyDataError(parent_class.__name__)
 
         # Parse JSON into Python structures
         if isinstance(json_data, str):
             parsed_data = json.loads(json_data)
             if not isinstance(parsed_data, list):
-                raise TypeError("_data JSON must decode to a list of dictionaries")
+                raise InvalidReadOnlyDataFormatError()
         elif isinstance(json_data, list):
             parsed_data = json_data
         else:
-            raise TypeError("_data must be a JSON string or a list of dictionaries")
+            raise InvalidReadOnlyDataTypeError()
 
         data_list = cast(list[dict[str, Any]], parsed_data)
 
         unique_fields = cls.getUniqueFields(model)
         if not unique_fields:
-            raise ValueError(
-                f"For ReadOnlyInterface '{parent_class.__name__}' must have at least one unique field."
-            )
+            raise MissingUniqueFieldError(parent_class.__name__)
 
         changes: dict[str, list[models.Model]] = {
             "created": [],
@@ -106,14 +167,27 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
             json_unique_values: set[Any] = set()
 
             # data synchronization
-            for data in data_list:
-                lookup = {field: data[field] for field in unique_fields}
+            for idx, data in enumerate(data_list):
+                try:
+                    lookup = {field: data[field] for field in unique_fields}
+                except KeyError as e:
+                    missing = e.args[0]
+                    raise InvalidReadOnlyDataFormatError() from KeyError(
+                        f"Item {idx} missing unique field '{missing}'."
+                    )
                 unique_identifier = tuple(lookup[field] for field in unique_fields)
                 json_unique_values.add(unique_identifier)
 
                 instance, is_created = model.objects.get_or_create(**lookup)
                 updated = False
-                for field_name, value in data.items():
+                editable_fields = {
+                    f.name
+                    for f in model._meta.local_fields
+                    if getattr(f, "editable", True)
+                    and not getattr(f, "primary_key", False)
+                } - {"is_active"}
+                for field_name in editable_fields.intersection(data.keys()):
+                    value = data[field_name]
                     if getattr(instance, field_name, None) != value:
                         setattr(instance, field_name, value)
                         updated = True
@@ -192,7 +266,7 @@ class ReadOnlyInterface(DBBasedInterface[GeneralManagerBasisModel]):
         if not table_exists(table):
             return [
                 Warning(
-                    f"Database table does not exist!",
+                    "Database table does not exist!",
                     hint=f"ReadOnlyInterface '{new_manager_class.__name__}' (Table '{table}') does not exist in the database.",
                     obj=model,
                 )

general_manager/manager/__init__.py

@@ -12,10 +12,19 @@ __all__ = list(MANAGER_EXPORTS)
 _MODULE_MAP = MANAGER_EXPORTS
 
 if TYPE_CHECKING:
-    from general_manager._types.manager import *  # noqa: F401,F403
+    from general_manager._types.manager import *  # noqa: F403
 
 
 def __getattr__(name: str) -> Any:
+    """
+    Resolve and return a public export by name for dynamic attribute access.
+
+    Parameters:
+        name (str): The attribute name to resolve.
+
+    Returns:
+        Any: The object bound to the requested public name.
+    """
     return resolve_export(
         name,
         module_all=__all__,

general_manager/manager/generalManager.py

@@ -7,6 +7,20 @@ from general_manager.cache.cacheTracker import DependencyTracker
 from general_manager.cache.signals import dataChange
 from general_manager.bucket.baseBucket import Bucket
 
+
+class UnsupportedUnionOperandError(TypeError):
+    """Raised when attempting to union a manager with an incompatible operand."""
+
+    def __init__(self, operand_type: type) -> None:
+        """
+        Exception raised when attempting to perform a union with an unsupported operand type.
+
+        Parameters:
+            operand_type (type): The operand type that is not supported for the union; its representation is included in the exception message.
+        """
+        super().__init__(f"Unsupported type for union: {operand_type}.")
+
+
 if TYPE_CHECKING:
     from general_manager.permission.basePermission import BasePermission
     from general_manager.interface.baseInterface import InterfaceBase
@@ -16,17 +30,15 @@ class GeneralManager(metaclass=GeneralManagerMeta):
     Permission: Type[BasePermission]
     _attributes: dict[str, Any]
     Interface: Type["InterfaceBase"]
+    _old_values: dict[str, Any]
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         """
-        Instantiate the manager by delegating to the interface and record its identification.
+        Create a manager by constructing its Interface and record the resulting identification.
 
         Parameters:
-            *args: Positional arguments forwarded to the interface constructor.
-            **kwargs: Keyword arguments forwarded to the interface constructor.
-
-        Returns:
-            None
+            *args: Positional arguments forwarded to the Interface constructor.
+            **kwargs: Keyword arguments forwarded to the Interface constructor.
         """
         self._interface = self.Interface(*args, **kwargs)
         self.__id: dict[str, Any] = self._interface.identification
@@ -56,36 +68,33 @@ class GeneralManager(metaclass=GeneralManagerMeta):
         other: Self | Bucket[Self],
     ) -> Bucket[Self]:
         """
-        Merge this manager with another manager or bucket.
+        Combine this manager with another manager or a Bucket into a Bucket representing their union.
 
         Parameters:
-            other (Self | Bucket[Self]): Manager instance or bucket to combine.
+            other (Self | Bucket[Self]): A manager of the same class or a Bucket to union with.
 
         Returns:
-            Bucket[Self]: Bucket containing the union of both inputs.
+            Bucket[Self]: A Bucket containing the union of the managed objects represented by this manager and `other`.
 
         Raises:
-            TypeError: If `other` is neither a compatible bucket nor manager.
+            UnsupportedUnionOperandError: If `other` is not a Bucket and not a GeneralManager instance of the same class.
         """
         if isinstance(other, Bucket):
             return other | self
         elif isinstance(other, GeneralManager) and other.__class__ == self.__class__:
             return self.filter(id__in=[self.__id, other.__id])
         else:
-            raise TypeError(f"Unsupported type for union: {type(other)}")
+            raise UnsupportedUnionOperandError(type(other))
 
     def __eq__(
         self,
         other: object,
     ) -> bool:
         """
-        Compare managers based on their identification values.
-
-        Parameters:
-            other (object): Object to compare against this manager.
+        Determine whether another object represents the same managed entity.
 
         Returns:
-            bool: True when `other` is a manager with the same identification.
+            `true` if `other` is a `GeneralManager` whose identification equals this manager's, `false` otherwise.
         """
         if not isinstance(other, GeneralManager):
             return False

general_manager/manager/groupManager.py

@@ -12,6 +12,20 @@ from general_manager.bucket.baseBucket import (
 )
 
 
+class MissingGroupAttributeError(AttributeError):
+    """Raised when a GroupManager access attempts to use an undefined attribute."""
+
+    def __init__(self, manager_name: str, attribute: str) -> None:
+        """
+        Initialize the exception indicating that a GroupManager attempted to access an undefined attribute.
+
+        Parameters:
+            manager_name (str): Name of the manager where the attribute access occurred.
+            attribute (str): The missing attribute name that was accessed.
+        """
+        super().__init__(f"{manager_name} has no attribute {attribute}.")
+
+
 class GroupManager(Generic[GeneralManagerType]):
     """Represent aggregated results for grouped GeneralManager records."""
 
@@ -112,16 +126,16 @@ class GroupManager(Generic[GeneralManagerType]):
 
     def combineValue(self, item: str) -> Any:
         """
-        Aggregate attribute values across the grouped records.
+        Aggregate the values of a named attribute across all records in the group.
 
         Parameters:
-            item (str): Name of the attribute to aggregate.
+            item (str): Attribute name to aggregate from each grouped record.
 
         Returns:
-            Any: Aggregated value corresponding to `item`.
+            Any: The aggregated value for `item` according to its type (e.g., merged Bucket/GeneralManager, concatenated list, merged dict, deduplicated comma-separated string, boolean OR, numeric sum, or latest datetime). Returns `None` if all values are `None` or if `item` is `"id"`.
 
         Raises:
-            AttributeError: If the attribute is not defined on the manager or property set.
+            MissingGroupAttributeError: If the attribute does not exist or its type cannot be determined on the manager.
         """
         if item == "id":
             return None
@@ -139,13 +153,13 @@ class GroupManager(Generic[GeneralManagerType]):
                     else cast(type, attr_value.graphql_type_hint)
                 )
         if data_type is None or not isinstance(data_type, type):
-            raise AttributeError(f"{self.__class__.__name__} has no attribute {item}")
+            raise MissingGroupAttributeError(self.__class__.__name__, item)
 
         total_data = []
         for entry in self._data:
             total_data.append(getattr(entry, item))
 
-        new_data = None
+        new_data: Any = None
         if all([i is None for i in total_data]):
             return new_data
         total_data = [i for i in total_data if i is not None]