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

general_manager/manager/input.py

@@ -1,5 +1,7 @@
+"""Input field metadata used by GeneralManager interfaces."""
+
 from __future__ import annotations
-from typing import Iterable, Optional, Callable, List, TypeVar, Generic, Any
+from typing import Iterable, Optional, Callable, List, TypeVar, Generic, Any, Type, cast
 import inspect
 
 from general_manager.manager.generalManager import GeneralManager
@@ -11,43 +13,49 @@ INPUT_TYPE = TypeVar("INPUT_TYPE", bound=type)
 
 
 class Input(Generic[INPUT_TYPE]):
+    """Descriptor describing the expected type and constraints for an interface input."""
+
     def __init__(
         self,
         type: INPUT_TYPE,
         possible_values: Optional[Callable | Iterable] = None,
         depends_on: Optional[List[str]] = None,
-    ):
+    ) -> None:
         """
         Create an Input specification with type information, allowed values, and dependency metadata.
-        
+
         Parameters:
-            type: The expected Python type for the input value.
-            possible_values: Optional; an iterable of allowed values or a callable returning allowed values.
-            depends_on: Optional; a list of dependency names. If not provided and possible_values is callable, dependencies are inferred from the callable's parameter names.
+            type (INPUT_TYPE): Expected Python type for the input value.
+            possible_values (Callable | Iterable | None): Allowed values as an iterable or callable returning allowed values.
+            depends_on (list[str] | None): Names of other inputs required for computing possible values.
         """
-        self.type = type
+        self.type: Type[Any] = cast(Type[Any], type)
         self.possible_values = possible_values
         self.is_manager = issubclass(type, GeneralManager)
 
         if depends_on is not None:
-            # Verwende die angegebenen Abhängigkeiten
+            # Use the provided dependency list when available
             self.depends_on = depends_on
         elif callable(possible_values):
-            # Ermittele Abhängigkeiten automatisch aus den Parametern der Funktion
+            # Derive dependencies automatically from the callable signature
             sig = inspect.signature(possible_values)
             self.depends_on = list(sig.parameters.keys())
         else:
-            # Keine Abhängigkeiten
+            # Default to no dependencies when none are provided
             self.depends_on = []
 
     def cast(self, value: Any) -> Any:
         """
-        Converts the input value to the type specified by this Input instance, handling special cases for dates, datetimes, GeneralManager subclasses, and Measurement types.
-        
-        If the value is already of the target type, it is returned unchanged. For date and datetime types, string and cross-type conversions are supported. For GeneralManager subclasses, instances are constructed from a dictionary or an ID. For Measurement, string values are parsed accordingly. Otherwise, the value is cast using the target type's constructor.
-        
+        Convert a raw value to the configured input type.
+
+        Parameters:
+            value (Any): Raw value supplied by the caller.
+
         Returns:
-            The value converted to the target type, or an instance of the target type.
+            Any: Value converted to the target type.
+
+        Raises:
+            ValueError: If the value cannot be converted to the target type.
         """
         if self.type == date:
             if isinstance(value, datetime) and type(value) is not date:

general_manager/manager/meta.py

@@ -1,11 +1,12 @@
+"""Metaclass infrastructure for registering GeneralManager subclasses."""
+
 from __future__ import annotations
 
 from django.conf import settings
-from typing import Any, Type, TYPE_CHECKING, Generic, TypeVar, Iterable
+from typing import Any, Type, TYPE_CHECKING, ClassVar, TypeVar, Iterable, cast
 from general_manager.interface.baseInterface import InterfaceBase
 
 if TYPE_CHECKING:
-    from general_manager.interface.readOnlyInterface import ReadOnlyInterface
     from general_manager.manager.generalManager import GeneralManager
 
 
@@ -17,32 +18,40 @@ class _nonExistent:
 
 
 class GeneralManagerMeta(type):
-    all_classes: list[Type[GeneralManager]] = []
-    read_only_classes: list[Type[GeneralManager]] = []
-    pending_graphql_interfaces: list[Type[GeneralManager]] = []
-    pending_attribute_initialization: list[Type[GeneralManager]] = []
+    """Metaclass responsible for wiring GeneralManager interfaces and registries."""
+
+    all_classes: ClassVar[list[Type[GeneralManager]]] = []
+    read_only_classes: ClassVar[list[Type[GeneralManager]]] = []
+    pending_graphql_interfaces: ClassVar[list[Type[GeneralManager]]] = []
+    pending_attribute_initialization: ClassVar[list[Type[GeneralManager]]] = []
     Interface: type[InterfaceBase]
 
-    def __new__(mcs, name: str, bases: tuple[type, ...], attrs: dict[str, Any]) -> type:
+    def __new__(
+        mcs: type["GeneralManagerMeta"],
+        name: str,
+        bases: tuple[type, ...],
+        attrs: dict[str, Any],
+    ) -> type:
         """
-        Creates a new class using the metaclass, integrating interface hooks and registering the class for attribute initialization and tracking.
+        Create a new GeneralManager subclass and register its interface hooks.
 
-        If the class definition includes an `Interface` attribute, validates it as a subclass of `InterfaceBase`, applies pre- and post-creation hooks from the interface, and registers the resulting class for attribute initialization and management. Regardless of interface presence, the new class is tracked for pending GraphQL interface creation.
+        Parameters:
+            name (str): Name of the class being created.
+            bases (tuple[type, ...]): Base classes inherited by the new class.
+            attrs (dict[str, Any]): Class namespace supplied during creation.
 
         Returns:
-            The newly created class, potentially augmented with interface integration and registration logic.
+            type: Newly created class augmented with interface integration.
         """
 
         def createNewGeneralManagerClass(
-            mcs, name: str, bases: tuple[type, ...], attrs: dict[str, Any]
-        ) -> Type[GeneralManager]:
-            """
-            Create a new GeneralManager class using the standard metaclass instantiation process.
-
-            Returns:
-                The newly created GeneralManager subclass.
-            """
-            return super().__new__(mcs, name, bases, attrs)
+            mcs: type["GeneralManagerMeta"],
+            name: str,
+            bases: tuple[type, ...],
+            attrs: dict[str, Any],
+        ) -> Type["GeneralManager"]:
+            """Helper to instantiate the class via the default ``type.__new__``."""
+            return cast(Type["GeneralManager"], type.__new__(mcs, name, bases, attrs))
 
         if "Interface" in attrs:
             interface = attrs.pop("Interface")
@@ -68,60 +77,51 @@ class GeneralManagerMeta(type):
     @staticmethod
     def createAtPropertiesForAttributes(
         attributes: Iterable[str], new_class: Type[GeneralManager]
-    ):
+    ) -> None:
         """
-        Dynamically creates and assigns property descriptors to a class for each given attribute name.
-        
-        For each attribute, adds a property to the class that:
-        - Returns the field type from the class's interface when accessed on the class itself.
-        - Retrieves the value from the instance's `_attributes` dictionary when accessed on an instance.
-        - If the attribute value is callable, invokes it with the instance's interface and returns the result.
-        - Raises `AttributeError` if the attribute is missing or if an error occurs during callable invocation.
-        
+        Attach descriptor-based properties for each attribute declared on the interface.
+
         Parameters:
-            attributes (Iterable[str]): Names of attributes for which to create property descriptors.
-            new_class (Type[GeneralManager]): The class to which the properties will be added.
+            attributes (Iterable[str]): Names of attributes for which descriptors are created.
+            new_class (Type[GeneralManager]): Class receiving the generated descriptors.
         """
 
-        def desciptorMethod(attr_name: str, new_class: type):
-            """
-            Create a property descriptor for dynamic attribute access and callable resolution.
-            
-            When accessed on the class, returns the field type from the class's associated interface. When accessed on an instance, retrieves the attribute value from the instance's `_attributes` dictionary; if the value is callable, it is invoked with the instance's interface. Raises `AttributeError` if the attribute is missing or if a callable attribute raises an exception.
-            """
+        def descriptorMethod(
+            attr_name: str,
+            new_class: type,
+        ) -> object:
+            """Create a descriptor that resolves attribute values from the interface at runtime."""
 
-            class Descriptor(Generic[GeneralManagerType]):
-                def __init__(self, attr_name: str, new_class: Type[GeneralManager]):
-                    self.attr_name = attr_name
-                    self.new_class = new_class
+            class Descriptor:
+                def __init__(
+                    self, descriptor_attr_name: str, descriptor_class: Type[Any]
+                ) -> None:
+                    self._attr_name = descriptor_attr_name
+                    self._class = descriptor_class
 
                 def __get__(
                     self,
-                    instance: GeneralManagerType | None,
+                    instance: Any | None,
                     owner: type | None = None,
-                ):
-                    """
-                    Retrieve the value of a dynamically defined attribute from an instance or its interface.
-                    
-                    When accessed on the class, returns the field type from the associated interface. When accessed on an instance, retrieves the attribute value from the instance's `_attributes` dictionary. If the attribute is callable, it is invoked with the instance's interface. Raises `AttributeError` if the attribute is missing or if a callable attribute raises an exception.
-                    """
+                ) -> Any:
+                    """Return the field type on the class or the stored value on an instance."""
                     if instance is None:
-                        return self.new_class.Interface.getFieldType(self.attr_name)
-                    attribute = instance._attributes.get(attr_name, _nonExistent)
+                        return self._class.Interface.getFieldType(self._attr_name)
+                    attribute = instance._attributes.get(self._attr_name, _nonExistent)
                     if attribute is _nonExistent:
                         raise AttributeError(
-                            f"{self.attr_name} not found in {instance.__class__.__name__}"
+                            f"{self._attr_name} not found in {instance.__class__.__name__}"
                         )
                     if callable(attribute):
                         try:
                             attribute = attribute(instance._interface)
                         except Exception as e:
                             raise AttributeError(
-                                f"Error calling attribute {self.attr_name}: {e}"
+                                f"Error calling attribute {self._attr_name}: {e}"
                             ) from e
                     return attribute
 
-            return Descriptor(attr_name, new_class)
+            return Descriptor(attr_name, cast(Type[Any], new_class))
 
         for attr_name in attributes:
-            setattr(new_class, attr_name, desciptorMethod(attr_name, new_class))
+            setattr(new_class, attr_name, descriptorMethod(attr_name, new_class))

general_manager/measurement/__init__.py

@@ -1,2 +1,37 @@
-from .measurement import Measurement
-from .measurementField import MeasurementField
+"""Public API for measurement utilities."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from general_manager.utils.public_api import build_module_dir, resolve_export
+
+__all__ = [
+    "Measurement",
+    "MeasurementField",
+    "ureg",
+    "currency_units",
+]
+
+_MODULE_MAP = {
+    "Measurement": ("general_manager.measurement.measurement", "Measurement"),
+    "ureg": ("general_manager.measurement.measurement", "ureg"),
+    "currency_units": ("general_manager.measurement.measurement", "currency_units"),
+    "MeasurementField": (
+        "general_manager.measurement.measurementField",
+        "MeasurementField",
+    ),
+}
+
+
+def __getattr__(name: str) -> Any:
+    return resolve_export(
+        name,
+        module_all=__all__,
+        module_map=_MODULE_MAP,
+        module_globals=globals(),
+    )
+
+
+def __dir__() -> list[str]:
+    return build_module_dir(module_all=__all__, module_globals=globals())

general_manager/measurement/measurement.py

@@ -1,3 +1,5 @@
+"""Utility types and helpers for unit-aware measurements."""
+
 # units.py
 from __future__ import annotations
 from typing import Any, Callable
@@ -20,14 +22,19 @@ for currency in currency_units:
 
 
 class Measurement:
-    def __init__(self, value: Decimal | float | int | str, unit: str):
+    def __init__(self, value: Decimal | float | int | str, unit: str) -> None:
         """
-        Initialize a Measurement with a numeric value and unit.
-        
-        Converts the provided value to a Decimal and associates it with the specified unit, creating a unit-aware measurement.
-        
+        Create a measurement from a numeric value and a unit string.
+
+        Parameters:
+            value (Decimal | float | int | str): Numeric value, which will be coerced to `Decimal` if needed.
+            unit (str): Unit name registered in the unit registry, including currencies and physical units.
+
+        Returns:
+            None
+
         Raises:
-            ValueError: If the value cannot be converted to a Decimal.
+            ValueError: If the numeric value cannot be converted to `Decimal`.
         """
         if not isinstance(value, (Decimal, float, int)):
             try:
@@ -38,12 +45,12 @@ class Measurement:
             value = Decimal(str(value))
         self.__quantity = ureg.Quantity(self.formatDecimal(value), unit)
 
-    def __getstate__(self):
+    def __getstate__(self) -> dict[str, str]:
         """
-        Return a dictionary representing the serializable state of the measurement, including its magnitude and unit as strings.
+        Produce a serialisable representation of the measurement.
 
         Returns:
-            dict: Contains 'magnitude' and 'unit' keys for serialization purposes.
+            dict[str, str]: Mapping with `magnitude` and `unit` entries for pickling.
         """
         state = {
             "magnitude": str(self.magnitude),
@@ -51,12 +58,15 @@ class Measurement:
         }
         return state
 
-    def __setstate__(self, state):
+    def __setstate__(self, state: dict[str, str]) -> None:
         """
-        Restore the Measurement object from a serialized state.
+        Recreate the internal quantity from a serialized representation.
 
         Parameters:
-            state (dict): Dictionary with 'magnitude' (as a string) and 'unit' (as a string) representing the measurement.
+            state (dict[str, str]): Serialized state containing `magnitude` and `unit` values.
+
+        Returns:
+            None
         """
         value = Decimal(state["magnitude"])
         unit = state["unit"]
@@ -65,30 +75,46 @@ class Measurement:
     @property
     def quantity(self) -> PlainQuantity:
         """
-        Return the internal quantity as a `PlainQuantity` object from the `pint` library.
+        Access the underlying pint quantity for advanced operations.
+
+        Returns:
+            PlainQuantity: Pint quantity representing the measurement value and unit.
         """
         return self.__quantity
 
     @property
     def magnitude(self) -> Decimal:
+        """
+        Fetch the numeric component of the measurement.
+
+        Returns:
+            Decimal: Magnitude of the measurement in its current unit.
+        """
         return self.__quantity.magnitude
 
     @property
     def unit(self) -> str:
+        """
+        Retrieve the unit label associated with the measurement.
+
+        Returns:
+            str: Canonical unit string as provided by the unit registry.
+        """
         return str(self.__quantity.units)
 
     @classmethod
     def from_string(cls, value: str) -> Measurement:
         """
-        Creates a Measurement instance from a string containing a numeric value and a unit.
+        Create a measurement from a textual representation of magnitude and unit.
 
-        If the string contains only a value, it is treated as dimensionless. If the string contains both a value and a unit separated by a space, both are used to construct the Measurement. Raises ValueError if the format is invalid or the value cannot be parsed.
+        Parameters:
+            value (str): String formatted as `"<number> <unit>"`; a single numeric value is treated as dimensionless.
 
         Returns:
-            Measurement: The constructed Measurement object.
+            Measurement: Measurement parsed from the provided string.
 
         Raises:
-            ValueError: If the string format is invalid or the value cannot be parsed as a number.
+            ValueError: If the string lacks a unit, has too many tokens, or contains a non-numeric magnitude.
         """
         splitted = value.split(" ")
         if len(splitted) == 1:
@@ -104,6 +130,15 @@ class Measurement:
 
     @staticmethod
     def formatDecimal(value: Decimal) -> Decimal:
+        """
+        Normalise decimals so integers have no fractional component.
+
+        Parameters:
+            value (Decimal): Decimal value that should be normalised.
+
+        Returns:
+            Decimal: Normalised decimal with insignificant trailing zeros removed.
+        """
         value = value.normalize()
         if value == value.to_integral_value():
             try:
@@ -113,7 +148,11 @@ class Measurement:
         else:
             return value
 
-    def to(self, target_unit: str, exchange_rate: float | None = None):
+    def to(
+        self,
+        target_unit: str,
+        exchange_rate: float | None = None,
+    ) -> Measurement:
         """
         Convert this measurement to a specified target unit, supporting both currency and physical unit conversions.
 
@@ -147,21 +186,28 @@ class Measurement:
             unit = str(converted_quantity.units)
             return Measurement(value, unit)
 
-    def is_currency(self):
-        # Check if the unit is a defined currency
+    def is_currency(self) -> bool:
         """
-        Return True if the measurement's unit is one of the defined currency units.
+        Determine whether the measurement's unit represents a configured currency.
+
+        Returns:
+            bool: True if the unit matches one of the registered currency codes.
         """
         return str(self.unit) in currency_units
 
     def __add__(self, other: Any) -> Measurement:
         """
-        Add this measurement to another, supporting both currency and physical units.
+        Add another measurement while enforcing currency and dimensional rules.
 
-        Addition is permitted only if both operands are currencies of the same unit or both are physical units with compatible dimensions. Raises a TypeError if operands are of different types (currency vs. physical unit) or not Measurement instances, and raises a ValueError if units are incompatible.
+        Parameters:
+            other (Any): Measurement or compatible value used as the addend.
 
         Returns:
-            Measurement: A new Measurement representing the sum.
+            Measurement: Measurement representing the sum.
+
+        Raises:
+            TypeError: If the operand is not a measurement or mixes currency with non-currency units.
+            ValueError: If the operands use incompatible currency codes or physical dimensions.
         """
         if not isinstance(other, Measurement):
             raise TypeError("Addition is only allowed between Measurement instances.")
@@ -194,12 +240,17 @@ class Measurement:
 
     def __sub__(self, other: Any) -> Measurement:
         """
-        Subtracts another Measurement from this one, enforcing unit compatibility.
+        Subtract another measurement while enforcing unit compatibility.
 
-        Subtraction is permitted only between two currency measurements of the same unit or two physical measurements with compatible dimensions. Raises a TypeError if the operand is not a Measurement or if subtracting between a currency and a physical unit. Raises a ValueError if subtracting different currencies or incompatible physical units.
+        Parameters:
+            other (Any): Measurement or compatible value that should be subtracted.
 
         Returns:
-            Measurement: A new Measurement representing the result of the subtraction.
+            Measurement: Measurement representing the difference.
+
+        Raises:
+            TypeError: If the operand is not a measurement or mixes currency with non-currency units.
+            ValueError: If the operands use incompatible currency codes or physical dimensions.
         """
         if not isinstance(other, Measurement):
             raise TypeError(
@@ -226,15 +277,16 @@ class Measurement:
 
     def __mul__(self, other: Any) -> Measurement:
         """
-        Multiply this measurement by another measurement or a numeric value.
-        
-        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.
-        
+        Multiply the measurement by another measurement or scalar.
+
+        Parameters:
+            other (Any): Measurement or numeric value used as the multiplier.
+
         Returns:
-            Measurement: The product as a new Measurement instance.
-        
+            Measurement: Product expressed as a measurement.
+
         Raises:
-            TypeError: If both operands are currency measurements, or if the operand is neither a Measurement nor a numeric value.
+            TypeError: If multiplying two currency amounts or using an unsupported type.
         """
         if isinstance(other, Measurement):
             if self.is_currency() and other.is_currency():
@@ -257,17 +309,16 @@ class Measurement:
 
     def __truediv__(self, other: Any) -> Measurement:
         """
-        Divide this measurement by another measurement or a numeric value.
+        Divide the measurement by another measurement or scalar value.
 
-        If dividing by another `Measurement`:
-          - Division between two *different* currencies is disallowed (raises TypeError).
-          - Division between the *same* currency is allowed and yields a dimensionless result.
-        Returns a new `Measurement` with the resulting value and unit.
+        Parameters:
+            other (Any): Measurement or numeric divisor.
 
-        Raises:
-            TypeError: If dividing two currency measurements with different units, or if the operand is not a `Measurement` or numeric value.
         Returns:
-            Measurement: The result of the division as a new `Measurement` instance.
+            Measurement: Quotient expressed as a measurement.
+
+        Raises:
+            TypeError: If dividing currency amounts with different units or using an unsupported type.
         """
         if isinstance(other, Measurement):
             if self.is_currency() and other.is_currency() and self.unit != other.unit:
@@ -288,32 +339,40 @@ class Measurement:
                 "Division is only allowed with Measurement or numeric values."
             )
 
