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

general_manager/factory/factories.py

@@ -1,48 +1,121 @@
 """Helpers for generating realistic factory values for Django models."""
 
 from __future__ import annotations
-from typing import Any, cast, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, cast
+
 from factory.declarations import LazyFunction
 from factory.faker import Faker
 import exrex  # type: ignore[import-untyped]
-from django.db import models
 from django.core.validators import RegexValidator
-import random
+from django.db import models
+from datetime import date, datetime, time, timezone
 from decimal import Decimal
+from random import SystemRandom
 from general_manager.measurement.measurement import Measurement
 from general_manager.measurement.measurementField import MeasurementField
-from datetime import date, datetime, time, timezone
 
 if TYPE_CHECKING:
     from general_manager.factory.autoFactory import AutoFactory
 
 
+_RNG = SystemRandom()
+
+
+class MissingFactoryOrInstancesError(ValueError):
+    """Raised when a related model offers neither a factory nor existing instances."""
+
+    def __init__(self, related_model: type[models.Model]) -> None:
+        """
+        Exception raised when a related model has neither a registered factory nor any existing instances.
+
+        Parameters:
+            related_model (type[models.Model]): The Django model class that lacks both a factory and existing instances.
+        """
+        super().__init__(
+            f"No factory found for {related_model.__name__} and no instances found."
+        )
+
+
+class MissingRelatedModelError(ValueError):
+    """Raised when a relational field lacks a related model definition."""
+
+    def __init__(self, field_name: str) -> None:
+        """
+        Initialize the exception for a field that does not declare a related model.
+
+        Parameters:
+            field_name (str): The name of the field missing a related model; included in the exception message.
+        """
+        super().__init__(f"Field {field_name} does not have a related model defined.")
+
+
+class InvalidRelatedModelTypeError(TypeError):
+    """Raised when a relational field references an incompatible model type."""
+
+    def __init__(self, field_name: str, related: object) -> None:
+        """
+        Initialize the exception indicating a relational field references a non-model type.
+
+        Parameters:
+            field_name (str): Name of the relational field that declared an invalid related model.
+            related (object): The value provided as the related model; its repr is included in the exception message.
+        """
+        super().__init__(
+            f"Related model for {field_name} must be a Django model class, got {related!r}."
+        )
+
+
 def getFieldValue(
     field: models.Field[Any, Any] | models.ForeignObjectRel,
-) -> object:
+) -> Any:
     """
-    Generate a realistic value for a Django model field.
+    Generate a realistic sample value for a Django model field or relation.
+
+    This returns a value appropriate for the field's type (e.g., text for TextField, Decimal for DecimalField,
+    datetime for DateTimeField, a LazyFunction that creates or selects a related instance for relational fields).
+    If the field is nullable there is a 10% chance this will return `None`.
 
     Parameters:
-        field (models.Field | models.ForeignObjectRel): Field definition to generate a value for.
+        field (models.Field | models.ForeignObjectRel): The Django field or relation to generate a value for.
 
     Returns:
-        object: Value appropriate for the field type.
+        object: A value suitable for assignment to the given field (or `None`).
 
     Raises:
-        ValueError: If a related model lacks both a factory and existing instances.
+        MissingFactoryOrInstancesError: When a related field's model has neither a factory nor any existing instances.
+        MissingRelatedModelError: When a relational field does not declare a related model.
+        InvalidRelatedModelTypeError: When a relational field's related value is not a Django model class.
     """
     if field.null:
-        if random.choice([True] + 9 * [False]):
+        if _RNG.choice([True] + 9 * [False]):
             return None
 
     if isinstance(field, MeasurementField):
 
         def _measurement() -> Measurement:
-            value = Decimal(random.randrange(0, 10_000_000)) / Decimal("100")  # two dp
+            """
+            Create a Measurement using the field's base unit and a randomly chosen value.
+
+            Returns:
+                measurement (Measurement): A Measurement whose value is a Decimal with two decimal places between 0.00 and 100000.00 and whose unit is the enclosing field's `base_unit`.
+            """
+            value = Decimal(_RNG.randrange(0, 10_000_000)) / Decimal("100")  # two dp
             return Measurement(value, field.base_unit)
 
         return LazyFunction(_measurement)
