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

general_manager/rule/rule.py

@@ -5,16 +5,8 @@ import ast
 import inspect
 import re
 import textwrap
-from typing import (
-    Callable,
-    ClassVar,
-    Dict,
-    Generic,
-    List,
-    Optional,
-    TypeVar,
-    cast,
-)
+from typing import Callable, Dict, Generic, List, Optional, Tuple, TypeVar
+from decimal import Decimal
 
 from django.conf import settings
 from django.utils.module_loading import import_string
@@ -30,6 +22,48 @@ from general_manager.manager.generalManager import GeneralManager
 
 GeneralManagerType = TypeVar("GeneralManagerType", bound=GeneralManager)
 
+NOTEXISTENT = object()
+
+
+class NonexistentAttributeError(AttributeError):
+    """Raised when a referenced attribute does not exist on the GeneralManager instance."""
+
+    def __init__(self, attribute: str) -> None:
+        """
+        Initialize the exception indicating that a referenced attribute does not exist.
+
+        Parameters:
+            attribute (str): The name of the nonexistent attribute; this name will be included in the exception message.
+        """
+        super().__init__(f"The attribute '{attribute}' does not exist.")
+
+
+class MissingErrorTemplateVariableError(ValueError):
+    """Raised when a custom error template omits required variables."""
+
+    def __init__(self, missing: List[str]) -> None:
+        """
+        Initialize the exception indicating that one or more variables referenced by a rule are missing from a custom error template.
+
+        Parameters:
+            missing (List[str]): Names of the variables that are required by the template but were not found; these names will be included in the exception message.
+        """
+        super().__init__(
+            f"The custom error message does not contain all used variables: {missing}."
+        )
+
+
+class ErrorMessageGenerationError(ValueError):
+    """Raised when generating an error message before evaluating any input."""
+
+    def __init__(self) -> None:
+        """
+        Exception raised when no input is available for generating an error message.
+
+        This exception is initialized with the default message "No input provided for error message generation."
+        """
+        super().__init__("No input provided for error message generation.")
+
 
 class Rule(Generic[GeneralManagerType]):
     """
@@ -44,6 +78,9 @@ class Rule(Generic[GeneralManagerType]):
     _ignore_if_none: bool
     _last_result: Optional[bool]
     _last_input: Optional[GeneralManagerType]
+    _last_args: Dict[str, object]
+    _param_names: Tuple[str, ...]
+    _primary_param: Optional[str]
     _tree: ast.AST
     _variables: List[str]
     _handlers: Dict[str, BaseRuleHandler]
@@ -54,11 +91,24 @@ class Rule(Generic[GeneralManagerType]):
         custom_error_message: Optional[str] = None,
         ignore_if_none: bool = True,
     ) -> None:
+        """
+        Initialize a Rule that wraps a predicate function, captures its source AST to discover referenced variables, and prepares handlers for generating error messages.
+
+        Parameters:
+            func (Callable[[GeneralManagerType], bool]): Predicate that evaluates a GeneralManager instance.
+            custom_error_message (Optional[str]): Optional template used to format generated error messages; placeholders must match variables referenced by the predicate.
+            ignore_if_none (bool): If True, evaluation will be skipped (result recorded as None) when any referenced variable resolves to None.
+        """
         self._func = func
         self._custom_error_message = custom_error_message
         self._ignore_if_none = ignore_if_none
         self._last_result = None
         self._last_input = None
+        self._last_args = {}
+
+        parameters = inspect.signature(func).parameters
+        self._param_names = tuple(parameters.keys())
+        self._primary_param = self._param_names[0] if self._param_names else None
 
         # 1) Extract source, strip decorators, and dedent
         src = textwrap.dedent(inspect.getsource(func))
@@ -67,7 +117,7 @@ class Rule(Generic[GeneralManagerType]):
         self._tree = ast.parse(src)
         for parent in ast.walk(self._tree):
             for child in ast.iter_child_nodes(parent):
-                setattr(child, "parent", parent)
+                child.parent = parent  # type: ignore
 
         # 3) Extract referenced variables
         self._variables = self._extract_variables()
@@ -108,15 +158,21 @@ class Rule(Generic[GeneralManagerType]):
 
     def evaluate(self, x: GeneralManagerType) -> Optional[bool]:
         """
-        Execute the predicate against a manager instance and record the result.
+        Evaluate the rule's predicate against a GeneralManager instance and record evaluation context.
+
+        Binds the primary parameter to the provided input, extracts referenced variable values, and sets the last evaluation result to the predicate outcome. If `ignore_if_none` is true and any referenced variable value is `None`, the evaluation is skipped and the last result is set to `None`.
 
         Parameters:
             x (GeneralManagerType): Manager instance supplied to the predicate.
 
         Returns:
-            bool | None: True or False when the predicate executes; None when `ignore_if_none` is set and any referenced value is None.
+            `True` if the predicate evaluates to true, `False` if it evaluates to false, `None` if evaluation was skipped because a referenced value was `None` and `ignore_if_none` is enabled.
         """
         self._last_input = x
+        self._last_args = {}
+        if self._primary_param is not None:
+            self._last_args[self._primary_param] = x
+
         vals = self._extract_variable_values(x)
         if self._ignore_if_none and any(v is None for v in vals.values()):
             self._last_result = None
@@ -127,13 +183,10 @@ class Rule(Generic[GeneralManagerType]):
 
     def validateCustomErrorMessage(self) -> None:
         """
-        Ensure the user-defined template references every extracted variable.
-
-        Returns:
-            None
+        Validate that a provided custom error message template includes placeholders for every variable referenced by the rule.
 
         Raises:
-            ValueError: If the custom error message omits a required placeholder.
+            MissingErrorTemplateVariableError: If one or more extracted variables are not present as `{name}` placeholders in the custom template.
         """
         if not self._custom_error_message:
             return
@@ -141,24 +194,22 @@ class Rule(Generic[GeneralManagerType]):
         vars_in_msg = set(re.findall(r"{([^}]+)}", self._custom_error_message))
         missing = [v for v in self._variables if v not in vars_in_msg]
         if missing:
-            raise ValueError(
-                f"The custom error message does not contain all used variables: {missing}"
-            )
+            raise MissingErrorTemplateVariableError(missing)
 
     def getErrorMessage(self) -> Optional[Dict[str, str]]:
         """
-        Build a mapping of variable names to error messages for the last evaluation.
+        Constructs error messages for the last failed evaluation and returns them keyed by variable name.
 
         Returns:
-            dict[str, str] | None: Mapping describing validation failures, or None when the predicate passed.
+            dict[str, str] | None: Mapping from each referenced variable name to its error message, or `None` if the predicate passed or was not evaluated.
 
         Raises:
-            ValueError: If called before any input has been evaluated.
+            ErrorMessageGenerationError: If called before any input has been evaluated.
         """
         if self._last_result or self._last_result is None:
             return None
         if self._last_input is None:
-            raise ValueError("No input provided for error message generation")
+            raise ErrorMessageGenerationError()
 
         # Validate and substitute template placeholders
         self.validateCustomErrorMessage()
@@ -176,20 +227,48 @@ class Rule(Generic[GeneralManagerType]):
         return errors or None
 
     def _extract_variables(self) -> List[str]:
+        """
+        Collects the dotted attribute names referenced on the rule's parameters.
+
+        Scans the predicate's AST and returns a sorted list of attribute access paths that originate from any of the predicate's parameter names (for example, "user.name" or "order.total"). If the predicate has no parameters, returns an empty list.
+
+        Returns:
+            List[str]: Sorted list of dotted variable names referenced from the predicate's parameters.
+        """
+        param_names = set(self._param_names)
+        if not param_names:
+            return []
+
         class VarVisitor(ast.NodeVisitor):
-            vars: set[str] = set()
+            def __init__(self, params: set[str]) -> None:
+                """
+                Initialize visitor state with a set of parameter names and an empty collection for discovered variables.
+
+                Parameters:
+                    params (set[str]): Names of function parameters to consider when extracting referenced variables.
+                """
+                self.vars: set[str] = set()
+                self.params = params
 
             def visit_Attribute(self, node: ast.Attribute) -> None:
+                """
+                Record dotted attribute accesses that originate from allowed parameter names.
+
+                Visits an ast.Attribute node, collects the dotted name components (e.g., "a.b.c") if the base is an ast.Name present in self.params, and adds the joined name to self.vars. Continues generic traversal after handling the node.
+
+                Parameters:
+                        node (ast.Attribute): The attribute node being visited.
+                """
                 parts: list[str] = []
                 curr: ast.AST = node
                 while isinstance(curr, ast.Attribute):
                     parts.append(curr.attr)
                     curr = curr.value
-                if isinstance(curr, ast.Name) and curr.id == "x":
+                if isinstance(curr, ast.Name) and curr.id in self.params:
                     self.vars.add(".".join(reversed(parts)))
                 self.generic_visit(node)
 
-        visitor = VarVisitor()
+        visitor = VarVisitor(param_names)
         visitor.visit(self._tree)
         return sorted(visitor.vars)
 
@@ -200,15 +279,27 @@ class Rule(Generic[GeneralManagerType]):
         for var in self._variables:
             obj: object = x  # type: ignore
             for part in var.split("."):
-                obj = getattr(obj, part)
+                obj = getattr(obj, part, NOTEXISTENT)
+                if obj is NOTEXISTENT:
+                    raise NonexistentAttributeError(var)
                 if obj is None:
                     break
             out[var] = obj
         return out
 
     def _extract_comparisons(self) -> list[ast.Compare]:
+        """
+        Collect all comparison (ast.Compare) nodes from the predicate AST.
+
+        Searches the rule's parsed AST stored on self._tree and returns every ast.Compare node found in traversal order.
+
+        Returns:
+            comps (list[ast.Compare]): The list of comparison nodes present in the predicate AST.
+        """
+
         class CompVisitor(ast.NodeVisitor):
-            comps: list[ast.Compare] = []
+            def __init__(self) -> None:
+                self.comps: list[ast.Compare] = []
 
             def visit_Compare(self, node: ast.Compare) -> None:
                 self.comps.append(node)
@@ -234,6 +325,17 @@ class Rule(Generic[GeneralManagerType]):
     def _generate_error_messages(
         self, var_values: Dict[str, Optional[object]]
     ) -> Dict[str, str]:
+        """
+        Generate human-readable error messages for each referenced variable using the resolved variable values.
+
+        Given a mapping of variable names to their evaluated values, produce a dictionary mapping each variable to an explanatory error message derived from the rule's predicate. If specialized rule handlers are registered for particular function calls in the predicate, those handlers will be used to produce messages for the affected variables. When the predicate contains boolean combinations and the last evaluation failed, all referenced variables receive a combined invalid-combination message. If no explicit comparisons are present in the predicate, a generic combination-invalid message is returned for every referenced variable.
+
+        Parameters:
+            var_values (Dict[str, Optional[object]]): Mapping from variable names (as extracted from the predicate) to their resolved values for the last-evaluated input.
+
+        Returns:
+            Dict[str, str]: Mapping from variable name to its generated error message.
+        """
         errors: Dict[str, str] = {}
         comparisons = self._extract_comparisons()
         logical = self._contains_logical_ops()
@@ -241,7 +343,7 @@ class Rule(Generic[GeneralManagerType]):
         if comparisons:
             for cmp in comparisons:
                 left, rights, ops = cmp.left, cmp.comparators, cmp.ops
-                for right, op in zip(rights, ops):
+                for right, op in zip(rights, ops, strict=False):
                     # Special handler?
                     if isinstance(left, ast.Call):
                         fn = self._get_node_name(left.func)
@@ -270,7 +372,7 @@ class Rule(Generic[GeneralManagerType]):
                 combo = ", ".join(f"[{v}]" for v in self._variables)
                 msg = f"{combo} combination is not valid"
                 for v in self._variables:
-                    errors[v] = msg
+                    errors.setdefault(v, msg)  # keep specific messages
 
             return errors
 
@@ -295,6 +397,17 @@ class Rule(Generic[GeneralManagerType]):
         }.get(type(op), "?")
 
     def _get_node_name(self, node: ast.AST) -> str:
+        """
+        Produce a concise, human-readable name for the given AST node.
+
+        For attribute access returns the dotted attribute path (e.g., "a.b.c"); for a Name node returns its identifier; for a Call node returns "func(arg1, arg2)" using the same naming rules for subnodes; for Constant nodes or nodes that cannot be represented returns an empty string.
+
+        Parameters:
+            node (ast.AST): The AST node to derive a readable name from.
+
+        Returns:
+            str: The human-readable name or an empty string if no sensible name can be produced.
+        """
         if isinstance(node, ast.Attribute):
             parts: list[str] = []
             curr: ast.AST = node
@@ -313,16 +426,42 @@ class Rule(Generic[GeneralManagerType]):
         try:
             # ast.unparse returns a string representation
             return ast.unparse(node)
-        except Exception:
+        except (AttributeError, ValueError, TypeError):
             return ""
 
     def _eval_node(self, node: ast.expr) -> Optional[object]:
-        """Evaluate an AST expression in the context of the last input."""
+        """
+        Evaluate an AST expression against the Rule's last-evaluated input and bound argument context.
+
+        Parameters:
+            node (ast.expr): The AST expression node to evaluate.
+
+        Returns:
+            result (Optional[object]): The evaluated value of the expression when resolvable; `None` if the node is not an expression or cannot be evaluated in the current context.
+
+        Description:
+            Supported evaluations:
+            - Attribute access: resolves chained attributes from the last input or resolved base value.
+            - Name: returns a bound argument value if present, otherwise looks up the name in the predicate function's global namespace.
+            - Unary negative: evaluates numeric negation for integer, float, or Decimal operands.
+            If the expression cannot be resolved (including missing intermediate attributes or unsupported node kinds), `None` is returned.
+        """
         if not isinstance(node, ast.expr):
             return None
         try:
-            expr = ast.Expression(body=node)
-            code = compile(expr, "<ast>", "eval")
-            return eval(code, {"x": self._last_input}, {})
-        except Exception:
-            return None
+            return ast.literal_eval(node)
+        except (ValueError, TypeError):
+            if isinstance(node, ast.Attribute):
+                base = self._eval_node(node.value)
+                if base is None:
+                    return None
+                return getattr(base, node.attr, None)
+            if isinstance(node, ast.Name):
+                if node.id in self._last_args:
+                    return self._last_args[node.id]
+                return self._func.__globals__.get(node.id)
+            if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub):
+                operand = self._eval_node(node.operand)
+                if isinstance(operand, (int, float, Decimal)):
+                    return -operand
+        return None

general_manager/utils/__init__.py

@@ -12,10 +12,19 @@ __all__ = list(UTILS_EXPORTS)
 _MODULE_MAP = UTILS_EXPORTS
 
 if TYPE_CHECKING:
-    from general_manager._types.utils import *  # noqa: F401,F403
+    from general_manager._types.utils import *  # noqa: F403
 
 
 def __getattr__(name: str) -> Any:
+    """
+    Resolve and return a lazily exported attribute from the module's public API.
+
+    Parameters:
+        name (str): The attribute name being accessed on the module.
+
+    Returns:
+        Any: The resolved export object corresponding to `name` as defined by the module's public API mapping.
+    """
     return resolve_export(
         name,
         module_all=__all__,

general_manager/utils/argsToKwargs.py

@@ -1,32 +1,57 @@
 from typing import Iterable, Mapping
 
 
+class TooManyArgumentsError(TypeError):
+    """Raised when more positional arguments are supplied than available keys."""
+
+    def __init__(self) -> None:
+        """
+        Initialize the TooManyArgumentsError instance.
+
+        Sets the exception message to "More positional arguments than keys provided."
+        """
+        super().__init__("More positional arguments than keys provided.")
+
+
+class ConflictingKeywordError(TypeError):
+    """Raised when generated keyword arguments conflict with existing kwargs."""
+
+    def __init__(self) -> None:
+        """
+        Initialize ConflictingKeywordError with the standard message "Conflicts in existing kwargs."
+        """
+        super().__init__("Conflicts in existing kwargs.")
+
+
 def args_to_kwargs(
     args: tuple[object, ...],
     keys: Iterable[str],
     existing_kwargs: Mapping[str, object] | None = None,
 ) -> dict[str, object]:
     """
-    Convert positional arguments to keyword arguments and merge them into an existing mapping.
+    Map positional arguments to the given keys and merge the result with an optional existing kwargs mapping.
 
     Parameters:
-        args (tuple[Any, ...]): Positional arguments that should be mapped to keyword arguments.
-        keys (Iterable[Any]): Keys used to map each positional argument within `args`.
-        existing_kwargs (dict | None): Optional keyword argument mapping to merge with the generated values.
+        args (tuple[object, ...]): Positional values to assign to keys in order.
+        keys (Iterable[str]): Keys to assign the positional values to.
+        existing_kwargs (Mapping[str, object] | None): Optional mapping of keyword arguments to merge into the result.
 
     Returns:
-        dict[Any, Any]: A dictionary containing the merged keyword arguments.
+        dict[str, object]: A dictionary containing the mapped keys for the provided positional arguments plus all entries from `existing_kwargs` (if given).
 
     Raises:
-        TypeError: If the number of positional arguments exceeds the number of provided keys, or if any generated keyword collides with `existing_kwargs`.
+        TooManyArgumentsError: If more positional arguments are provided than keys.
+        ConflictingKeywordError: If `existing_kwargs` contains a key that was already produced from `args` and `keys`.
     """
     keys = list(keys)
     if len(args) > len(keys):
-        raise TypeError("More positional arguments than keys provided.")
+        raise TooManyArgumentsError()
 
-    kwargs: dict[str, object] = {key: value for key, value in zip(keys, args)}
+    kwargs: dict[str, object] = {
+        key: value for key, value in zip(keys, args, strict=False)
+    }
     if existing_kwargs and any(key in kwargs for key in existing_kwargs):
-        raise TypeError("Conflicts in existing kwargs.")
+        raise ConflictingKeywordError()
     if existing_kwargs:
         kwargs.update(existing_kwargs)
 

general_manager/utils/filterParser.py

@@ -5,21 +5,36 @@ from typing import Any, Callable
 from general_manager.manager.input import Input
 
 
+class UnknownInputFieldError(ValueError):
+    """Raised when a filter references an unknown input field."""
+
+    def __init__(self, field_name: str) -> None:
+        """
+        Initialize the UnknownInputFieldError with a message indicating which input field was not recognized.
+
+        Parameters:
+            field_name (str): Name of the input field referenced in the filter that is not defined.
+        """
+        super().__init__(f"Unknown input field '{field_name}' in filter.")
+
+
 def parse_filters(
     filter_kwargs: dict[str, Any], possible_values: dict[str, Input]
 ) -> dict[str, dict]:
     """
-    Parse raw filter keyword arguments into structured criteria for the configured input fields.
+    Parse raw filter keyword arguments into structured criteria aligned with 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.
+        filter_kwargs (dict[str, Any]): Mapping of filter expressions keyed by "<field>[__lookup]".
+        possible_values (dict[str, Input]): Mapping of field names to Input definitions used for casting and type information.
 
     Returns:
-        dict[str, dict[str, Any]]: Mapping of input field names to dictionaries containing either `filter_kwargs` or `filter_funcs` entries used when evaluating filters.
+        dict[str, dict]: Mapping from input field name to a dictionary containing either:
+            - "filter_kwargs": dict of lookup names to values for bucket (GeneralManager) fields, or
+            - "filter_funcs": list of callables that evaluate non-bucket field conditions.
 
     Raises:
-        ValueError: If a filter references an input field that is not defined in `possible_values`.
+        UnknownInputFieldError: If a filter references a field name not present in `possible_values`.
     """
     from general_manager.manager.generalManager import GeneralManager
 
@@ -28,7 +43,7 @@ def parse_filters(
         parts = kwarg.split("__")
         field_name = parts[0]
         if field_name not in possible_values:
-            raise ValueError(f"Unknown input field '{field_name}' in filter")
+            raise UnknownInputFieldError(field_name)
         input_field = possible_values[field_name]
 
         lookup = "__".join(parts[1:]) if len(parts) > 1 else ""
@@ -131,5 +146,5 @@ def apply_lookup(value_to_check: Any, lookup: str, filter_value: Any) -> bool:
             return value_to_check in filter_value
         else:
             return False
-    except TypeError as e:
+    except TypeError:
         return False

general_manager/utils/formatString.py

@@ -1,5 +1,6 @@
 """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/pathMapping.py

@@ -1,7 +1,7 @@
 """Utilities for tracing relationships between GeneralManager classes."""
 
 from __future__ import annotations
-from typing import TYPE_CHECKING, Any, cast, get_args
+from typing import TYPE_CHECKING, Any, ClassVar, cast, get_args
 from general_manager.manager.meta import GeneralManagerMeta
 from general_manager.api.property import GraphQLProperty
 
@@ -13,19 +13,27 @@ type PathStart = str
 type PathDestination = str
 
 
+class MissingStartInstanceError(ValueError):
+    """Raised when attempting to traverse a path without a starting instance."""
+
+    def __init__(self) -> None:
+        """
+        Create the MissingStartInstanceError with its default message.
+
+        This initializer constructs the exception with the message: "Cannot call goTo on a PathMap without a start instance."
+        """
+        super().__init__("Cannot call goTo on a PathMap without a start instance.")
+
+
 class PathMap:
     """Maintain cached traversal paths between GeneralManager classes."""
 
     instance: PathMap
