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

general_manager/cache/dependencyIndex.py

@@ -5,6 +5,7 @@ import time
 import ast
 import re
 import logging
+from datetime import date, datetime
 
 from django.core.cache import cache
 from general_manager.cache.signals import post_data_change, pre_data_change
@@ -32,6 +33,22 @@ type Dependency = Tuple[general_manager_name, filter_type, str]
 
 logger = logging.getLogger(__name__)
 
+
+class DependencyLockTimeoutError(TimeoutError):
+    """Raised when the dependency index lock cannot be acquired within the timeout."""
+
+    def __init__(self, operation: str) -> None:
+        """
+        Error raised when acquiring the dependency index lock times out.
+
+        Parameters:
+            operation (str): Name or description of the operation during which lock acquisition timed out.
+        """
+        super().__init__(
+            f"Timed out acquiring dependency index lock during {operation}."
+        )
+
+
 # -----------------------------------------------------------------------------
 # CONFIG
 # -----------------------------------------------------------------------------
@@ -39,6 +56,7 @@ INDEX_KEY = "dependency_index"  # Cache key storing the complete dependency inde
 LOCK_KEY = "dependency_index_lock"  # Cache key used for the dependency lock
 LOCK_TIMEOUT = 5  # Lock TTL in seconds
 UNDEFINED = object()  # Sentinel for undefined values
+ACTIONS: tuple[Literal["filter"], Literal["exclude"]] = ("filter", "exclude")
 
 
 # -----------------------------------------------------------------------------
@@ -112,23 +130,22 @@ def record_dependencies(
     ],
 ) -> None:
     """
-    Register cache keys against the filters and exclusions they depend on.
+    Register a cache key as dependent on the given manager-level filters, exclusions, or identifications.
 
     Parameters:
-        cache_key (str): Cache key produced for the cached queryset.
+        cache_key (str): The cache key to associate with the declared dependencies.
         dependencies (Iterable[tuple[str, Literal["filter", "exclude", "identification"], str]]):
-            Collection describing manager name, dependency type, and identifying data.
-
-    Returns:
-        None
+            Iterable of tuples describing each dependency as (manager_name, action, identifier).
+            - For `filter` and `exclude`, `identifier` is a string representation of a mapping of lookups to values.
+            - For `identification`, `identifier` is the identifying value (treated as a lookup on `id`).
 
     Raises:
-        TimeoutError: If the dependency lock cannot be acquired within `LOCK_TIMEOUT`.
+        DependencyLockTimeoutError: If a lock cannot be acquired within the configured timeout while updating the index.
     """
     start = time.time()
     while not acquire_lock():
         if time.time() - start > LOCK_TIMEOUT:
-            raise TimeoutError("Could not aquire lock for record_dependencies")
+            raise DependencyLockTimeoutError("record_dependencies")
         time.sleep(0.05)
 
     try:
