GeneralManager 0.12.0__tar.gz → 0.12.1__tar.gz

{generalmanager-0.12.0 → generalmanager-0.12.1}/GeneralManager.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.12.0
+Version: 0.12.1
 Summary: Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching.
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License-Expression: MIT

{generalmanager-0.12.0 → generalmanager-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: GeneralManager
-Version: 0.12.0
+Version: 0.12.1
 Summary: Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching.
 Author-email: Tim Kleindick <tkleindick@yahoo.de>
 License-Expression: MIT

{generalmanager-0.12.0 → generalmanager-0.12.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "GeneralManager"
-version = "0.12.0"
+version = "0.12.1"
 description = "Modular Django-based data management framework with ORM, GraphQL, fine-grained permissions, rule validation, calculations and caching."
 readme = "README.md"
 authors = [{ name = "Tim Kleindick", email = "tkleindick@yahoo.de" }]

{generalmanager-0.12.0 → generalmanager-0.12.1}/src/general_manager/api/graphql.py

@@ -4,6 +4,7 @@ from typing import Any, Callable, get_args, TYPE_CHECKING, cast, Type
 from decimal import Decimal
 from datetime import date, datetime
 import json
+from graphql.language import ast
 
 from general_manager.measurement.measurement import Measurement
 from general_manager.manager.generalManager import GeneralManagerMeta, GeneralManager
@@ -26,6 +27,28 @@ class MeasurementType(graphene.ObjectType):
     unit = graphene.String()
 
 
+class MeasurementScalar(graphene.Scalar):
+    """
+    A measurement in format "value unit", e.g. "12.5 m/s".
+    """
+
+    @staticmethod
+    def serialize(value: Measurement) -> str:
+        if not isinstance(value, Measurement):
+            raise TypeError(f"Expected Measurement, got {type(value)}")
+        return str(value)
+
+    @staticmethod
+    def parse_value(value: str) -> Measurement:
+        return Measurement.from_string(value)
+
+    @staticmethod
+    def parse_literal(node: Any) -> Measurement | None:
+        if isinstance(node, ast.StringValueNode):
+            return Measurement.from_string(node.value)
+        return None
+
+
 class PageInfo(graphene.ObjectType):
     total_count = graphene.Int(required=True)
     page_size = graphene.Int(required=False)
@@ -38,9 +61,9 @@ def getReadPermissionFilter(
     info: GraphQLResolveInfo,
 ) -> list[tuple[dict[str, Any], dict[str, Any]]]:
     """
-    Returns a list of filter and exclude dictionaries based on the read permissions for the specified manager class and user context.
-    
-    Each tuple in the returned list contains a filter dictionary and an exclude dictionary, representing permission-based constraints to be applied to queries.
+    Returns permission-based filter and exclude constraints for querying instances of a manager class.
+
+    For the given manager class and user context, retrieves a list of (filter, exclude) dictionary pairs that represent the read access restrictions to be applied to queries. Returns an empty list if no permission class is defined.
     """
     filters = []
     PermissionClass: type[BasePermission] | None = getattr(
@@ -74,9 +97,9 @@ class GraphQL:
     @classmethod
     def createGraphqlMutation(cls, generalManagerClass: type[GeneralManager]) -> None:
         """
-        Creates and registers GraphQL mutation classes (create, update, delete) for the given manager class if its interface overrides the corresponding base methods.
-        
-        For each supported mutation, generates a GraphQL mutation class with appropriate input and output fields, and adds it to the mutation registry.
+        Generates and registers GraphQL mutation classes for create, update, and delete operations on the specified manager class if its interface provides custom implementations.
+
+        For each supported mutation, a corresponding GraphQL mutation class is created and added to the mutation registry, enabling dynamic mutation support in the schema.
         """
 
         interface_cls: InterfaceBase | None = getattr(
@@ -112,9 +135,9 @@ class GraphQL:
     @classmethod
     def createGraphqlInterface(cls, generalManagerClass: GeneralManagerMeta) -> None:
         """
-        Creates and registers a GraphQL ObjectType for the given GeneralManager subclass.
-        
-        This method introspects the manager's interface and GraphQLProperty fields, maps them to Graphene fields with appropriate resolvers, registers the resulting type in the internal registry, and adds corresponding query fields to the schema.
+        Creates and registers a GraphQL ObjectType for a GeneralManager subclass.
+
+        Introspects the manager's interface and GraphQLProperty fields, maps them to Graphene fields with appropriate resolvers, registers the resulting type in the internal registry, and adds corresponding query fields to the schema.
         """
         interface_cls: InterfaceBase | None = getattr(
             generalManagerClass, "Interface", None
@@ -155,10 +178,10 @@ class GraphQL:
         generalManagerClass: GeneralManagerMeta,
     ) -> type[graphene.Enum] | None:
         """
-        Generate a Graphene Enum type listing the sortable fields for a given GeneralManager class.
-        
+        Creates a Graphene Enum type representing sortable fields for a given GeneralManager class.
+
         Returns:
-            A Graphene Enum type with options for each sortable attribute, including separate options for the value and unit of Measurement fields, or None if no sortable fields are found.
+            A Graphene Enum type with options for each sortable attribute, including separate entries for the value and unit of Measurement fields. Returns None if there are no sortable fields.
         """
         sort_options = []
         for (
@@ -168,9 +191,6 @@ class GraphQL:
             field_type = field_info["type"]
             if issubclass(field_type, GeneralManager):
                 continue
-            elif issubclass(field_type, Measurement):
-                sort_options.append(f"{field_name}_value")
-                sort_options.append(f"{field_name}_unit")
             else:
                 sort_options.append(field_name)
 
@@ -189,8 +209,15 @@ class GraphQL:
     ) -> type[graphene.InputObjectType] | None:
         """
         Dynamically generates a Graphene InputObjectType for filtering fields of a GeneralManager subclass.
-        
+
         Creates filter fields for each attribute based on its type, supporting numeric and string filter operations, and specialized handling for Measurement attributes. Returns the generated InputObjectType, or None if no applicable filter fields exist.
+
+        Parameters:
+            field_name (str): The name of the field to generate filter options for.
+            field_type (GeneralManagerMeta): The manager class whose attributes are used to build filter fields.
+
+        Returns:
+            type[graphene.InputObjectType] | None: The generated filter input type, or None if no filter fields are applicable.
         """
         number_options = ["exact", "gt", "gte", "lt", "lte"]
         string_options = [
@@ -212,11 +239,9 @@ class GraphQL:
             if issubclass(attr_type, GeneralManager):
                 continue
             elif issubclass(attr_type, Measurement):
-                filter_fields[f"{attr_name}_value"] = graphene.Float()
-                filter_fields[f"{attr_name}_unit"] = graphene.String()
+                filter_fields[f"{attr_name}"] = MeasurementScalar()
                 for option in number_options:
-                    filter_fields[f"{attr_name}_value__{option}"] = graphene.Float()
-                    filter_fields[f"{attr_name}_unit__{option}"] = graphene.String()
+                    filter_fields[f"{attr_name}__{option}"] = MeasurementScalar()
             else:
                 filter_fields[attr_name] = GraphQL._mapFieldToGrapheneRead(
                     attr_type, attr_name
@@ -246,8 +271,8 @@ class GraphQL:
     def _mapFieldToGrapheneRead(field_type: type, field_name: str) -> Any:
         """
         Maps a Python field type and name to the appropriate Graphene field for GraphQL schema generation.
-        
-        For `Measurement` fields, returns a field with an optional `target_unit` argument. For `GeneralManager` subclasses, returns a paginated field with filtering, exclusion, sorting, pagination, and grouping arguments if the field name ends with `_list`; otherwise, returns a single object field. For all other types, returns the corresponding Graphene scalar field.
+
+        For `Measurement` fields, returns a Graphene field with an optional `target_unit` argument. For `GeneralManager` subclasses, returns a paginated field with filtering, exclusion, sorting, pagination, and grouping arguments if the field name ends with `_list`; otherwise, returns a single object field. For all other types, returns the corresponding Graphene scalar field.
         """
         if issubclass(field_type, Measurement):
             return graphene.Field(MeasurementType, target_unit=graphene.String())
@@ -299,6 +324,8 @@ class GraphQL:
             return graphene.Float
         elif issubclass(field_type, (date, datetime)):
             return graphene.Date
+        elif issubclass(field_type, Measurement):
+            return MeasurementScalar
         else:
             return graphene.String
 
@@ -325,17 +352,16 @@ class GraphQL:
         reverse: bool,
     ) -> Bucket[GeneralManager]:
         """
-        Applies filtering, exclusion, and sorting parameters to a queryset.
-        
+        Apply filtering, exclusion, and sorting to a queryset based on provided parameters.
+
         Parameters:
-            queryset (Bucket[GeneralManager]): The queryset to modify.
-            filter_input (dict | str | None): Filters to apply, as a dict or JSON string.
-            exclude_input (dict | str | None): Exclusions to apply, as a dict or JSON string.
-            sort_by (graphene.Enum | None): Field to sort by, if provided.
-            reverse (bool): Whether to reverse the sort order.
-        
+            filter_input: Filters to apply, as a dictionary or JSON string.
+            exclude_input: Exclusions to apply, as a dictionary or JSON string.
+            sort_by: Field to sort by, as a Graphene Enum value.
+            reverse: If True, reverses the sort order.
+
         Returns:
-            Bucket[GeneralManager]: The modified queryset after applying filters, exclusions, and sorting.
+            The queryset after applying filters, exclusions, and sorting.
         """
         filters = GraphQL._parseInput(filter_input)
         if filters:
@@ -389,9 +415,9 @@ class GraphQL:
         base_getter: Callable[[Any], Any], fallback_manager_class: type[GeneralManager]
     ) -> Callable[..., Any]:
         """
-        Creates a resolver for GraphQL list fields that returns paginated, filtered, sorted, and optionally grouped results with permission checks applied.
-        
-        The returned resolver processes list queries by applying permission-based filtering, user-specified filters and exclusions, sorting, grouping, and pagination. It returns a dictionary containing the paginated items and pagination metadata.
+        Creates a resolver for GraphQL list fields that returns paginated, filtered, sorted, and optionally grouped results with permission checks.
+
+        The generated resolver applies permission-based filtering, user-specified filters and exclusions, sorting, grouping, and pagination to the list field. It returns a dictionary containing the resulting items and pagination metadata.
         """
 
         def resolver(
@@ -406,19 +432,19 @@ class GraphQL:
             group_by: list[str] | None = None,
         ) -> dict[str, Any]:
             """
-            Resolves a list field by returning paginated, filtered, sorted, and optionally grouped results with permission checks applied.
-            
+            Resolves a list field by returning filtered, excluded, sorted, grouped, and paginated results with permission checks.
+
             Parameters:
-                filter (dict[str, Any] | str | None): Filter criteria as a dictionary or JSON string.
-                exclude (dict[str, Any] | str | None): Exclusion criteria as a dictionary or JSON string.
-                sort_by (graphene.Enum | None): Field to sort by.
-                reverse (bool): Whether to reverse the sort order.
-                page (int | None): Page number for pagination.
-                page_size (int | None): Number of items per page.
-                group_by (list[str] | None): List of field names to group results by.
-            
+                filter: Filter criteria as a dictionary or JSON string.
+                exclude: Exclusion criteria as a dictionary or JSON string.
+                sort_by: Field to sort by, as a Graphene Enum.
+                reverse: If True, reverses the sort order.
+                page: Page number for pagination.
+                page_size: Number of items per page.
+                group_by: List of field names to group results by.
+
             Returns:
-                dict[str, Any]: A dictionary containing the paginated items under "items" and pagination metadata under "pageInfo".
+                A dictionary containing the paginated items under "items" and pagination metadata under "pageInfo".
             """
             base_queryset = base_getter(self)
             # use _manager_class from the attribute if available, otherwise fallback
@@ -453,9 +479,16 @@ class GraphQL:
         queryset: Bucket[GeneralManager], page: int | None, page_size: int | None
     ) -> Bucket[GeneralManager]:
         """
-        Return a paginated subset of the queryset based on the specified page number and page size.
-        
-        If either `page` or `page_size` is provided, pagination is applied; otherwise, the original queryset is returned.
+        Returns a paginated subset of the queryset based on the given page number and page size.
+
+        If neither `page` nor `page_size` is provided, the entire queryset is returned. Defaults to page 1 and page size 10 if only one parameter is specified.
+
+        Parameters:
+            page (int | None): The page number to retrieve (1-based).
+            page_size (int | None): The number of items per page.
+
+        Returns:
+            Bucket[GeneralManager]: The paginated queryset.
         """
         if page is not None or page_size is not None:
             page = page or 1
@@ -469,8 +502,8 @@ class GraphQL:
         queryset: Bucket[GeneralManager], group_by: list[str] | None
     ) -> Bucket[GeneralManager]:
         """
-        Group a queryset by the specified fields.
-        
+        Groups the queryset by the specified fields.
+
         If `group_by` is `[""]`, groups by all default fields. If `group_by` is a list of field names, groups by those fields. Returns the grouped queryset.
         """
         if group_by is not None:
@@ -483,13 +516,9 @@ class GraphQL:
     @staticmethod
     def _createMeasurementResolver(field_name: str) -> Callable[..., Any]:
         """
-        Creates a resolver function for Measurement fields that returns the value and unit, optionally converting to a specified target unit.
-        
-        Parameters:
-            field_name (str): The name of the Measurement field to resolve.
-        
-        Returns:
-            Callable[..., dict[str, Any] | None]: A resolver that returns a dictionary with 'value' and 'unit' keys, or None if permission is denied or the field is not a Measurement.
+        Creates a resolver for a Measurement field that returns its value and unit, with optional unit conversion.
+
+        The generated resolver checks read permissions for the specified field. If permitted and the field is a Measurement, it returns a dictionary containing the measurement's value and unit, converting to the specified target unit if provided. Returns None if permission is denied or the field is not a Measurement.
         """
 
         def resolver(
@@ -527,9 +556,9 @@ class GraphQL:
     @classmethod
     def _createResolver(cls, field_name: str, field_type: type) -> Callable[..., Any]:
         """
-        Selects and returns the appropriate resolver function for a given field based on its type and name.
-        
-        For fields ending with `_list` and referencing a `GeneralManager` subclass, returns a list resolver supporting pagination and filtering. For `Measurement` fields, returns a measurement resolver. For all other fields, returns a standard resolver.
+        Returns a resolver function for a field, selecting list, measurement, or standard resolution based on the field's type and name.
+
+        For fields ending with `_list` referencing a `GeneralManager` subclass, provides a resolver supporting pagination and filtering. For `Measurement` fields, returns a resolver that handles unit conversion and permission checks. For all other fields, returns a standard resolver with permission enforcement.
         """
         if field_name.endswith("_list") and issubclass(field_type, GeneralManager):
             return cls._createListResolver(
@@ -546,13 +575,9 @@ class GraphQL:
         item_type: type[graphene.ObjectType] | Callable[[], type[graphene.ObjectType]],
     ) -> type[graphene.ObjectType]:
         """
-        Return a paginated GraphQL ObjectType for the given item type, creating and caching it if it does not already exist.
-        
-        Parameters:
-            page_type_name (str): The name to use for the paginated type.
-        
-        Returns:
-            type[graphene.ObjectType]: A GraphQL ObjectType with `items` (list of item_type) and `pageInfo` (pagination metadata).
+        Returns a paginated GraphQL ObjectType for the specified item type, creating and caching it if it does not already exist.
+
+        The returned ObjectType includes an `items` field (a required list of the item type) and a `pageInfo` field (pagination metadata).
         """
         if page_type_name not in cls._page_type_registry:
             cls._page_type_registry[page_type_name] = type(
@@ -571,8 +596,8 @@ class GraphQL:
     ) -> None:
         """
         Adds paginated list and single-item query fields for a GeneralManager subclass to the GraphQL schema.
-        
-        The list query field supports filtering, exclusion, sorting, pagination, and grouping, returning a paginated result with metadata. The single-item query field retrieves an instance by its identification fields. Both queries are registered with their corresponding resolvers.
+
+        The list query field enables filtering, exclusion, sorting, pagination, and grouping, returning a paginated result with metadata. The single-item query field retrieves an instance by its identification fields. Both queries are registered with their respective resolvers.
         """
         if not issubclass(generalManagerClass, GeneralManager):
             raise TypeError(
@@ -642,10 +667,10 @@ class GraphQL:
     @classmethod
     def createWriteFields(cls, interface_cls: InterfaceBase) -> dict[str, Any]:
         """
-        Generate a dictionary of Graphene input fields for mutations based on the attributes of the provided interface class.
-        
-        Skips system-managed and derived attributes. For attributes referencing `GeneralManager` subclasses, uses an ID or list of IDs as appropriate. Other types are mapped to their corresponding Graphene scalar types. Each field is annotated with an `editable` attribute. An optional `history_comment` field, also marked as editable, is always included.
-        
+        Generates a dictionary of Graphene input fields for mutations based on the attributes of the provided interface class.
+
+        Skips system-managed and derived attributes. For attributes referencing `GeneralManager` subclasses, uses an ID or list of IDs as appropriate. Other types are mapped to their corresponding Graphene scalar types. Each field is annotated with an `editable` attribute. Always includes an optional `history_comment` field marked as editable.
+
         Returns:
             dict[str, Any]: Mapping of attribute names to Graphene input fields for mutation arguments.
         """
@@ -698,11 +723,11 @@ class GraphQL:
     ) -> type[graphene.Mutation] | None:
         """
         Dynamically generates a Graphene mutation class for creating an instance of a specified GeneralManager subclass.
-        
-        The generated mutation class accepts input fields defined by the manager's interface, filters out fields with `NOT_PROVIDED` values, and calls the manager's `create` method with the provided arguments and the current user's ID. If creation succeeds, it returns a dictionary with a success flag and the created instance; if an error occurs, a GraphQL error is raised. Returns None if the manager class does not define an interface.
-        
+
+        The generated mutation class uses the manager's interface to define input arguments, filters out fields with `NOT_PROVIDED` values, and invokes the manager's `create` method with the provided data and the current user's ID. On success, it returns a dictionary with a success flag and the created instance; on failure, it raises a GraphQL error. Returns `None` if the manager class does not define an interface.
+
         Returns:
-            The generated Graphene mutation class, or None if the manager class does not define an interface.
+            The generated Graphene mutation class, or `None` if the manager class does not define an interface.
         """
         interface_cls: InterfaceBase | None = getattr(
             generalManagerClass, "Interface", None
@@ -716,9 +741,9 @@ class GraphQL:
             **kwargs: Any,
         ) -> dict:
             """
-            Creates a new instance of the manager class with the provided arguments.
-            
-            Filters out fields set to `NOT_PROVIDED` before creation. Returns a dictionary containing a success flag and the created instance keyed by the manager class name. Raises a GraphQL error if creation fails.
+            Creates a new instance of the manager class using the provided arguments.
+
+            Filters out any fields set to `NOT_PROVIDED` before invoking the creation method. Returns a dictionary with a success flag and the created instance keyed by the manager class name. If creation fails, raises a GraphQL error and returns a dictionary with `success` set to `False`.
             """
             try:
                 kwargs = {
@@ -769,11 +794,11 @@ class GraphQL:
     ) -> type[graphene.Mutation] | None:
         """
         Generates a GraphQL mutation class for updating an instance of a GeneralManager subclass.
-        
-        The generated mutation accepts editable fields as arguments, invokes the manager's `update` method with the provided values and the current user's ID, and returns a dictionary containing the operation's success status and the updated instance. If the manager class does not define an `Interface`, returns None.
-        
+
+        The generated mutation accepts editable fields as arguments, calls the manager's `update` method with the provided values and the current user's ID, and returns a dictionary containing a success flag and the updated instance. Returns `None` if the manager class does not define an `Interface`.
+
         Returns:
-            The generated Graphene mutation class, or None if no interface is defined.
+            The generated Graphene mutation class, or `None` if no interface is defined.
         """
         interface_cls: InterfaceBase | None = getattr(
             generalManagerClass, "Interface", None
@@ -787,14 +812,14 @@ class GraphQL:
             **kwargs: Any,
         ) -> dict:
             """
-            Updates an instance of the specified GeneralManager class with the provided field values.
-            
+            Updates an instance of a GeneralManager subclass with the specified field values.
+
             Parameters:
-                info (GraphQLResolveInfo): The GraphQL resolver context, containing user and request information.
-                **kwargs: Fields to update, including the required 'id' of the instance.
-            
+                info (GraphQLResolveInfo): The GraphQL resolver context, including user and request data.
+                **kwargs: Field values to update, including the required 'id' of the instance.
+
             Returns:
-                dict: Contains 'success' (bool) and the updated instance keyed by its class name.
+                dict: A dictionary with 'success' (bool) and the updated instance keyed by its class name.
             """
             try:
                 manager_id = kwargs.pop("id", None)
@@ -841,9 +866,9 @@ class GraphQL:
     ) -> type[graphene.Mutation] | None:
         """
         Generates a GraphQL mutation class for deactivating (soft-deleting) an instance of a GeneralManager subclass.
-        
-        The generated mutation accepts input fields defined by the manager's interface, deactivates the specified instance using its ID, and returns a dictionary containing a success status and the deactivated instance keyed by the class name. If the manager class does not define an interface, returns None.
-        
+
+        The generated mutation accepts input fields defined by the manager's interface, deactivates the specified instance using its ID, and returns a dictionary containing a success status and the deactivated instance keyed by the class name. Returns None if the manager class does not define an interface.
+
         Returns:
             The generated Graphene mutation class, or None if no interface is defined.
         """
@@ -859,14 +884,10 @@ class GraphQL:
             **kwargs: Any,
         ) -> dict:
             """
-            Deactivates an instance of the specified GeneralManager class and returns the result.
-            
-            Parameters:
-                info (GraphQLResolveInfo): GraphQL resolver context containing user information.
-                **kwargs: Arguments including the instance ID to deactivate.
-            
+            Deactivates an instance of a GeneralManager subclass and returns the operation result.
+
             Returns:
-                dict: Contains "success" (bool) and the deactivated instance keyed by its class name.
+                dict: A dictionary with a "success" boolean and the deactivated instance keyed by its class name.
             """
             try:
                 manager_id = kwargs.pop("id", None)
@@ -908,9 +929,9 @@ class GraphQL:
     @staticmethod
     def _handleGraphQLError(error: Exception) -> None:
         """
-        Raises a GraphQLError with an appropriate error code based on the type of exception.
-        
-        If the error is a PermissionError, the code is set to "PERMISSION_DENIED". For ValueError or ValidationError, the code is "BAD_USER_INPUT". All other exceptions result in a code of "INTERNAL_SERVER_ERROR".
+        Raises a GraphQLError with a specific error code based on the exception type.
+
+        PermissionError results in "PERMISSION_DENIED", ValueError or ValidationError in "BAD_USER_INPUT", and all other exceptions in "INTERNAL_SERVER_ERROR".
         """
         if isinstance(error, PermissionError):
             raise GraphQLError(

{generalmanager-0.12.0 → generalmanager-0.12.1}/src/general_manager/measurement/measurement.py

@@ -24,7 +24,7 @@ class Measurement:
         """
         Initialize a Measurement with a numeric value and unit.
         
-        Creates a Measurement instance by converting the provided value to a Decimal and associating it with the specified unit. Accepts numeric types or strings convertible to Decimal.
+        Converts the provided value to a Decimal and associates it with the specified unit, creating a unit-aware measurement.
         
         Raises:
             ValueError: If the value cannot be converted to a Decimal.
@@ -226,12 +226,12 @@ class Measurement:
 
     def __mul__(self, other: Any) -> Measurement:
         """
-        Multiplies this measurement by another measurement or a numeric value.
+        Multiply this measurement by another measurement or a numeric value.
         
-        Multiplication between two currency measurements is not permitted. When multiplying by another measurement, the resulting measurement combines their units. When multiplying by a numeric value, only the magnitude is scaled.
+        Multiplication between two currency measurements is not allowed. When multiplying by another measurement, the resulting measurement combines their units. When multiplying by a numeric value, only the magnitude is scaled.
         
         Returns:
-            Measurement: A new measurement representing the product.
+            Measurement: The product as a new Measurement instance.
         
         Raises:
             TypeError: If both operands are currency measurements, or if the operand is neither a Measurement nor a numeric value.
@@ -304,17 +304,19 @@ class Measurement:
 
     def _compare(self, other: Any, operation: Callable[..., bool]) -> bool:
         """
-        Compares this Measurement to another using a specified comparison operation.
-
-        If `other` is a string, it is parsed as a Measurement. The comparison is performed after converting `other` to this instance's unit. Raises a TypeError if `other` is not a Measurement or a valid string, and a ValueError if the measurements have incompatible dimensions.
-
+        Compare this Measurement to another using a specified comparison operation.
+        
+        If `other` is a string, it is parsed as a Measurement. Returns `False` if `other` is `None` or an empty value. Raises `TypeError` if `other` is not a Measurement or a valid string. Raises `ValueError` if the measurements have incompatible dimensions.
+        
         Parameters:
-            other: The object to compare, either a Measurement or a string in the format "value unit".
-            operation: A callable that takes two magnitudes and returns a boolean.
-
+            other: The object to compare, which can be a Measurement instance or a string in the format "value unit".
+            operation: A callable that takes two magnitudes and returns a boolean result.
+        
         Returns:
-            bool: The result of the comparison.
+            bool: The result of applying the comparison operation to the magnitudes.
         """
+        if other is None or other in ("", [], (), {}):
+            return False
         if isinstance(other, str):
             other = Measurement.from_string(other)
 

generalmanager-0.12.1/src/general_manager/measurement/measurementField.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+from django.db import models
+from django.core.exceptions import ValidationError
+from django.db.models.expressions import Col
+from decimal import Decimal
+import pint
+from general_manager.measurement.measurement import Measurement, ureg, currency_units
+
+
+class MeasurementField(models.Field):
+    description = "Stores a measurement (value + unit) but exposes a single field API"
+
+    empty_values = (None, "", [], (), {})
+
+    def __init__(
+        self, base_unit: str, *args, null=False, blank=False, editable=True, **kwargs
+    ):
+        """
+        Initialize a MeasurementField to store a numeric value and its unit with unit-aware validation.
+
+        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.
+
+        The field internally manages a DecimalField for the value and a CharField for the unit, both configured according to the provided options.
+        """
+        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)
+
+        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)
+        """
+        Registers the MeasurementField with the model class and attaches internal value and unit fields.
+
+        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.
+        """
+        super().contribute_to_class(cls, name, private_only=private_only, **kwargs)
+        self.concrete = False
+        self.column = None  # type: ignore # will not be set in db
+        self.field = self
+
+        self.value_attr = f"{name}_value"
+        self.unit_attr = f"{name}_unit"
+
+        # prevent duplicate attributes
+        if hasattr(cls, self.value_attr):
+            self.value_field = getattr(cls, self.value_attr).field
+        else:
+            self.value_field.set_attributes_from_name(self.value_attr)
+            self.value_field.contribute_to_class(cls, self.value_attr)
+
+        if hasattr(cls, self.unit_attr):
+            self.unit_field = getattr(cls, self.unit_attr).field
+        else:
+            self.unit_field.set_attributes_from_name(self.unit_attr)
+            self.unit_field.contribute_to_class(cls, self.unit_attr)
+
+        # Descriptor override
+        setattr(cls, name, self)
+
+    # ---- ORM Delegation ----
+    def get_col(self, alias, output_field=None):
+        """
+        Returns a Django ORM column expression for the internal value field, enabling queries on the numeric part of the measurement.
+        """
+        return Col(alias, self.value_field, output_field or self.value_field)  # type: ignore
+
+    def get_lookup(self, lookup_name):
+        """
+        Return the lookup class for the specified lookup name, delegating to the internal value field.
+
+        Parameters:
+                lookup_name (str): The name of the lookup to retrieve.
+
+        Returns:
+                The lookup class corresponding to the given name, as provided by the internal decimal value field.
+        """
+        return self.value_field.get_lookup(lookup_name)
+
+    def get_transform(self, lookup_name) -> models.Transform | None:
+        """
+        Delegates retrieval of a transform operation to the internal value field.
+
+        Returns:
+            The transform corresponding to the given lookup name, or None if not found.
+        """
+        return self.value_field.get_transform(lookup_name)
+
+    def db_type(self, connection) -> None:  # type: ignore
+        """
+        Return None to indicate that MeasurementField does not correspond to a single database column.
+
+        This field manages its data using separate internal fields and does not require a direct database type.
+        """
+        return None
+
+    def run_validators(self, value: Measurement | None) -> None:
+        """
+        Runs all validators on the provided Measurement value if it is not None.
+
+        Parameters:
+            value (Measurement | None): The measurement to validate, or None to skip validation.
+        """
+        if value is None:
+            return
+        for v in self.validators:
+            v(value)
+
+    def clean(
+        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.
+
+        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.
+
+        Returns:
+            Measurement | None: The validated measurement value, or None if the input was None.
+        """
+        self.validate(value, model_instance)
+        self.run_validators(value)
+        return value
+
+    def to_python(self, value):
+        """
+        Returns the input value unchanged.
+
+        This method is required by Django custom fields to convert database values to Python objects, but no conversion is performed for this field.
+        """
+        return value
+
+    def get_prep_value(self, value):
+        """
+        Prepare a value for database storage by converting a Measurement to its decimal magnitude in the base unit.
+
+        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.
+
+        Returns:
+            Decimal: The numeric value of the measurement in the base unit, or None if the input is None.
+
+        Raises:
+            ValidationError: If the value is not a Measurement or cannot be converted to the base unit.
+        """
+        if value is None:
+            return None
+        if isinstance(value, str):
+            value = Measurement.from_string(value)
+        if isinstance(value, Measurement):
+            try:
+                return Decimal(str(value.quantity.to(self.base_unit).magnitude))
+            except pint.errors.DimensionalityError as e:
+                raise ValidationError(
+                    {self.name: [f"Unit must be compatible with '{self.base_unit}'."]}
+                ) from e
+        raise ValidationError(
+            {self.name: ["Value must be a Measurement instance or None."]}
+        )
+
+    # ------------ Descriptor ------------
+    def __get__(  # type: ignore
+        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.
+
+        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.
+        """
+        if instance is None:
+            return self
+        val = getattr(instance, self.value_attr)
+        unit = getattr(instance, self.unit_attr)
+        if val is None or unit is None:
+            return None
+        qty_base = Decimal(val) * ureg(self.base_unit)
+        try:
+            qty_orig = qty_base.to(unit)
+        except pint.errors.DimensionalityError:
+            qty_orig = qty_base
+        return Measurement(qty_orig.magnitude, str(qty_orig.units))
+
+    def __set__(self, instance, value):
+        """
+        Assigns a measurement value to the model instance, validating type, unit compatibility, and editability.
+
+        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.
+        """
+        if not self.editable:
+            raise ValidationError(f"{self.name} is not editable.")
+        if value is None:
+            setattr(instance, self.value_attr, None)
+            setattr(instance, self.unit_attr, None)
+            return
+        if isinstance(value, str):
+            try:
+                value = Measurement.from_string(value)
+            except ValueError as e:
+                raise ValidationError(
+                    {self.name: ["Value must be a Measurement instance or None."]}
+                ) from e
+        if not isinstance(value, Measurement):
+            raise ValidationError(
+                {self.name: ["Value must be a Measurement instance or None."]}
+            )
+
+        if str(self.base_unit) in currency_units:
+            if not value.is_currency():
+                raise ValidationError(
+                    {
+                        self.name: [
+                            f"Unit must be a currency ({', '.join(currency_units)})."
+                        ]
+                    }
+                )
+        else:
+            if value.is_currency():
+                raise ValidationError({self.name: ["Unit cannot be a currency."]})
+
+        try:
+            base_mag = value.quantity.to(self.base_unit).magnitude
+        except pint.errors.DimensionalityError as e:
+            raise ValidationError(
+                {self.name: [f"Unit must be compatible with '{self.base_unit}'."]}
+            ) from e
+
+        setattr(instance, self.value_attr, Decimal(str(base_mag)))
+        setattr(instance, self.unit_attr, str(value.quantity.units))
+
+    def validate(
+        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.
+
+        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.
+        """
+        if value is None:
+            if not self.null:
+                raise ValidationError(self.error_messages["null"], code="null")
+            return
+        if value in ("", [], (), {}):
+            if not self.blank:
+                raise ValidationError(self.error_messages["blank"], code="blank")
+            return
+
+        for validator in self.validators:
+            validator(value)

generalmanager-0.12.0/src/general_manager/measurement/measurementField.py

@@ -1,168 +0,0 @@
-# fields.py
-from __future__ import annotations
-from django.db import models
-from django.core.exceptions import ValidationError
-from decimal import Decimal
-from general_manager.measurement.measurement import Measurement, ureg, currency_units
-import pint
-from typing import Any
-
-
-class MeasurementField(models.Field):  # type: ignore
-    description = (
-        "A field that stores a measurement value, both in base unit and original unit"
-    )
-
-    def __init__(
-        self,
-        base_unit: str,
-        null: bool = False,
-        blank: bool = False,
-        editable: bool = True,
-        *args: Any,
-        **kwargs: Any,
-    ):
-        """
-        Initialize a MeasurementField to store values in a specified base unit and retain the original unit.
-        
-        Parameters:
-            base_unit (str): The canonical unit in which values are stored (e.g., 'meter').
-            null (bool, optional): Whether the field allows NULL values.
-            blank (bool, optional): Whether the field allows blank values.
-            editable (bool, optional): Whether the field is editable in Django admin and forms.
-        
-        The field internally manages a DecimalField for the value (in the base unit) and a CharField for the original unit.
-        """
-        self.base_unit = base_unit  # E.g., 'meter' for length units
-        # Determine the dimensionality of the base unit
-        self.base_dimension = ureg.parse_expression(self.base_unit).dimensionality
-        # Internal fields
-        null_blank_kwargs = {}
-        if null is True:
-            null_blank_kwargs["null"] = True
-        if blank is True:
-            null_blank_kwargs["blank"] = True
-        self.editable = editable
-        self.value_field: models.DecimalField[Decimal] = models.DecimalField(
-            max_digits=30,
-            decimal_places=10,
-            db_index=True,
-            **null_blank_kwargs,
-            editable=editable,
-        )
-        self.unit_field: models.CharField[str] = models.CharField(
-            max_length=30, **null_blank_kwargs, editable=editable
-        )
-        super().__init__(null=null, blank=blank, *args, **kwargs)
-
-    def contribute_to_class(
-        self, cls: type, name: str, private_only: bool = False, **kwargs: Any
-    ) -> None:
-        """
-        Integrates the MeasurementField into the Django model class, setting up internal fields for value and unit storage.
-        
-        This method assigns unique attribute names for the value and unit fields, attaches them to the model, and sets the descriptor for the custom field on the model class.
-        """
-        self.name = name
-        self.value_attr = f"{name}_value"
-        self.unit_attr = f"{name}_unit"
-        self.value_field.attname = self.value_attr
-        self.unit_field.attname = self.unit_attr
-        self.value_field.name = self.value_attr
-        self.unit_field.name = self.unit_attr
-        self.value_field.column = self.value_attr
-        self.unit_field.column = self.unit_attr
-
-        self.value_field.model = cls
-        self.unit_field.model = cls
-
-        self.value_field.contribute_to_class(cls, self.value_attr)
-        self.unit_field.contribute_to_class(cls, self.unit_attr)
-
-        setattr(cls, self.name, self)
-
-    def __get__(self, instance: Any, owner: Any) -> Any:
-        if instance is None:
-            return self
-        value = getattr(instance, self.value_attr)
-        unit = getattr(instance, self.unit_attr)
-        if value is None or unit is None:
-            return None
-        # Create a Measurement object with the value in the original unit
-        quantity_in_base_unit = Decimal(value) * ureg(self.base_unit)
-        # Convert back to the original unit
-        try:
-            quantity_in_original_unit: pint.Quantity = quantity_in_base_unit.to(unit)  # type: ignore
-        except pint.errors.DimensionalityError:
-            # If the unit is not compatible, return the value in base unit
-            quantity_in_original_unit = quantity_in_base_unit
-        return Measurement(
-            quantity_in_original_unit.magnitude, str(quantity_in_original_unit.units)
-        )
-
-    def __set__(self, instance: Any, value: Any) -> None:
-        if self.editable is False:
-            raise ValidationError(f"{self.name} is not editable.")
-        if value is None:
-            setattr(instance, self.value_attr, None)
-            setattr(instance, self.unit_attr, None)
-            return
-        elif isinstance(value, str):
-            try:
-                value = Measurement.from_string(value)
-            except ValueError:
-                raise ValidationError(
-                    {self.name: ["Value must be a Measurement instance or None."]}
-                )
-        if isinstance(value, Measurement):
-            if str(self.base_unit) in currency_units:
-                # Base unit is a currency
-                if not value.is_currency():
-                    raise ValidationError(
-                        {
-                            self.name: [
-                                f"The unit must be a currency ({', '.join(currency_units)})."
-                            ]
-                        }
-                    )
-            else:
-                # Physical unit
-                if value.is_currency():
-                    raise ValidationError(
-                        {self.name: ["The unit cannot be a currency."]}
-                    )
-                elif value.quantity.dimensionality != self.base_dimension:
-                    raise ValidationError(
-                        {
-                            self.name: [
-                                f"The unit must be compatible with '{self.base_unit}'."
-                            ]
-                        }
-                    )
-            # Store the value in the base unit
-            try:
-                value_in_base_unit: Any = value.quantity.to(self.base_unit).magnitude  # type: ignore
-            except pint.errors.DimensionalityError:
-                raise ValidationError(
-                    {
-                        self.name: [
-                            f"The unit must be compatible with '{self.base_unit}'."
-                        ]
-                    }
-                )
-            setattr(instance, self.value_attr, Decimal(str(value_in_base_unit)))
-            # Store the original unit
-            setattr(instance, self.unit_attr, str(value.quantity.units))
-        else:
-            raise ValidationError(
-                {self.name: ["Value must be a Measurement instance or None."]}
-            )
-
-    def get_prep_value(self, value: Any) -> Any:
-        # Not needed since we use internal fields
-        pass
-
-    def deconstruct(self):
-        name, path, args, kwargs = super().deconstruct()
-        kwargs["base_unit"] = self.base_unit
-        return name, path, args, kwargs