GeneralManager 0.14.1__py3-none-any.whl → 0.15.1__py3-none-any.whl

general_manager/utils/filterParser.py

@@ -1,3 +1,5 @@
+"""Utilities for parsing filter keyword arguments into structured callables."""
+
 from __future__ import annotations
 from typing import Any, Callable
 from general_manager.manager.input import Input
@@ -7,20 +9,21 @@ def parse_filters(
     filter_kwargs: dict[str, Any], possible_values: dict[str, Input]
 ) -> dict[str, dict]:
     """
-    Parses filter keyword arguments and constructs filter criteria for input fields.
-    
-    For each filter key-value pair, determines the target field and lookup type, validates the field, and generates either filter keyword arguments or filter functions depending on the field's type. Returns a dictionary mapping field names to filter criteria, supporting both direct lookups and dynamic filter functions.
-    
-    Args:
-        filter_kwargs: Dictionary of filter keys and their corresponding values.
-        possible_values: Mapping of field names to Input definitions used for validation and casting.
-    
+    Parse raw filter keyword arguments into structured criteria for the configured input fields.
+
+    Parameters:
+        filter_kwargs (dict[str, Any]): Filter expressions keyed by `<field>[__lookup]` strings.
+        possible_values (dict[str, Input]): Input definitions that validate, cast, and describe dependencies for each field.
+
     Returns:
-        A dictionary where each key is a field name and each value is a dictionary containing either 'filter_kwargs' for direct lookups or 'filter_funcs' for dynamic filtering.
+        dict[str, dict[str, Any]]: Mapping of input field names to dictionaries containing either `filter_kwargs` or `filter_funcs` entries used when evaluating filters.
+
+    Raises:
+        ValueError: If a filter references an input field that is not defined in `possible_values`.
     """
     from general_manager.manager.generalManager import GeneralManager
 
-    filters = {}
+    filters: dict[str, dict[str, Any]] = {}
     for kwarg, value in filter_kwargs.items():
         parts = kwarg.split("__")
         field_name = parts[0]