+    elif (
+        getattr(field, "choices", None)
+        and not getattr(field, "many_to_one", False)
+        and not getattr(field, "many_to_many", False)
+    ):
+        # Use any declared choices directly to keep generated values valid.
+        flat_choices = [
+            choice[0] if isinstance(choice, (list, tuple)) and choice else choice
+            for choice in list(getattr(field, "flatchoices", ()))
+        ]
+        if flat_choices:
+            return LazyFunction(lambda: _RNG.choice(flat_choices))
+        # Fall through to default behaviour when no usable choices were discovered.
     elif isinstance(field, models.TextField):
         return cast(str, Faker("paragraph"))
     elif isinstance(field, models.IntegerField):
@@ -108,21 +181,19 @@ def getFieldValue(
             # If no factory exists, pick a random existing instance
             related_instances = list(related_model.objects.all())
             if related_instances:
-                return LazyFunction(lambda: random.choice(related_instances))
+                return LazyFunction(lambda: _RNG.choice(related_instances))
             else:
-                raise ValueError(
-                    f"No factory found for {related_model.__name__} and no instances found"
-                )
+                raise MissingFactoryOrInstancesError(related_model)
     elif isinstance(field, models.ForeignKey):
         related_model = getRelatedModel(field)
         # Create or get an instance of the related model
         if hasattr(related_model, "_general_manager_class"):
-            create_a_new_instance = random.choice([True, True, False])
+            create_a_new_instance = _RNG.choice([True, True, False])
             if not create_a_new_instance:
                 existing_instances = list(related_model.objects.all())
                 if existing_instances:
                     # Pick a random existing instance
-                    return LazyFunction(lambda: random.choice(existing_instances))
+                    return LazyFunction(lambda: _RNG.choice(existing_instances))
 
             related_factory = related_model._general_manager_class.Factory  # type: ignore
             return related_factory()
@@ -131,11 +202,9 @@ def getFieldValue(
             # If no factory exists, pick a random existing instance
             related_instances = list(related_model.objects.all())
             if related_instances:
-                return LazyFunction(lambda: random.choice(related_instances))
+                return LazyFunction(lambda: _RNG.choice(related_instances))
             else:
-                raise ValueError(
-                    f"No factory found for {related_model.__name__} and no instances found"
-                )
+                raise MissingFactoryOrInstancesError(related_model)
     else:
         return None
 
@@ -144,28 +213,29 @@ def getRelatedModel(
     field: models.ForeignObjectRel | models.Field[Any, Any],
 ) -> type[models.Model]:
     """
-    Return the related model class for the given relational field.
+    Resolve and return the Django model class referenced by a relational field.
+
+    If the field's declared related model is the string "self", this resolves it to the field's model before validation.
 
     Parameters:
-        field (models.Field | models.ForeignObjectRel): Relational field to inspect.
+        field (models.ForeignObjectRel | models.Field): Relational field or relation descriptor to inspect.
 
     Returns:
-        type[models.Model]: Related model class.
+        type[models.Model]: The related Django model class.
 
     Raises:
-        ValueError: If the field does not declare a related model.
+        MissingRelatedModelError: If the field does not declare a related model.
+        InvalidRelatedModelTypeError: If the resolved related model is not a Django model class.
     """
     related_model = field.related_model
     if related_model is None:
-        raise ValueError(f"Field {field.name} does not have a related model defined.")
+        raise MissingRelatedModelError(field.name)
     if related_model == "self":
         related_model = field.model
     if not isinstance(related_model, type) or not issubclass(
         related_model, models.Model
     ):
-        raise TypeError(
-            f"Related model for {field.name} must be a Django model class, got {related_model!r}"
-        )
+        raise InvalidRelatedModelTypeError(field.name, related_model)
     return cast(type[models.Model], related_model)
 
 
@@ -173,16 +243,18 @@ def getManyToManyFieldValue(
     field: models.ManyToManyField,
 ) -> list[models.Model]:
     """
-    Produce sample related instances for a ManyToMany field.
+    Generate a list of related model instances suitable for assigning to a ManyToManyField.
+
+    The function selects a random number of related objects (at least one when the field is not blank, up to 10). It will use the related model's factory to create new instances when available, prefer a mix of created and existing instances if both are present, or return existing instances when no factory is available.
 
     Parameters:
-        field (models.ManyToManyField): Field definition whose values should be generated.
+        field (models.ManyToManyField): The ManyToMany field to generate values for.
 
     Returns:
-        list[models.Model]: List of related instances to assign to the field.
+        list[models.Model]: A list of related model instances to assign to the field.
 
     Raises:
-        ValueError: If neither factories nor existing instances are available.
+        MissingFactoryOrInstancesError: If the related model provides neither a factory nor any existing instances.
     """
     related_factory = None
     related_model = getRelatedModel(field)
@@ -191,13 +263,13 @@ def getManyToManyFieldValue(
         related_factory = related_model._general_manager_class.Factory  # type: ignore
 
     min_required = 0 if field.blank else 1
-    number_of_instances = random.randint(min_required, 10)
+    number_of_instances = _RNG.randint(min_required, 10)
     if related_factory and related_instances:
-        number_to_create = random.randint(min_required, number_of_instances)
+        number_to_create = _RNG.randint(min_required, number_of_instances)
         number_to_pick = number_of_instances - number_to_create
         if number_to_pick > len(related_instances):
             number_to_pick = len(related_instances)
-        existing_instances = random.sample(related_instances, number_to_pick)
+        existing_instances = _RNG.sample(related_instances, number_to_pick)
         new_instances = [related_factory() for _ in range(number_to_create)]
         return existing_instances + new_instances
     elif related_factory:
@@ -209,9 +281,7 @@ def getManyToManyFieldValue(
         number_to_pick = number_of_instances
         if number_to_pick > len(related_instances):
             number_to_pick = len(related_instances)
-        existing_instances = random.sample(related_instances, number_to_pick)
+        existing_instances = _RNG.sample(related_instances, number_to_pick)
         return existing_instances
     else:
-        raise ValueError(
-            f"No factory found for {related_model.__name__} and no instances found"
-        )
+        raise MissingFactoryOrInstancesError(related_model)

general_manager/factory/factoryMethods.py

@@ -1,43 +1,62 @@
 """Convenience helpers for defining factory_boy lazy attributes."""
 
 from typing import Any, Optional
-from factory.declarations import LazyFunction, LazyAttribute, LazyAttributeSequence
-import random
-from general_manager.measurement.measurement import Measurement
-from datetime import timedelta, date, datetime
+
+from factory.declarations import LazyAttribute, LazyAttributeSequence, LazyFunction
+from datetime import date, datetime, timedelta
+from decimal import Decimal
 from faker import Faker
+from general_manager.measurement.measurement import Measurement
+from random import SystemRandom
 import uuid
-from decimal import Decimal
 
 fake = Faker()
+_RNG = SystemRandom()
+
+_AVG_DELTA_DAYS_ERROR = "avg_delta_days must be >= 0"
+_EMPTY_OPTIONS_ERROR = "options must be a non-empty list"
 
 
 def LazyMeasurement(
     min_value: int | float, max_value: int | float, unit: str
 ) -> LazyFunction:
     """
-    Return a lazy factory producing ``Measurement`` values in the given range.
+    Create a lazy factory that produces Measurement values with a numeric magnitude sampled between the given bounds and the specified unit.
 
     Parameters:
-        min_value (int | float): Minimum magnitude.
-        max_value (int | float): Maximum magnitude.
-        unit (str): Measurement unit.
+        min_value (int | float): Lower bound (inclusive) for the sampled magnitude.
+        max_value (int | float): Upper bound (inclusive) for the sampled magnitude.
+        unit (str): Unit string to attach to the Measurement.
+
+    Returns:
+        LazyFunction: A factory that yields a Measurement whose numeric value is drawn uniformly between min_value and max_value (formatted to six decimal places) and uses the provided unit.
     """
     return LazyFunction(
-        lambda: Measurement(f"{random.uniform(min_value, max_value):.6f}", unit)
+        lambda: Measurement(f"{_RNG.uniform(min_value, max_value):.6f}", unit)
     )
 
 
 def LazyDeltaDate(avg_delta_days: int, base_attribute: str) -> LazyAttribute:
-    """Return a lazy attribute that offsets a base date by a random delta.
+    """
+    Compute a date by offsetting an instance's base date attribute by a randomized number of days.
 
     Parameters:
-        avg_delta_days (int): Average number of days to offset.
-        base_attribute (str): Name of the attribute providing the base date.
+        avg_delta_days (int): Average number of days for the offset; the actual offset is randomly chosen
+            between floor(avg_delta_days / 2) and floor(avg_delta_days * 3 / 2), inclusive.
+        base_attribute (str): Name of the attribute on the instance that provides the base date. If that
+            attribute is missing or evaluates to false, today's date is used as the base.
+
+    Returns:
+        date: The base date shifted by the randomly chosen number of days.
+
+    Raises:
+        ValueError: If avg_delta_days is negative.
     """
+    if avg_delta_days < 0:
+        raise ValueError(_AVG_DELTA_DAYS_ERROR)
     return LazyAttribute(
-        lambda obj: (getattr(obj, base_attribute) or date.today())
-        + timedelta(days=random.randint(avg_delta_days // 2, avg_delta_days * 3 // 2))
+        lambda instance: (getattr(instance, base_attribute) or date.today())
+        + timedelta(days=_RNG.randint(avg_delta_days // 2, avg_delta_days * 3 // 2))
     )
 
 
@@ -59,57 +78,126 @@ def LazyDateToday() -> LazyFunction:
 
 
 def LazyDateBetween(start_date: date, end_date: date) -> LazyAttribute:
-    """Return a lazy attribute producing dates within the supplied range."""
+    """
+    Produce a lazy attribute that yields a date between two given dates (inclusive).
+
+    Parameters:
+        start_date (date): The start of the date range. If later than end_date, the range will be corrected.
+        end_date (date): The end of the date range. If earlier than start_date, the range will be corrected.
+
+    Returns:
+        date: A date between start_date and end_date, inclusive.
+    """
     delta = (end_date - start_date).days
     if delta < 0:
         start_date, end_date = end_date, start_date
         delta = -delta
-    return LazyAttribute(
-        lambda obj: start_date + timedelta(days=random.randint(0, delta))
-    )
+    return LazyAttribute(lambda _: start_date + timedelta(days=_RNG.randint(0, delta)))
 
 
 def LazyDateTimeBetween(start: datetime, end: datetime) -> LazyAttribute:
-    """Return a lazy attribute producing datetimes within the supplied range."""
+    """
+    Produce a lazy attribute that yields a datetime within the inclusive range defined by `start` and `end`.
+
+    If `start` is after `end`, the two endpoints are swapped before selecting a value.
+
+    Parameters:
+        start (datetime): The start of the datetime range.
+        end (datetime): The end of the datetime range.
+
+    Returns:
+        LazyAttribute: A lazy attribute that produces a `datetime` between `start` and `end` (inclusive).
+    """
     span = (end - start).total_seconds()
     if span < 0:
         start, end = end, start
         span = -span
     return LazyAttribute(
-        lambda obj: start + timedelta(seconds=random.randint(0, int(span)))
+        lambda _: start + timedelta(seconds=_RNG.randint(0, int(span)))
     )
 
 
 def LazyInteger(min_value: int, max_value: int) -> LazyFunction:
-    """Return a lazy factory yielding random integers within the bounds."""
-    return LazyFunction(lambda: random.randint(min_value, max_value))
+    """
+    Return a lazy factory that produces an integer within the provided bounds.
+
+    Parameters:
+        min_value (int): Lower bound (inclusive) for generated integers.
+        max_value (int): Upper bound (inclusive) for generated integers.
+
+    Returns:
+        int: A random integer greater than or equal to min_value and less than or equal to max_value.
+    """
+    return LazyFunction(lambda: _RNG.randint(min_value, max_value))
 
 
 def LazyDecimal(min_value: float, max_value: float, precision: int = 2) -> LazyFunction:
-    """Return a lazy factory yielding Decimal values within the bounds."""
+    """
+    Create a lazy factory that produces Decimal values between min_value and max_value, rounded to the specified precision.
+
+    Parameters:
+        min_value (float): Lower bound of the generated value.
+        max_value (float): Upper bound of the generated value.
+        precision (int): Number of decimal places to round the generated value to.
+
+    Returns:
+        Decimal: A Decimal value between min_value and max_value (inclusive), rounded to `precision` decimal places.
+    """
     fmt = f"{{:.{precision}f}}"
-    return LazyFunction(
-        lambda: Decimal(fmt.format(random.uniform(min_value, max_value)))
-    )
+    return LazyFunction(lambda: Decimal(fmt.format(_RNG.uniform(min_value, max_value))))
 
 
 def LazyChoice(options: list[Any]) -> LazyFunction:
-    """Return a lazy factory selecting a random element from the options."""
-    return LazyFunction(lambda: random.choice(options))
+    """
+    Create a lazy factory that selects a random element from the provided options.
+
+    Parameters:
+        options (list[Any]): Candidate values to choose from.
+
+    Returns:
+        Any: One element randomly chosen from `options`.
+    """
+    if not options:
+        raise ValueError(_EMPTY_OPTIONS_ERROR)
+    return LazyFunction(lambda: _RNG.choice(options))
 
 
 def LazySequence(start: int = 0, step: int = 1) -> LazyAttributeSequence:
-    """Return a lazy attribute sequence starting at ``start`` with ``step`` increments."""
-    return LazyAttributeSequence(lambda obj, n: start + n * step)
+    """
+    Produce a sequence attribute that yields successive integer values.
+
+    Each produced value equals start + index * step where index is the zero-based position in the sequence.
+
+    Parameters:
+        start (int): Initial value of the sequence.
+        step (int): Increment between successive values.
+
+    Returns:
+        LazyAttributeSequence: An attribute sequence that yields integers as described.
+    """
+    return LazyAttributeSequence(lambda _instance, index: start + index * step)
 
 
 def LazyBoolean(trues_ratio: float = 0.5) -> LazyFunction:
-    """Return a lazy factory yielding booleans with the given true ratio."""
-    return LazyFunction(lambda: random.random() < trues_ratio)
+    """
+    Return booleans where each value is True with the specified probability.
+
+    Parameters:
+        trues_ratio (float): Probability that the generated value is True; expected between 0 and 1.
+
+    Returns:
+        bool: `True` with probability `trues_ratio`, `False` otherwise.
+    """
+    return LazyFunction(lambda: _RNG.random() < trues_ratio)
 
 
 def LazyUUID() -> LazyFunction:
-    """Return a lazy factory producing UUID4 strings."""
+    """
+    Create a lazy factory that yields RFC 4122 version 4 UUID strings.
+
+    Returns:
+        uuid_str (str): A UUID4 string in standard 36-character representation.
+    """
     return LazyFunction(lambda: str(uuid.uuid4()))
 
 

general_manager/interface/__init__.py

@@ -12,10 +12,19 @@ __all__ = list(INTERFACE_EXPORTS)
 _MODULE_MAP = INTERFACE_EXPORTS
 
 if TYPE_CHECKING:
-    from general_manager._types.interface import *  # noqa: F401,F403
+    from general_manager._types.interface import *  # noqa: F403
 
 
 def __getattr__(name: str) -> Any:
+    """
+    Lazily resolve a public API export and return the object for the given attribute name.
+
+    Parameters:
+        name (str): Name of the attribute to resolve from the module's public exports.
+
+    Returns:
+        Any: The resolved export object associated with `name`.
+    """
     return resolve_export(
         name,
         module_all=__all__,