@@ -138,6 +155,11 @@ def record_dependencies(
                 action_key = cast(Literal["filter", "exclude"], action)
                 params = ast.literal_eval(identifier)
                 section = idx[action_key].setdefault(model_name, {})
+                if len(params) > 1:
+                    cache_dependencies = section.setdefault(
+                        "__cache_dependencies__", {}
+                    )
+                    cache_dependencies.setdefault(cache_key, set()).add(identifier)
                 for lookup, val in params.items():
                     lookup_map = section.setdefault(lookup, {})
                     val_key = repr(val)
@@ -161,29 +183,31 @@ def record_dependencies(
 # -----------------------------------------------------------------------------
 def remove_cache_key_from_index(cache_key: str) -> None:
     """
-    Remove a cache entry from all dependency mappings.
+    Remove a cache key from all dependency mappings in the stored dependency index.
 
-    Parameters:
-        cache_key (str): Cache key that should be expunged from the index.
+    Acquires the dependency lock to update and persist the index; if the lock cannot be obtained within LOCK_TIMEOUT the operation fails.
 
-    Returns:
-        None
+    Parameters:
+        cache_key (str): The cache key to expunge from all recorded filter, exclude, and identification mappings.
 
     Raises:
-        TimeoutError: If the dependency lock cannot be acquired within `LOCK_TIMEOUT`.
+        DependencyLockTimeoutError: If the dependency lock cannot be acquired within LOCK_TIMEOUT.
     """
     start = time.time()
     while not acquire_lock():
         if time.time() - start > LOCK_TIMEOUT:
-            raise TimeoutError("Could not aquire lock for remove_cache_key_from_index")
+            raise DependencyLockTimeoutError("remove_cache_key_from_index")
         time.sleep(0.05)
 
     try:
         idx = get_full_index()
-        for action in ("filter", "exclude"):
-            action_section = idx.get(action, {})
+        for action in ACTIONS:
+            action_section = idx[action]
             for mname, model_section in list(action_section.items()):
+                cache_dependencies = model_section.get("__cache_dependencies__", {})
                 for lookup, lookup_map in list(model_section.items()):
+                    if lookup.startswith("__"):
+                        continue
                     for val_key, key_set in list(lookup_map.items()):
                         if cache_key in key_set:
                             key_set.remove(cache_key)
@@ -191,6 +215,10 @@ def remove_cache_key_from_index(cache_key: str) -> None:
                                 del lookup_map[val_key]
                     if not lookup_map:
                         del model_section[lookup]
+                if cache_dependencies:
+                    cache_dependencies.pop(cache_key, None)
+                    if not cache_dependencies:
+                        model_section.pop("__cache_dependencies__", None)
                 if not model_section:
                     del action_section[mname]
         set_full_index(idx)
@@ -221,15 +249,10 @@ def capture_old_values(
     **kwargs: object,
 ) -> None:
     """
-    Cache the field values referenced by tracked filters before an update.
+    Record the current values of fields referenced by tracked filters on the given manager instance before it changes.
 
     Parameters:
-        sender (type[GeneralManager]): Manager class dispatching the signal.
-        instance (GeneralManager | None): Manager instance about to change.
-        **kwargs: Additional signal metadata.
-
-    Returns:
-        None
+        instance (GeneralManager | None): Manager instance about to change; if provided, this function sets instance._old_values to a mapping of lookup keys to their current values for use by post-change invalidation logic.
     """
     if instance is None:
         return
@@ -237,8 +260,16 @@ def capture_old_values(
     idx = get_full_index()
     # get all lookups for this model
     lookups = set()
-    for action in ("filter", "exclude"):
-        lookups |= set(idx.get(action, {}).get(manager_name, {}))
+    for action in ACTIONS:
+        model_section = idx[action].get(manager_name)
+        if isinstance(model_section, dict):
+            lookups |= {
+                lookup
+                for lookup in model_section.keys()
+                if isinstance(lookup, str) and not lookup.startswith("__")
+            }
+        elif isinstance(model_section, list):
+            lookups |= set(model_section)
     if lookups and instance.identification:
         # save old values for later comparison
         vals: dict[str, object] = {}
@@ -251,7 +282,7 @@ def capture_old_values(
                     break
                 current = getattr(current, attr, None)
             vals[lookup] = current
-        setattr(instance, "_old_values", vals)
+        instance._old_values = vals
 
 
 @receiver(post_data_change)
@@ -262,41 +293,150 @@ def generic_cache_invalidation(
     **kwargs: object,
 ) -> None:
     """
-    Invalidate cached query results affected by a data change.
+    Invalidate cache entries whose recorded dependencies are affected by changes to a GeneralManager instance.
 
-    Parameters:
-        sender (type[GeneralManager]): Manager class that triggered the signal.
-        instance (GeneralManager): Updated manager instance.
-        old_relevant_values (dict[str, Any]): Previously captured values for tracked lookups.
-        **kwargs: Additional signal metadata.
+    Uses the dependency index to compare previously captured values against the instance's current values for tracked lookups, evaluates both simple and composite dependency conditions for "filter" and "exclude" actions, and for any dependency that warrants invalidation it deletes the corresponding cache entry and removes its references from the index.
 
-    Returns:
-        None
+    Parameters:
+        sender (type[GeneralManager]): Manager class that emitted the signal.
+        instance (GeneralManager): The manager instance that was changed.
+        old_relevant_values (dict[str, Any]): Mapping of lookup paths (joined by "__") to their values as captured before the change; used to compare old vs. new values for invalidation decisions.
     """
     manager_name = sender.__name__
     idx = get_full_index()
 
+    def _safe_literal_eval(value: Any) -> Any:
+        if isinstance(value, str):
+            try:
+                return ast.literal_eval(value)
+            except (ValueError, SyntaxError):
+                return value
+        return value
+
+    def _coerce_to_type(sample: Any, raw: Any) -> Any | None:
+        """
+        Coerces a raw value to match the type and semantics of a sample value.
+
+        Attempts to convert `raw` into the same type as `sample`. Handles:
+        - datetimes: parses ISO-like strings, preserves or aligns timezone info with `sample`,
+        - dates: parses ISO date strings,
+        - booleans: recognizes common textual and numeric boolean representations,
+        - other types: attempts to call the sample's type on `raw`.
+
+        Parameters:
+            sample: A value whose type and semantics should be used as the target.
+            raw: The input value to coerce.
+
+        Returns:
+            The coerced value of the same type as `sample`, or `None` if `raw` cannot be sensibly converted.
+        """
+        if sample is None:
+            return None
+
+        if isinstance(sample, datetime):
+            if isinstance(raw, datetime):
+                parsed = raw
+            elif isinstance(raw, str):
+                candidate = raw.replace("Z", "+00:00")
+                candidate = candidate.replace(" ", "T", 1)
+                try:
+                    parsed = datetime.fromisoformat(candidate)
+                except ValueError:
+                    return None
+            else:
+                return None
+
+            if sample.tzinfo and parsed.tzinfo is None:
+                parsed = parsed.replace(tzinfo=sample.tzinfo)
+            elif not sample.tzinfo and parsed.tzinfo is not None:
+                parsed = parsed.replace(tzinfo=None)
+            return parsed
+
+        if isinstance(sample, date) and not isinstance(sample, datetime):
+            if isinstance(raw, date) and not isinstance(raw, datetime):
+                return raw
+            if isinstance(raw, str):
+                try:
+                    return date.fromisoformat(raw)
+                except ValueError:
+                    return None
+            return None
+
+        # Booleans: avoid bool("False") == True
+        if isinstance(sample, bool):
+            if isinstance(raw, bool):
+                return raw
+            if isinstance(raw, (int,)):
+                return bool(raw)
+            if isinstance(raw, str):
+                s = raw.strip().lower()
+                if s in {"true", "1", "yes", "y", "t"}:
+                    return True
+                if s in {"false", "0", "no", "n", "f"}:
+                    return False
+            return None
+        try:
+            return type(sample)(raw)  # type: ignore
+        except (TypeError, ValueError):
+            if isinstance(raw, type(sample)):
+                return raw
+            return None
+
     def matches(op: str, value: Any, val_key: Any) -> bool:
+        """
+        Evaluate whether a given value satisfies a lookup operation described by `op` and `val_key`.
+
+        Supports operators:
+        - "eq": equality; attempts to interpret `val_key` as a literal and coerce it to `value`'s type before comparing.
+        - "in": membership; expects `val_key` to be a literal iterable and checks if any coerced element equals `value`.
+        - "gt", "gte", "lt", "lte": numeric/date comparisons; `val_key` is interpreted as a literal and coerced to `value`'s type.
+        - "contains", "startswith", "endswith": string containment/prefix/suffix checks; both sides are compared as strings.
+        - "regex": treats `val_key` as a regular expression pattern and tests it against the string form of `value`.
+
+        Behavior notes:
+        - If `value` is None the function returns `False`.
+        - Literal parsing of `val_key` is attempted via AST literal evaluation; if parsing or coercion fails, the function falls back to conservative comparisons or returns `False` where appropriate.
+        - Regex patterns that fail to compile are treated as non-matching.
+
+        Parameters:
+            op (str): The lookup operator name (one of the supported operators above).
+            value (Any): The runtime value to test.
+            val_key (Any): The stored comparison key (often a string representation) to interpret for the comparison.
+
+        Returns:
+            bool: `True` if the comparison defined by `op` and `val_key` matches `value`, `False` otherwise.
+        """
         if value is None:
             return False
 
         # eq
         if op == "eq":
-            return repr(value) == val_key
+            literal_val = _safe_literal_eval(val_key)
+            comparable = _coerce_to_type(value, literal_val)
+            if comparable is None:
+                return repr(value) == val_key
+            return value == comparable
 
         # in
         if op == "in":
             try:
                 seq = ast.literal_eval(val_key)
-                return value in seq
-            except:
+            except (ValueError, SyntaxError):
                 return False
+            for item in seq:
+                comparable = _coerce_to_type(value, item)
+                if comparable is not None:
+                    if value == comparable:
+                        return True
+                elif repr(value) == repr(item):
+                    return True
+            return False
 
         # range comparisons
         if op in ("gt", "gte", "lt", "lte"):
-            try:
-                thr = type(value)(ast.literal_eval(val_key))
-            except:
+            literal_val = _safe_literal_eval(val_key)
+            thr = _coerce_to_type(value, literal_val)
+            if thr is None:
                 return False
             if op == "gt":
                 return value > thr
@@ -311,7 +451,7 @@ def generic_cache_invalidation(
         if op in ("contains", "startswith", "endswith", "regex"):
             try:
                 literal = ast.literal_eval(val_key)
-            except Exception:
+            except (ValueError, SyntaxError):
                 literal = val_key
 
             # ensure we always work with strings to avoid TypeErrors
@@ -325,16 +465,110 @@ def generic_cache_invalidation(
             # regex: treat the stored key as the regex pattern
             if op == "regex":
                 try:
-                    pattern = re.compile(val_key)
+                    pattern_source = (
+                        literal if isinstance(literal, str) else str(literal)
+                    )
+                    pattern = re.compile(pattern_source)
                 except re.error:
                     return False
                 return bool(pattern.search(text))
 
         return False
 
-    for action in ("filter", "exclude"):
-        model_section = idx.get(action, {}).get(manager_name, {})
+    def current_value_for_path(path: list[str]) -> Any:
+        """
+        Fetches the current value from the captured `instance` by following a sequence of attribute names.
+
+        Parameters:
+            path (list[str]): Ordered attribute names to traverse on the instance (e.g., ["user", "profile", "email"]).
+
+        Returns:
+            The value found at the end of the attribute path, or `None` if any attribute along the path is missing.
+        """
+        current: object = instance
+        for attr in path:
+            current = getattr(current, attr, UNDEFINED)
+            if current is UNDEFINED:
+                return None
+        return current
+
+    def evaluate_composite(
+        cache_key: str,
+        lookup_key: str,
+        action: Literal["filter", "exclude"],
+        model_section: dict[str, dict[str, set[str]]],
+    ) -> bool | None:
+        """
+        Determine whether a composite dependency (multiple lookup params grouped under a single identifier)
+        for a given cache key and lookup should cause cache invalidation.
+
+        Parameters:
+            cache_key (str): The cache key being evaluated.
+            lookup_key (str): The specific lookup (operator and attribute path joined by `"__"`) that prompted evaluation.
+            action (Literal["filter", "exclude"]): The dependency action context; "filter" treats a match as cause for invalidation,
+                "exclude" treats a change in match membership as cause for invalidation.
+            model_section (dict[str, dict[str, set[str]]]): The index section for the model containing lookup maps and an
+                optional "__cache_dependencies__" mapping from cache keys to sets of identifier strings (each identifier
+                encodes multiple lookup parameters).
+
+        Returns:
+            bool | None: `True` if the composite dependency indicates the cache entry should be invalidated,
+            `False` if it indicates no invalidation is required, or `None` if there are no composite identifiers
+            registered for `cache_key`.
+        """
+        cache_dependencies = model_section.get("__cache_dependencies__", {})
+        identifiers = cache_dependencies.get(cache_key) if cache_dependencies else None
+        if not identifiers:
+            return None
+
+        for identifier in identifiers:
+            params = ast.literal_eval(identifier)
+            if lookup_key not in params:
+                continue
+            old_all = True
+            new_all = True
+            for param_lookup, expected in params.items():
+                parts_param = param_lookup.split("__")
+                if parts_param[-1] in (
+                    "gt",
+                    "gte",
+                    "lt",
+                    "lte",
+                    "in",
+                    "contains",
+                    "startswith",
+                    "endswith",
+                    "regex",
+                ):
+                    op_param = parts_param[-1]
+                    attr_path_param = parts_param[:-1]
+                else:
+                    op_param = "eq"
+                    attr_path_param = parts_param
+                expected_key = repr(expected)
+                old_val_param = old_relevant_values.get("__".join(attr_path_param))
+                new_val_param = current_value_for_path(attr_path_param)
+                if not matches(op_param, old_val_param, expected_key):
+                    old_all = False
+                if not matches(op_param, new_val_param, expected_key):
+                    new_all = False
+                if not old_all and not new_all and action == "filter":
+                    break
+            if action == "filter":
+                if old_all or new_all:
+                    return True
+            else:  # exclude
+                if old_all != new_all:
+                    return True
+        return False
+
+    for action in ACTIONS:
+        model_section = idx[action].get(manager_name)
+        if not isinstance(model_section, dict):
+            continue
         for lookup, lookup_map in model_section.items():
+            if lookup.startswith("__"):
+                continue
             # 1) get operator and attribute path
             parts = lookup.split("__")
             if parts[-1] in (
@@ -371,20 +605,36 @@ def generic_cache_invalidation(
 
                 if action == "filter":
                     # Filter: invalidate if new match or old match
-                    if new_match or old_match:
-                        logger.info(
-                            f"Invalidate cache key {cache_keys} for filter {lookup} with value {val_key}"
+                    for ck in list(cache_keys):
+                        composite_decision = evaluate_composite(
+                            ck, lookup, action, model_section
                         )
-                        for ck in list(cache_keys):
+                        should_invalidate = (
+                            composite_decision
+                            if composite_decision is not None
+                            else (new_match or old_match)
+                        )
+                        if should_invalidate:
+                            logger.info(
+                                f"Invalidate cache key {ck} for filter {lookup} with value {val_key}"
+                            )
                             invalidate_cache_key(ck)
                             remove_cache_key_from_index(ck)
 
                 else:  # action == 'exclude'
                     # Excludes: invalidate only if matches changed
-                    if old_match != new_match:
-                        logger.info(
-                            f"Invalidate cache key {cache_keys} for exclude {lookup} with value {val_key}"
+                    for ck in list(cache_keys):
+                        composite_decision = evaluate_composite(
+                            ck, lookup, action, model_section
+                        )
+                        should_invalidate = (
+                            composite_decision
+                            if composite_decision is not None
+                            else (old_match != new_match)
                         )
-                        for ck in list(cache_keys):
+                        if should_invalidate:
+                            logger.info(
+                                f"Invalidate cache key {ck} for exclude {lookup} with value {val_key}"
+                            )
                             invalidate_cache_key(ck)
                             remove_cache_key_from_index(ck)

general_manager/cache/signals.py

@@ -27,14 +27,16 @@ def dataChange(func: Callable[P, R]) -> Callable[P, R]:
     @wraps(func)
     def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
         """
-        Execute the wrapped function while emitting data change signals.
+        Emit pre_data_change and post_data_change signals around the wrapped function call.
+
+        Emits a pre_data_change signal before invoking the wrapped function and a post_data_change signal afterwards. Signals are sent with `sender`, `instance`, and `action`; the post-change signal also includes `old_relevant_values`. After signaling, the wrapper removes the `_old_values` attribute from the pre-change instance if it exists.
 
         Parameters:
             *args: Positional arguments forwarded to the wrapped function.
             **kwargs: Keyword arguments forwarded to the wrapped function.
 
         Returns:
-            R: Result produced by the wrapped function.
+            R: The result returned by the wrapped function.
         """
         action = func.__name__
         if func.__name__ == "create":
@@ -66,6 +68,11 @@ def dataChange(func: Callable[P, R]) -> Callable[P, R]:
             old_relevant_values=old_relevant_values,
             **kwargs,
         )
+        if instance_before is not None:
+            try:
+                delattr(instance_before, "_old_values")
+            except AttributeError:
+                pass
         return result
 
     return wrapper

general_manager/factory/__init__.py

@@ -12,10 +12,19 @@ __all__ = list(FACTORY_EXPORTS)
 _MODULE_MAP = FACTORY_EXPORTS
 
 if TYPE_CHECKING:
-    from general_manager._types.factory import *  # noqa: F401,F403
+    from general_manager._types.factory import *  # noqa: F403
 
 
 def __getattr__(name: str) -> Any:
+    """
+    Dynamically resolve and return a named export from this module.
+
+    Parameters:
+        name (str): The attribute name to resolve.
+
+    Returns:
+        Any: The resolved attribute object corresponding to `name`.
+    """
     return resolve_export(
         name,
         module_all=__all__,

general_manager/factory/autoFactory.py

@@ -15,6 +15,40 @@ if TYPE_CHECKING:
 modelsModel = TypeVar("modelsModel", bound=models.Model)
 
 
+class InvalidGeneratedObjectError(TypeError):
+    """Raised when factory generation produces non-model instances."""
+
+    def __init__(self) -> None:
+        """
+        Initialize the exception indicating a generated object is not a Django model instance.
+
+        Sets a default error message explaining that the generated object is not a Django model instance.
+        """
+        super().__init__("Generated object is not a Django model instance.")
+
+
+class InvalidAutoFactoryModelError(TypeError):
+    """Raised when the factory metadata does not reference a Django model class."""
+
+    def __init__(self) -> None:
+        """
+        Raised when an AutoFactory target model is not a Django model class.
+
+        The exception carries a default message explaining that `_meta.model` must be a Django model class.
+        """
+        super().__init__("AutoFactory requires _meta.model to be a Django model class.")
+
+
+class UndefinedAdjustmentMethodError(ValueError):
+    """Raised when an adjustment method is required but not configured."""
+
+    def __init__(self) -> None:
+        """
+        Initialize the UndefinedAdjustmentMethodError with the default message indicating that a generate/adjustment function is not configured.
+        """
+        super().__init__("_adjustmentMethod is not defined.")
+
+
 class AutoFactory(DjangoModelFactory[modelsModel]):
     """Factory that auto-populates model fields based on interface metadata."""
 
@@ -28,18 +62,26 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         cls, strategy: Literal["build", "create"], params: dict[str, Any]
     ) -> models.Model | list[models.Model]:
         """
-        Generate and populate model instances with automatically derived field values.
+        Generate and populate model instances using automatically derived field values.
 
         Parameters:
-            strategy (Literal["build", "create"]): Whether to persist the generated instances.
-            params (dict[str, Any]): Field values supplied by the caller.
+            strategy (Literal["build", "create"]): Either "build" (unsaved instance) or "create" (saved instance).
+            params (dict[str, Any]): Field values supplied by the caller; any missing non-auto fields will be populated automatically.
 
         Returns:
-            models.Model | list[models.Model]: Generated instance(s) matching the requested strategy.
+            models.Model | list[models.Model]: A generated model instance or a list of generated model instances.
+
+        Raises:
+            InvalidAutoFactoryModelError: If the factory target `_meta.model` is not a Django model class.
+            InvalidGeneratedObjectError: If an element of a generated list is not a Django model instance.
         """
         model = cls._meta.model
-        if not issubclass(model, models.Model):
-            raise ValueError("Model must be a type")
+        try:
+            is_model = isinstance(model, type) and issubclass(model, models.Model)
+        except TypeError:
+            is_model = False
+        if not is_model:
+            raise InvalidAutoFactoryModelError
         field_name_list, to_ignore_list = cls.interface.handleCustomFields(model)
 
         fields = [
@@ -71,7 +113,7 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         if isinstance(obj, list):
             for item in obj:
                 if not isinstance(item, models.Model):
-                    raise ValueError("Model must be a type")
+                    raise InvalidGeneratedObjectError()
                 cls._handleManyToManyFieldsAfterCreation(item, params)
         else:
             cls._handleManyToManyFieldsAfterCreation(obj, params)
@@ -191,21 +233,21 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         cls, use_creation_method: bool, params: dict[str, Any]
     ) -> models.Model | list[models.Model]:
         """
-        Create or build instance(s) using the configured adjustment method.
+        Create or build model instance(s) using the configured adjustment method.
 
         Parameters:
-            use_creation_method (bool): Whether generated objects should be saved.
-            params (dict[str, Any]): Arguments forwarded to the adjustment callback.
+            use_creation_method (bool): If True, created records are validated and saved; if False, unsaved instances are returned.
+            params (dict[str, Any]): Keyword arguments forwarded to the adjustment method to produce record dict(s).
 
         Returns:
-            models.Model | list[models.Model]: Created or built instance(s).
+            models.Model | list[models.Model]: A single model instance or a list of instances — saved instances when `use_creation_method` is True, unsaved otherwise.
 
         Raises:
-            ValueError: If no adjustment method has been configured.
+            UndefinedAdjustmentMethodError: If no adjustment method has been configured on the factory.
         """
         model_cls = cls._meta.model
         if cls._adjustmentMethod is None:
-            raise ValueError("generate_func is not defined")
+            raise UndefinedAdjustmentMethodError()
         records = cls._adjustmentMethod(**params)
         if isinstance(records, dict):
             if use_creation_method: