pydantic-fixturegen 1.0.0__py3-none-any.whl

pydantic_fixturegen/core/schema.py

@@ -0,0 +1,320 @@
+"""Utilities for extracting constraint metadata from Pydantic models."""
+
+from __future__ import annotations
+
+import dataclasses as dataclasses_module
+import datetime
+import decimal
+import enum
+import types
+import uuid
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Annotated, Any, Union, get_args, get_origin
+
+import annotated_types
+import pydantic
+from pydantic import BaseModel, SecretBytes, SecretStr
+from pydantic.fields import FieldInfo
+
+
+@dataclass(slots=True)
+class FieldConstraints:
+    ge: float | None = None
+    le: float | None = None
+    gt: float | None = None
+    lt: float | None = None
+    multiple_of: float | None = None
+    min_length: int | None = None
+    max_length: int | None = None
+    pattern: str | None = None
+    max_digits: int | None = None
+    decimal_places: int | None = None
+
+    def has_constraints(self) -> bool:
+        return any(
+            value is not None
+            for value in (
+                self.ge,
+                self.le,
+                self.gt,
+                self.lt,
+                self.multiple_of,
+                self.min_length,
+                self.max_length,
+                self.pattern,
+                self.max_digits,
+                self.decimal_places,
+            )
+        )
+
+
+@dataclass(slots=True)
+class FieldSummary:
+    type: str
+    constraints: FieldConstraints
+    format: str | None = None
+    item_type: str | None = None
+    enum_values: list[Any] | None = None
+    is_optional: bool = False
+    annotation: Any | None = None
+    item_annotation: Any | None = None
+
+
+def extract_constraints(field: FieldInfo) -> FieldConstraints:
+    """Extract constraint metadata from a single Pydantic FieldInfo."""
+    constraints = FieldConstraints()
+
+    for meta in field.metadata:
+        _apply_metadata(constraints, meta)
+
+    # Additional decimal info can be provided via annotation / metadata
+    _normalize_decimal_constraints(constraints)
+
+    return constraints
+
+
+def extract_model_constraints(model: type[BaseModel]) -> Mapping[str, FieldConstraints]:
+    """Return constraint metadata for each field on a Pydantic model."""
+    result: dict[str, FieldConstraints] = {}
+    for name, field in model.model_fields.items():
+        constraints = extract_constraints(field)
+        if constraints.has_constraints():
+            result[name] = constraints
+    return result
+
+
+def summarize_field(field: FieldInfo) -> FieldSummary:
+    constraints = extract_constraints(field)
+    annotation = field.annotation
+    summary = _summarize_annotation(annotation, constraints)
+    return summary
+
+
+def summarize_model_fields(model: type[BaseModel]) -> Mapping[str, FieldSummary]:
+    summary: dict[str, FieldSummary] = {}
+    for name, field in model.model_fields.items():
+        summary[name] = summarize_field(field)
+    return summary
+
+
+def _apply_metadata(constraints: FieldConstraints, meta: Any) -> None:
+    # Numeric bounds
+    if meta is None:
+        return
+
+    if isinstance(meta, annotated_types.Interval):
+        constraints.ge = _max_value(constraints.ge, _to_float(getattr(meta, "ge", None)))
+        constraints.le = _min_value(constraints.le, _to_float(getattr(meta, "le", None)))
+        constraints.gt = _max_value(constraints.gt, _to_float(getattr(meta, "gt", None)))
+        constraints.lt = _min_value(constraints.lt, _to_float(getattr(meta, "lt", None)))
+
+    if isinstance(meta, annotated_types.Ge):
+        constraints.ge = _max_value(constraints.ge, _to_float(meta.ge))
+    if isinstance(meta, annotated_types.Le):
+        constraints.le = _min_value(constraints.le, _to_float(meta.le))
+    if hasattr(annotated_types, "Gt") and isinstance(meta, annotated_types.Gt):
+        constraints.gt = _max_value(constraints.gt, _to_float(getattr(meta, "gt", None)))
+    if hasattr(annotated_types, "Lt") and isinstance(meta, annotated_types.Lt):
+        constraints.lt = _min_value(constraints.lt, _to_float(getattr(meta, "lt", None)))
+    if hasattr(annotated_types, "MultipleOf") and isinstance(meta, annotated_types.MultipleOf):
+        constraints.multiple_of = _to_float(getattr(meta, "multiple_of", None))
+
+    # String / collection length
+    if isinstance(meta, annotated_types.MinLen):
+        constraints.min_length = _max_int(constraints.min_length, meta.min_length)
+    if isinstance(meta, annotated_types.MaxLen):
+        constraints.max_length = _min_int(constraints.max_length, meta.max_length)
+
+    # General metadata container used by Pydantic for Field(...)
+    if hasattr(meta, "__dict__"):
+        data = meta.__dict__
+        if "pattern" in data and data["pattern"] is not None:
+            constraints.pattern = data["pattern"]
+        if "min_length" in data and data["min_length"] is not None:
+            constraints.min_length = _max_int(constraints.min_length, data["min_length"])
+        if "max_length" in data and data["max_length"] is not None:
+            constraints.max_length = _min_int(constraints.max_length, data["max_length"])
+        if "max_digits" in data and data["max_digits"] is not None:
+            constraints.max_digits = _min_int(constraints.max_digits, data["max_digits"])
+        if "decimal_places" in data and data["decimal_places"] is not None:
+            constraints.decimal_places = _min_int(
+                constraints.decimal_places, data["decimal_places"]
+            )
+
+
+def _normalize_decimal_constraints(constraints: FieldConstraints) -> None:
+    if (
+        constraints.max_digits is not None
+        and constraints.decimal_places is not None
+        and constraints.decimal_places > constraints.max_digits
+    ):
+        constraints.decimal_places = constraints.max_digits
+
+
+def _max_value(current: float | None, new: float | int | decimal.Decimal | None) -> float | None:
+    if new is None:
+        return current
+    new_float = float(new)
+    if current is None or new_float > current:
+        return new_float
+    return current
+
+
+def _min_value(current: float | None, new: float | int | decimal.Decimal | None) -> float | None:
+    if new is None:
+        return current
+    new_float = float(new)
+    if current is None or new_float < current:
+        return new_float
+    return current
+
+
+def _to_float(value: Any) -> float | None:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):  # pragma: no cover - defensive fallback
+        return None
+
+
+def _max_int(current: int | None, new: int | None) -> int | None:
+    if new is None:
+        return current
+    if current is None or new > current:
+        return int(new)
+    return current
+
+
+def _min_int(current: int | None, new: int | None) -> int | None:
+    if new is None:
+        return current
+    if current is None or new < current:
+        return int(new)
+    return current
+
+
+def _strip_optional(annotation: Any) -> tuple[Any, bool]:
+    origin = get_origin(annotation)
+    if origin in {Union, types.UnionType}:
+        args = [arg for arg in get_args(annotation) if arg is not type(None)]  # noqa: E721
+        if len(args) == 1 and len(get_args(annotation)) != len(args):
+            return args[0], True
+    return annotation, False
+
+
+def _extract_enum_values(annotation: Any) -> list[Any] | None:
+    if isinstance(annotation, type) and issubclass(annotation, enum.Enum):
+        return [member.value for member in annotation]
+    return None
+
+
+def _summarize_annotation(
+    annotation: Any,
+    constraints: FieldConstraints | None = None,
+) -> FieldSummary:
+    inner_annotation, is_optional = _strip_optional(annotation)
+    type_name, fmt, item_annotation = _infer_annotation_kind(inner_annotation)
+    item_type = None
+    item_annotation_clean = None
+    if item_annotation is not None:
+        item_inner, _ = _strip_optional(item_annotation)
+        item_annotation_clean = item_inner
+        item_type, _, _ = _infer_annotation_kind(item_inner)
+    enum_values = _extract_enum_values(inner_annotation)
+    return FieldSummary(
+        type=type_name,
+        constraints=constraints or FieldConstraints(),
+        format=fmt,
+        item_type=item_type,
+        enum_values=enum_values,
+        is_optional=is_optional,
+        annotation=inner_annotation,
+        item_annotation=item_annotation_clean,
+    )
+
+
+def _infer_annotation_kind(annotation: Any) -> tuple[str, str | None, Any | None]:
+    annotation = _unwrap_annotation(annotation)
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+
+    if origin in {Union, types.UnionType}:
+        non_none = [arg for arg in args if arg is not type(None)]  # noqa: E721
+        if len(non_none) == 1:
+            return _infer_annotation_kind(non_none[0])
+
+    if origin in {list, list[int]}:  # pragma: no cover - typing quirk
+        origin = list
+
+    if origin in {list, set, tuple}:
+        item_annotation = args[0] if args else None
+        type_map = {list: "list", set: "set", tuple: "tuple"}
+        return type_map.get(origin, "collection"), None, item_annotation
+
+    if origin in {dict}:
+        value_annotation = args[1] if len(args) > 1 else None
+        return "mapping", None, value_annotation
+
+    if isinstance(annotation, type) and issubclass(annotation, enum.Enum):
+        return "enum", None, None
+
+    if annotation is Any:
+        return "any", None, None
+
+    if isinstance(annotation, type):
+        if dataclasses_module.is_dataclass(annotation):
+            return "dataclass", None, None
+        email_type = getattr(pydantic, "EmailStr", None)
+        if email_type is not None and issubclass(annotation, email_type):
+            return "email", None, None
+        any_url_type = getattr(pydantic, "AnyUrl", None)
+        if any_url_type is not None and issubclass(annotation, any_url_type):
+            return "url", None, None
+        ip_address_type = getattr(pydantic, "IPvAnyAddress", None)
+        if ip_address_type is not None and issubclass(annotation, ip_address_type):
+            return "ip-address", None, None
+        ip_interface_type = getattr(pydantic, "IPvAnyInterface", None)
+        if ip_interface_type is not None and issubclass(annotation, ip_interface_type):
+            return "ip-interface", None, None
+        ip_network_type = getattr(pydantic, "IPvAnyNetwork", None)
+        if ip_network_type is not None and issubclass(annotation, ip_network_type):
+            return "ip-network", None, None
+        payment_card_type = getattr(pydantic, "PaymentCardNumber", None)
+        if payment_card_type is not None and issubclass(annotation, payment_card_type):
+            return "payment-card", None, None
+        if issubclass(annotation, SecretStr):
+            return "secret-str", None, None
+        if issubclass(annotation, SecretBytes):
+            return "secret-bytes", None, None
+        if issubclass(annotation, uuid.UUID):
+            return "uuid", None, None
+        if issubclass(annotation, datetime.datetime):
+            return "datetime", None, None
+        if issubclass(annotation, datetime.date) and not issubclass(annotation, datetime.datetime):
+            return "date", None, None
+        if issubclass(annotation, datetime.time):
+            return "time", None, None
+        if issubclass(annotation, BaseModel):
+            return "model", None, None
+        scalar_map = {
+            bool: "bool",
+            int: "int",
+            float: "float",
+            str: "string",
+            bytes: "bytes",
+            decimal.Decimal: "decimal",
+        }
+        for candidate, label in scalar_map.items():
+            if issubclass(annotation, candidate):
+                return label, None, None
+
+    return "any", None, None
+
+
+def _unwrap_annotation(annotation: Any) -> Any:
+    origin = get_origin(annotation)
+    if origin is Annotated:
+        return _unwrap_annotation(get_args(annotation)[0])
+    return annotation

pydantic_fixturegen/core/seed.py

@@ -0,0 +1,154 @@
+"""Deterministic seed plumbing for random, Faker, and optional NumPy streams."""
+
+from __future__ import annotations
+
+import hashlib
+import random
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from importlib import import_module
+from typing import Any, TypeVar, cast
+
+from faker import Faker
+
+try:  # pragma: no cover - optional dependency
+    _np = cast(Any, import_module("numpy"))
+except ModuleNotFoundError:  # pragma: no cover - numpy optional
+    _np = None
+
+DEFAULT_LOCALE = "en_US"
+_SEPARATOR = b"\x1f"  # unit separator for hash derivation
+
+
+def _normalize_seed(seed: Any | None) -> int:
+    """Normalize seed inputs to an integer suitable for RNGs."""
+    if isinstance(seed, int):
+        return seed
+
+    if seed is None:
+        return 0
+
+    payload = seed if isinstance(seed, bytes) else str(seed).encode("utf-8")
+    digest = hashlib.sha256(payload).digest()
+    return int.from_bytes(digest[:16], "big", signed=False)
+
+
+def _create_faker(locale: str, seed: int) -> Faker:
+    faker = Faker(locale)
+    faker.seed_instance(seed)
+    return faker
+
+
+def _create_numpy_rng(seed: int) -> Any | None:
+    if _np is None:
+        return None
+
+    bit_gen = _np.random.PCG64(seed)  # pragma: no cover
+    return _np.random.Generator(bit_gen)  # pragma: no cover
+
+
+def _seed_bytes(seed: int) -> bytes:
+    return str(seed).encode("utf-8")
+
+
+SeedKey = tuple[Any, ...]
+T = TypeVar("T")
+
+
+@dataclass
+class SeedManager:
+    """Manage deterministic random streams derived from a master seed."""
+
+    seed: Any | None = None
+    locale: str = DEFAULT_LOCALE
+
+    _normalized_seed: int = field(init=False, repr=False)
+    _seed_bytes: bytes = field(init=False, repr=False)
+    _base_random: random.Random = field(init=False, repr=False)
+    _faker: Faker = field(init=False, repr=False)
+    _numpy_rng: Any | None = field(init=False, repr=False)
+    _random_cache: dict[SeedKey, random.Random] = field(
+        default_factory=dict, init=False, repr=False
+    )
+    _faker_cache: dict[SeedKey, Faker] = field(default_factory=dict, init=False, repr=False)
+    _numpy_cache: dict[SeedKey, Any] = field(default_factory=dict, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._normalized_seed = _normalize_seed(self.seed)
+        self._seed_bytes = _seed_bytes(self._normalized_seed)
+        self._base_random = random.Random(self._normalized_seed)
+        self._faker = _create_faker(self.locale, self._normalized_seed)
+        self._numpy_rng = _create_numpy_rng(self._normalized_seed)
+
+    @property
+    def normalized_seed(self) -> int:
+        """Return the normalized integer seed."""
+        return self._normalized_seed
+
+    @property
+    def base_random(self) -> random.Random:
+        """Random generator seeded with the master seed."""
+        return self._base_random
+
+    @property
+    def faker(self) -> Faker:
+        """Faker instance seeded with the master seed."""
+        return self._faker
+
+    @property
+    def numpy_rng(self) -> Any | None:
+        """NumPy random generator seeded with the master seed (if NumPy is available)."""
+        return self._numpy_rng  # pragma: no cover - optional dependency
+
+    def derive_child_seed(self, *parts: Any) -> int:
+        """Derive a deterministic child seed from the master seed and supplied key parts."""
+        hasher = hashlib.sha256()
+        hasher.update(self._seed_bytes)
+
+        for part in parts:
+            hasher.update(_SEPARATOR)
+            hasher.update(str(part).encode("utf-8"))
+
+        digest = hasher.digest()
+        return int.from_bytes(digest[:16], "big", signed=False)
+
+    def _cache_get_or_create(
+        self, cache: dict[SeedKey, T], key: SeedKey, factory: Callable[[SeedKey], T]
+    ) -> T:
+        if key not in cache:
+            cache[key] = factory(key)
+        return cache[key]
+
+    def random_for(self, *parts: Any) -> random.Random:
+        """Return a deterministic `random.Random` stream for the given key parts."""
+        key = tuple(parts)
+
+        def factory(_: SeedKey) -> random.Random:
+            return random.Random(self.derive_child_seed(*parts))
+
+        return self._cache_get_or_create(self._random_cache, key, factory)
+
+    def faker_for(self, *parts: Any) -> Faker:
+        """Return a Faker instance seeded for the given key parts."""
+        key = tuple(parts)
+
+        def factory(_: SeedKey) -> Faker:
+            faker = Faker(self.locale)
+            faker.seed_instance(self.derive_child_seed(*parts))
+            return faker
+
+        return self._cache_get_or_create(self._faker_cache, key, factory)
+
+    def numpy_for(self, *parts: Any) -> Any | None:
+        """Return a NumPy generator seeded for the given key (if NumPy is available)."""
+        if _np is None:
+            return None
+        else:  # pragma: no cover
+            key = tuple(parts)
+
+            def factory(_: SeedKey) -> Any:
+                seed = self.derive_child_seed(*parts)
+                bit_gen = _np.random.PCG64(seed)  # pragma: no cover
+                return _np.random.Generator(bit_gen)  # pragma: no cover
+
+            return self._cache_get_or_create(self._numpy_cache, key, factory)

pydantic_fixturegen/core/strategies.py

@@ -0,0 +1,193 @@
+"""Strategy builder for field generation policies."""
+
+from __future__ import annotations
+
+import types
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Union, get_args, get_origin
+
+import pluggy
+from pydantic import BaseModel
+
+from pydantic_fixturegen.core import schema as schema_module
+from pydantic_fixturegen.core.providers import ProviderRef, ProviderRegistry
+from pydantic_fixturegen.core.schema import FieldConstraints, FieldSummary, summarize_model_fields
+from pydantic_fixturegen.plugins.loader import get_plugin_manager
+
+
+@dataclass(slots=True)
+class Strategy:
+    """Represents a concrete provider strategy for a field."""
+
+    field_name: str
+    summary: FieldSummary
+    annotation: Any
+    provider_ref: ProviderRef | None
+    provider_name: str | None
+    provider_kwargs: dict[str, Any] = field(default_factory=dict)
+    p_none: float = 0.0
+    enum_values: list[Any] | None = None
+    enum_policy: str | None = None
+
+
+@dataclass(slots=True)
+class UnionStrategy:
+    """Represents a strategy for union types."""
+
+    field_name: str
+    choices: list[Strategy]
+    policy: str
+
+
+StrategyResult = Strategy | UnionStrategy
+
+
+class StrategyBuilder:
+    """Builds provider strategies for Pydantic models."""
+
+    def __init__(
+        self,
+        registry: ProviderRegistry,
+        *,
+        enum_policy: str = "first",
+        union_policy: str = "first",
+        default_p_none: float = 0.0,
+        optional_p_none: float | None = None,
+        plugin_manager: pluggy.PluginManager | None = None,
+    ) -> None:
+        self.registry = registry
+        self.enum_policy = enum_policy
+        self.union_policy = union_policy
+        self.default_p_none = default_p_none
+        self.optional_p_none = optional_p_none if optional_p_none is not None else default_p_none
+        self._plugin_manager = plugin_manager or get_plugin_manager()
+
+    def build_model_strategies(self, model: type[BaseModel]) -> Mapping[str, StrategyResult]:
+        summaries = summarize_model_fields(model)
+        strategies: dict[str, StrategyResult] = {}
+        for name, model_field in model.model_fields.items():
+            summary = summaries[name]
+            strategies[name] = self.build_field_strategy(
+                model,
+                name,
+                model_field.annotation,
+                summary,
+            )
+        return strategies
+
+    def build_field_strategy(
+        self,
+        model: type[BaseModel],
+        field_name: str,
+        annotation: Any,
+        summary: FieldSummary,
+    ) -> StrategyResult:
+        base_annotation, _ = schema_module._strip_optional(annotation)
+        union_args = self._extract_union_args(base_annotation)
+        if union_args:
+            return self._build_union_strategy(model, field_name, union_args)
+        return self._build_single_strategy(model, field_name, summary, base_annotation)
+
+    # ------------------------------------------------------------------ helpers
+    def _build_union_strategy(
+        self,
+        model: type[BaseModel],
+        field_name: str,
+        union_args: Sequence[Any],
+    ) -> UnionStrategy:
+        choices: list[Strategy] = []
+        for ann in union_args:
+            summary = self._summarize_inline(ann)
+            choices.append(self._build_single_strategy(model, field_name, summary, ann))
+        return UnionStrategy(field_name=field_name, choices=choices, policy=self.union_policy)
+
+    def _build_single_strategy(
+        self,
+        model: type[BaseModel],
+        field_name: str,
+        summary: FieldSummary,
+        annotation: Any,
+    ) -> Strategy:
+        if summary.enum_values:
+            return Strategy(
+                field_name=field_name,
+                summary=summary,
+                annotation=annotation,
+                provider_ref=None,
+                provider_name="enum.static",
+                provider_kwargs={},
+                p_none=self.optional_p_none if summary.is_optional else self.default_p_none,
+                enum_values=summary.enum_values,
+                enum_policy=self.enum_policy,
+            )
+
+        if summary.type in {"model", "dataclass"}:
+            p_none = self.optional_p_none if summary.is_optional else self.default_p_none
+            return Strategy(
+                field_name=field_name,
+                summary=summary,
+                annotation=annotation,
+                provider_ref=None,
+                provider_name=summary.type,
+                provider_kwargs={},
+                p_none=p_none,
+            )
+
+        provider = self.registry.get(summary.type, summary.format)
+        if provider is None:
+            provider = self.registry.get(summary.type)
+        if provider is None and summary.type == "string":
+            provider = self.registry.get("string")
+        if provider is None:
+            raise ValueError(
+                f"No provider registered for field '{field_name}' with type '{summary.type}'."
+            )
+
+        p_none = self.default_p_none
+        if summary.is_optional:
+            p_none = self.optional_p_none
+
+        strategy = Strategy(
+            field_name=field_name,
+            summary=summary,
+            annotation=annotation,
+            provider_ref=provider,
+            provider_name=provider.name,
+            provider_kwargs={},
+            p_none=p_none,
+        )
+        return self._apply_strategy_plugins(model, field_name, strategy)
+
+    # ------------------------------------------------------------------ utilities
+    def _extract_union_args(self, annotation: Any) -> Sequence[Any]:
+        origin = get_origin(annotation)
+        if origin in {list, set, tuple, dict}:
+            return []
+        if origin in {Union, types.UnionType}:
+            args = [arg for arg in get_args(annotation) if arg is not type(None)]  # noqa: E721
+            if len(args) > 1:
+                return args
+        return []
+
+    def _summarize_inline(self, annotation: Any) -> FieldSummary:
+        return schema_module._summarize_annotation(annotation, FieldConstraints())
+
+    def _apply_strategy_plugins(
+        self,
+        model: type[BaseModel],
+        field_name: str,
+        strategy: Strategy,
+    ) -> Strategy:
+        results = self._plugin_manager.hook.pfg_modify_strategy(
+            model=model,
+            field_name=field_name,
+            strategy=strategy,
+        )
+        for result in results:
+            if isinstance(result, Strategy):
+                strategy = result
+        return strategy
+
+
+__all__ = ["Strategy", "UnionStrategy", "StrategyBuilder", "StrategyResult"]