@@ -57,16 +60,14 @@ def parse_filters(
 
 def create_filter_function(lookup_str: str, value: Any) -> Callable[[Any], bool]:
     """
-    Creates a filter function based on an attribute path and lookup operation.
-    
-    The returned function checks whether an object's nested attribute(s) satisfy a specified comparison or matching operation against a given value.
-    
-    Args:
-        lookup_str: Attribute path and lookup operation, separated by double underscores (e.g., "age__gte", "name__contains").
-        value: The value to compare against.
-    
+    Build a callable that evaluates whether an object's attribute satisfies a lookup expression.
+
+    Parameters:
+        lookup_str (str): Attribute path and lookup operator separated by double underscores (for example, `age__gte`).
+        value (Any): Reference value used when applying the lookup comparison.
+
     Returns:
-        A function that takes an object and returns True if the object's attribute(s) match the filter condition, otherwise False.
+        Callable[[Any], bool]: Function returning True when the target object's attribute value passes the lookup test.
     """
     parts = lookup_str.split("__") if lookup_str else []
     if parts and parts[-1] in [
@@ -86,7 +87,7 @@ def create_filter_function(lookup_str: str, value: Any) -> Callable[[Any], bool]
         lookup = "exact"
         attr_path = parts
 
-    def filter_func(x):
+    def filter_func(x: object) -> bool:
         for attr in attr_path:
             if hasattr(x, attr):
                 x = getattr(x, attr)
@@ -99,17 +100,15 @@ def create_filter_function(lookup_str: str, value: Any) -> Callable[[Any], bool]
 
 def apply_lookup(value_to_check: Any, lookup: str, filter_value: Any) -> bool:
     """
-    Evaluates whether a value satisfies a specified lookup condition against a filter value.
-    
-    Supports comparison and string operations such as "exact", "lt", "lte", "gt", "gte", "contains", "startswith", "endswith", and "in". Returns False for unsupported lookups or if a TypeError occurs.
-    
-    Args:
-        value_to_check: The value to be compared or checked.
-        lookup: The lookup operation to perform.
-        filter_value: The value to compare against.
-    
+    Evaluate a lookup operation against a candidate value.
+
+    Parameters:
+        value_to_check (Any): Value that will be compared using the lookup expression.
+        lookup (str): Name of the comparison operation (for example, `exact`, `gte`, or `contains`).
+        filter_value (Any): Reference value supplied by the filter expression.
+
     Returns:
-        True if the lookup condition is satisfied; otherwise, False.
+        bool: True if the comparison succeeds; otherwise, False.
     """
     try:
         if lookup == "exact":

general_manager/utils/formatString.py

@@ -1,3 +1,5 @@
+"""Utility helpers for converting between common string casing styles."""
+
 def snake_to_pascal(s: str) -> str:
     """
     Convert a snake_case string to PascalCase.

general_manager/utils/jsonEncoder.py

@@ -1,10 +1,23 @@
+"""Custom JSON encoder capable of rendering GeneralManager objects."""
+
 from datetime import datetime, date, time
 import json
 from general_manager.manager.generalManager import GeneralManager
 
 
 class CustomJSONEncoder(json.JSONEncoder):
-    def default(self, o):
+    """Serialise complex objects that appear within GeneralManager payloads."""
+
+    def default(self, o: object) -> object:
+        """
+        Convert unsupported objects into JSON-friendly representations.
+
+        Parameters:
+            o (Any): Object to encode.
+
+        Returns:
+            Any: JSON-serialisable representation of the object.
+        """
 
         # Serialize datetime objects as ISO strings
         if isinstance(o, (datetime, date, time)):

general_manager/utils/makeCacheKey.py

@@ -1,26 +1,32 @@
+"""Utilities for building deterministic cache keys from function calls."""
+
 import inspect
 import json
-from general_manager.utils.jsonEncoder import CustomJSONEncoder
 from hashlib import sha256
+from typing import Callable, Mapping
 
+from general_manager.utils.jsonEncoder import CustomJSONEncoder
 
-def make_cache_key(func, args, kwargs):
-    """
-    Generates a unique, deterministic cache key for a specific function call.
 
-    The key is derived from the function's module, qualified name, and bound arguments,
-    serialized to JSON and hashed with SHA-256 to ensure uniqueness for each call signature.
+def make_cache_key(
+    func: Callable[..., object],
+    args: tuple[object, ...],
+    kwargs: Mapping[str, object] | None,
+) -> str:
+    """
+    Build a deterministic cache key that uniquely identifies a function invocation.
 
-    Args:
-        func: The target function to be identified.
-        args: Positional arguments for the function call.
-        kwargs: Keyword arguments for the function call.
+    Parameters:
+        func (Callable[..., Any]): The function whose invocation should be cached.
+        args (tuple[Any, ...]): Positional arguments supplied to the function.
+        kwargs (dict[str, Any]): Keyword arguments supplied to the function.
 
     Returns:
-        A hexadecimal SHA-256 hash string uniquely representing the function call.
+        str: Hexadecimal SHA-256 digest representing the call signature.
     """
     sig = inspect.signature(func)
-    bound = sig.bind_partial(*args, **kwargs)
+    kwargs_dict = dict(kwargs or {})
+    bound = sig.bind_partial(*args, **kwargs_dict)
     bound.apply_defaults()
     payload = {
         "module": func.__module__,

general_manager/utils/noneToZero.py

@@ -1,3 +1,5 @@
+"""Convenience helpers for normalising optional numeric inputs."""
+
 from typing import Optional, TypeVar, Literal
 from general_manager.measurement import Measurement
 
@@ -8,13 +10,13 @@ def noneToZero(
     value: Optional[NUMBERVALUE],
 ) -> NUMBERVALUE | Literal[0]:
     """
-    Returns zero if the input is None; otherwise, returns the original value.
-    
-    Args:
-        value: An integer, float, or Measurement, or None.
-    
+    Replace None with zero while preserving existing numeric values.
+
+    Parameters:
+        value (Optional[NUMBERVALUE]): Numeric value or Measurement instance that may be None.
+
     Returns:
-        The original value if not None, otherwise 0.
+        NUMBERVALUE | Literal[0]: The input value if it is not None; otherwise, zero.
     """
     if value is None:
         return 0

general_manager/utils/pathMapping.py

@@ -1,5 +1,7 @@
+"""Utilities for tracing relationships between GeneralManager classes."""
+
 from __future__ import annotations
-from typing import TYPE_CHECKING, cast, get_args
+from typing import TYPE_CHECKING, Any, cast, get_args
 from general_manager.manager.meta import GeneralManagerMeta
 from general_manager.api.property import GraphQLProperty
 
@@ -12,22 +14,36 @@ type PathDestination = str
 
 
 class PathMap:
+    """Maintain cached traversal paths between GeneralManager classes."""
 
     instance: PathMap
     mapping: dict[tuple[PathStart, PathDestination], PathTracer] = {}
 
-    def __new__(cls, *args, **kwargs):
+    def __new__(cls, *args: object, **kwargs: object) -> PathMap:
+        """
+        Create or return the singleton PathMap instance and ensure the path mapping is initialised.
+
+        Parameters:
+            args (tuple): Positional arguments ignored by the constructor.
+            kwargs (dict): Keyword arguments ignored by the constructor.
+
+        Returns:
+            PathMap: The singleton PathMap instance.
+        """
         if not hasattr(cls, "instance"):
             cls.instance = super().__new__(cls)
             cls.createPathMapping()
         return cls.instance
 
     @classmethod
-    def createPathMapping(cls):
+    def createPathMapping(cls) -> None:
         """
-        Builds the mapping of paths between all pairs of distinct managed classes.
+        Populate the path mapping with tracers for every distinct pair of managed classes.
 
-        Iterates over all registered managed classes and creates a PathTracer for each unique start and destination class pair, storing them in the mapping dictionary.
+        The generated tracers capture the attribute sequence needed to navigate from the start class to the destination class and are cached on the singleton instance.
+
+        Returns:
+            None
         """
         all_managed_classes = GeneralManagerMeta.all_classes
         for start_class in all_managed_classes:
@@ -37,19 +53,29 @@ class PathMap:
                         (start_class.__name__, destination_class.__name__)
                     ] = PathTracer(start_class, destination_class)
 
-    def __init__(self, path_start: PathStart | GeneralManager | type[GeneralManager]):
+    def __init__(
+        self,
+        path_start: PathStart | GeneralManager | type[GeneralManager],
+    ) -> None:
         """
-        Initializes a PathMap with a specified starting point.
+        Create a new traversal context rooted at the provided manager class or instance.
+
+        Parameters:
+            path_start (PathStart | GeneralManager | type[GeneralManager]): Name, instance, or class that serves as the origin for future path lookups. The value determines both the stored starting instance and the class metadata used for path resolution.
 
-        The starting point can be a class name (string), a GeneralManager instance, or a GeneralManager subclass. Sets internal attributes for the start instance, class, and class name based on the input.
+        Returns:
+            None
         """
+        self.start_instance: GeneralManager | None
+        self.start_class: type[GeneralManager] | None
+        self.start_class_name: str
         if isinstance(path_start, GeneralManager):
             self.start_instance = path_start
             self.start_class = path_start.__class__
             self.start_class_name = path_start.__class__.__name__
         elif isinstance(path_start, type):
             self.start_instance = None
-            self.start_class = path_start
+            self.start_class = cast(type[GeneralManager], path_start)
             self.start_class_name = path_start.__name__
         else:
             self.start_instance = None
@@ -59,6 +85,15 @@ class PathMap:
     def to(
         self, path_destination: PathDestination | type[GeneralManager] | str
     ) -> PathTracer | None:
+        """
+        Retrieve the cached path tracer from the start class to the desired destination.
+
+        Parameters:
+            path_destination (PathDestination | type[GeneralManager] | str): Target manager identifier, either as a class, instance name, or class name.
+
+        Returns:
+            PathTracer | None: The tracer describing how to traverse to the destination, or None if no path is known.
+        """
         if isinstance(path_destination, type):
             path_destination = path_destination.__name__
 
@@ -70,19 +105,34 @@ class PathMap:
     def goTo(
         self, path_destination: PathDestination | type[GeneralManager] | str
     ) -> GeneralManager | Bucket | None:
+        """
+        Follow the cached path from the starting point to the requested destination.
+
+        Parameters:
+            path_destination (PathDestination | type[GeneralManager] | str): Target manager identifier, either as a class, instance, or class name.
+
+        Returns:
+            GeneralManager | Bucket | None: The resolved manager instance, a bucket of instances, or None when no path exists.
+
+        Raises:
+            ValueError: If no starting instance was supplied when constructing the PathMap.
+        """
         if isinstance(path_destination, type):
             path_destination = path_destination.__name__
 
         tracer = self.mapping.get((self.start_class_name, path_destination), None)
         if not tracer:
             return None
-        if not self.start_instance:
+        if self.start_instance is None:
             raise ValueError("Cannot call goTo on a PathMap without a start instance.")
         return tracer.traversePath(self.start_instance)
 
     def getAllConnected(self) -> set[str]:
         """
-        Returns a list of all classes that are connected to the start class.
+        List the class names that are reachable from the configured starting point.
+
+        Returns:
+            set[str]: Collection of destination class names that have a valid traversal path.
         """
         connected_classes: set[str] = set()
         for path_tuple, path_obj in self.mapping.items():
@@ -95,13 +145,25 @@ class PathMap:
 
 
 class PathTracer:
+    """Resolve attribute paths linking one manager class to another."""
+
     def __init__(
         self, start_class: type[GeneralManager], destination_class: type[GeneralManager]
-    ):
+    ) -> None:
+        """
+        Initialise a path tracer between two manager classes.
+
+        Parameters:
+            start_class (type[GeneralManager]): Origin manager class where traversal begins.
+            destination_class (type[GeneralManager]): Target manager class to reach.
+
+        Returns:
+            None
+        """
         self.start_class = start_class
         self.destination_class = destination_class
         if self.start_class == self.destination_class:
-            self.path = []
+            self.path: list[str] | None = []
         else:
             self.path = self.createPath(start_class, [])
 
@@ -109,14 +171,14 @@ class PathTracer:
         self, current_manager: type[GeneralManager], path: list[str]
     ) -> list[str] | None:
         """
-        Recursively constructs a path of attribute names from the current manager class to the destination class.
+        Recursively compute the traversal path from `current_manager` to the destination class.
 
-        Args:
-            current_manager: The current GeneralManager subclass being inspected.
-            path: The list of attribute names traversed so far.
+        Parameters:
+            current_manager (type[GeneralManager]): Manager class used as the current traversal node.
+            path (list[str]): Sequence of attribute names accumulated along the traversal.
 
         Returns:
-            A list of attribute names representing the path to the destination class, or None if no path exists.
+            list[str] | None: Updated list of attribute names leading to the destination, or None if no route exists.
         """
         current_connections = {
             attr_name: attr_value["type"]
@@ -135,7 +197,7 @@ class PathTracer:
         for attr, attr_type in current_connections.items():
             if attr in path or attr_type == self.start_class:
                 continue
-            if attr_type is None:
+            if attr_type is None or not isinstance(attr_type, type):
                 continue
             if not issubclass(attr_type, GeneralManager):
                 continue
@@ -151,27 +213,28 @@ class PathTracer:
         self, start_instance: GeneralManager | Bucket
     ) -> GeneralManager | Bucket | None:
         """
-        Traverses the stored path from a starting instance to reach the destination instance or bucket.
+        Traverse the stored path starting from the provided manager or bucket instance.
 
-        Args:
-            start_instance: The initial GeneralManager or Bucket instance from which to begin traversal.
+        Parameters:
+            start_instance (GeneralManager | Bucket): Object used as the traversal root.
 
         Returns:
-            The resulting GeneralManager or Bucket instance at the end of the path, or None if the path is empty.
+            GeneralManager | Bucket | None: The resolved destination object, a merged bucket, or None when no traversal is required.
         """
-        current_instance = start_instance
+        current_instance: Any = start_instance
         if not self.path:
             return None
         for attr in self.path:
             if not isinstance(current_instance, Bucket):
                 current_instance = getattr(current_instance, attr)
                 continue
-            new_instance = None
+            new_instance: Any = None
             for entry in current_instance:
-                if not new_instance:
-                    new_instance = getattr(entry, attr)
+                attr_value = getattr(entry, attr)
+                if new_instance is None:
+                    new_instance = attr_value
                 else:
-                    new_instance = new_instance | getattr(entry, attr)
+                    new_instance = new_instance | attr_value  # type: ignore[operator]
             current_instance = new_instance
 
-        return current_instance
+        return cast(GeneralManager | Bucket[Any] | None, current_instance)

general_manager/utils/public_api.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+"""Utility helpers for building lazy-loading public package APIs."""
+
+from importlib import import_module
+from typing import Any, Iterable, Mapping, MutableMapping, overload
+
+ModuleTarget = tuple[str, str]
+ModuleMap = Mapping[str, str | ModuleTarget]
+
+
+@overload
+def _normalize_target(name: str, target: str) -> ModuleTarget: ...
+
+
+@overload
+def _normalize_target(name: str, target: ModuleTarget) -> ModuleTarget: ...
+
+
+def _normalize_target(name: str, target: str | ModuleTarget) -> ModuleTarget:
+    if isinstance(target, tuple):
+        return target
+    return target, name
+
+
+def resolve_export(
+    name: str,
+    *,
+    module_all: Iterable[str],
+    module_map: ModuleMap,
+    module_globals: MutableMapping[str, Any],
+) -> Any:
+    """Resolve a lazily-loaded export for a package __init__ module."""
+    if name not in module_all:
+        raise AttributeError(f"module {module_globals['__name__']!r} has no attribute {name!r}")
+    module_path, attr_name = _normalize_target(name, module_map[name])
+    module = import_module(module_path)
+    value = getattr(module, attr_name)
+    module_globals[name] = value
+    return value
+
+
+def build_module_dir(
+    *,
+    module_all: Iterable[str],
+    module_globals: MutableMapping[str, Any],
+) -> list[str]:
+    """Return a sorted directory listing for a package __init__ module."""
+    return sorted(list(module_globals.keys()) + list(module_all))