-    def __str__(self):
+    def __str__(self) -> str:
         """
-        Return a string representation of the measurement, including the unit unless it is dimensionless.
+        Format the measurement as a string, including the unit when present.
+
+        Returns:
+            str: Text representation of the magnitude and unit.
         """
         if not str(self.unit) == "dimensionless":
             return f"{self.magnitude} {self.unit}"
         return f"{self.magnitude}"
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         """
-        Return a string representation of the Measurement instance for debugging, showing its magnitude and unit.
+        Return a detailed representation suitable for debugging.
+
+        Returns:
+            str: Debug-friendly notation including magnitude and unit.
         """
         return f"Measurement({self.magnitude}, '{self.unit}')"
 
     def _compare(self, other: Any, operation: Callable[..., bool]) -> bool:
         """
-        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.
-        
+        Normalise operands into comparable measurements before applying a comparison.
+
         Parameters:
-            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.
-        
+            other (Any): Measurement instance or string representation used for the comparison.
+            operation (Callable[..., bool]): Callable that consumes two magnitudes and returns a comparison result.
+
         Returns:
-            bool: The result of applying the comparison operation to the magnitudes.
+            bool: Outcome of the supplied comparison function.
+
+        Raises:
+            TypeError: If `other` cannot be interpreted as a measurement.
+            ValueError: If the operands use incompatible dimensions.
         """
         if other is None or other in ("", [], (), {}):
             return False
@@ -332,6 +391,15 @@ class Measurement:
             raise ValueError("Cannot compare measurements with different dimensions.")
 
     def __radd__(self, other: Any) -> Measurement:
+        """
+        Support sum() by treating zero as a neutral element.
+
+        Parameters:
+            other (Any): Left operand supplied by Python's arithmetic machinery.
+
+        Returns:
+            Measurement: Either `self` or the result of addition.
+        """
         if other == 0:
             return self
         return self.__add__(other)
@@ -354,16 +422,25 @@ class Measurement:
 
     def __ge__(self, other: Any) -> bool:
         """
-        Return True if this measurement is greater than or equal to another measurement or compatible value.
+        Check whether the measurement is greater than or equal to another value.
+
+        Parameters:
+            other (Any): Measurement or compatible representation used in the comparison.
 
-        The comparison converts the other operand to this measurement's unit before evaluating. Raises TypeError if the operand is not a Measurement or convertible string, or ValueError if units are incompatible.
+        Returns:
+            bool: True when the measurement is greater than or equal to `other`.
+
+        Raises:
+            TypeError: If `other` cannot be interpreted as a measurement.
+            ValueError: If units are incompatible.
         """
         return self._compare(other, ge)
 
     def __hash__(self) -> int:
         """
-        Return a hash based on the measurement's magnitude and unit.
+        Compute a hash using the measurement's magnitude and unit.
 
-        Enables Measurement instances to be used in hash-based collections.
+        Returns:
+            int: Stable hash suitable for use in dictionaries and sets.
         """
         return hash((self.magnitude, str(self.unit)))