-    mapping: dict[tuple[PathStart, PathDestination], PathTracer] = {}
+    mapping: ClassVar[dict[tuple[PathStart, PathDestination], PathTracer]] = {}
 
-    def __new__(cls, *args: object, **kwargs: object) -> PathMap:
+    def __new__(cls, *args: Any, **kwargs: Any) -> 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.
+        Obtain the singleton PathMap, initializing the path mapping on first instantiation.
 
         Returns:
             PathMap: The singleton PathMap instance.
@@ -106,16 +114,16 @@ class PathMap:
         self, path_destination: PathDestination | type[GeneralManager] | str
     ) -> GeneralManager | Bucket | None:
         """
-        Follow the cached path from the starting point to the requested destination.
+        Traverse the cached path from the configured start to the given destination.
 
         Parameters:
-            path_destination (PathDestination | type[GeneralManager] | str): Target manager identifier, either as a class, instance, or class name.
+            path_destination (PathDestination | type[GeneralManager] | str): Destination specified as a GeneralManager class, a destination name, or a PathDestination identifier.
 
         Returns:
-            GeneralManager | Bucket | None: The resolved manager instance, a bucket of instances, or None when no path exists.
+            GeneralManager | Bucket | None: The resolved GeneralManager instance, a Bucket of instances reached by the path, or `None` if no cached path exists.
 
         Raises:
-            ValueError: If no starting instance was supplied when constructing the PathMap.
+            MissingStartInstanceError: If the cached path requires a concrete start instance but the PathMap was constructed without one.
         """
         if isinstance(path_destination, type):
             path_destination = path_destination.__name__
@@ -124,15 +132,15 @@ class PathMap:
         if not tracer:
             return None
         if self.start_instance is None:
-            raise ValueError("Cannot call goTo on a PathMap without a start instance.")
+            raise MissingStartInstanceError()
         return tracer.traversePath(self.start_instance)
 
     def getAllConnected(self) -> set[str]:
         """
-        List the class names that are reachable from the configured starting point.
+        Return the set of destination class names that are reachable from the configured start.
 
         Returns:
-            set[str]: Collection of destination class names that have a valid traversal path.
+            set[str]: Destination class names reachable from the current start_class_name.
         """
         connected_classes: set[str] = set()
         for path_tuple, path_obj in self.mapping.items():

general_manager/utils/public_api.py

@@ -5,6 +5,23 @@ from __future__ import annotations
 from importlib import import_module
 from typing import Any, Iterable, Mapping, MutableMapping, overload
 
+
+class MissingExportError(AttributeError):
+    """Raised when a requested export is not defined in the public API."""
+
+    def __init__(self, module_name: str, attribute: str) -> None:
+        """
+        Initialize the MissingExportError with the originating module name and the missing attribute.
+
+        Constructs the exception message "module 'module_name' has no attribute 'attribute'".
+
+        Parameters:
+            module_name (str): Name of the module where the attribute was expected.
+            attribute (str): Name of the missing attribute.
+        """
+        super().__init__(f"module {module_name!r} has no attribute {attribute!r}")
+
+
 ModuleTarget = tuple[str, str]
 ModuleMap = Mapping[str, str | ModuleTarget]
 
@@ -30,9 +47,23 @@ def resolve_export(
     module_map: ModuleMap,
     module_globals: MutableMapping[str, Any],
 ) -> Any:
-    """Resolve a lazily-loaded export for a package __init__ module."""
+    """
+    Resolve and cache a lazily-loaded export for a package __init__ module.
+
+    Parameters:
+        name (str): The public export name to resolve.
+        module_all (Iterable[str]): Iterable of names declared in the module's __all__; used to validate that `name` is an allowed export.
+        module_map (ModuleMap): Mapping from public export names to target module paths or (module path, attribute) pairs used to locate the actual object.
+        module_globals (MutableMapping[str, Any]): The module's globals dict; the resolved value will be stored here under `name`.
+
+    Returns:
+        Any: The resolved attribute value for `name`.
+
+    Raises:
+        MissingExportError: If `name` is not present in `module_all`.
+    """
     if name not in module_all:
-        raise AttributeError(f"module {module_globals['__name__']!r} has no attribute {name!r}")
+        raise MissingExportError(module_globals["__name__"], name)
     module_path, attr_name = _normalize_target(name, module_map[name])
     module = import_module(module_path)
     value = getattr(module, attr_name)