pydantic-fixturegen 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

pydantic_fixturegen/core/generate.py

@@ -3,19 +3,27 @@
 from __future__ import annotations
 
 import dataclasses
+import datetime
 import enum
 import inspect
 import random
-from collections.abc import Iterable, Sized
+from collections.abc import Iterable, Mapping, Sized
 from dataclasses import dataclass, is_dataclass
 from dataclasses import fields as dataclass_fields
 from typing import Any, get_type_hints
 
 from faker import Faker
-from pydantic import BaseModel
+from pydantic import BaseModel, ValidationError
 from pydantic.fields import FieldInfo
 
 from pydantic_fixturegen.core import schema as schema_module
+from pydantic_fixturegen.core.config import ConfigError
+from pydantic_fixturegen.core.constraint_report import ConstraintReporter
+from pydantic_fixturegen.core.field_policies import (
+    FieldPolicy,
+    FieldPolicyConflictError,
+    FieldPolicySet,
+)
 from pydantic_fixturegen.core.providers import ProviderRegistry, create_default_registry
 from pydantic_fixturegen.core.schema import FieldConstraints, FieldSummary, extract_constraints
 from pydantic_fixturegen.core.strategies import (
@@ -36,6 +44,19 @@ class GenerationConfig:
     default_p_none: float = 0.0
     optional_p_none: float = 0.0
     seed: int | None = None
+    time_anchor: datetime.datetime | None = None
+    field_policies: tuple[FieldPolicy, ...] = ()
+
+
+@dataclass(slots=True)
+class _PathEntry:
+    module: str
+    qualname: str
+    via_field: str | None = None
+
+    @property
+    def full(self) -> str:
+        return f"{self.module}.{self.qualname}"
 
 
 class InstanceGenerator:
@@ -70,6 +91,15 @@ class InstanceGenerator:
             plugin_manager=self._plugin_manager,
         )
         self._strategy_cache: dict[type[Any], dict[str, StrategyResult]] = {}
+        self._constraint_reporter = ConstraintReporter()
+        self._field_policy_set = (
+            FieldPolicySet(self.config.field_policies) if self.config.field_policies else None
+        )
+        self._path_stack: list[_PathEntry] = []
+
+    @property
+    def constraint_report(self) -> ConstraintReporter:
+        return self._constraint_reporter
 
     # ------------------------------------------------------------------ public API
     def generate_one(self, model: type[BaseModel]) -> BaseModel | None:
@@ -86,64 +116,223 @@ class InstanceGenerator:
         return results
 
     # ------------------------------------------------------------------ internals
-    def _build_model_instance(self, model_type: type[Any], *, depth: int) -> Any | None:
+    def _build_model_instance(
+        self,
+        model_type: type[Any],
+        *,
+        depth: int,
+        via_field: str | None = None,
+    ) -> Any | None:
         if depth >= self.config.max_depth:
             return None
         if not self._consume_object():
             return None
 
+        entry = self._make_path_entry(model_type, via_field)
+        self._path_stack.append(entry)
         try:
             strategies = self._get_model_strategies(model_type)
         except TypeError:
             return None
 
+        self._constraint_reporter.begin_model(model_type)
+
         values: dict[str, Any] = {}
-        for field_name, strategy in strategies.items():
-            values[field_name] = self._evaluate_strategy(strategy, depth)
+        try:
+            for field_name, strategy in strategies.items():
+                self._apply_field_policies(field_name, strategy)
+                values[field_name] = self._evaluate_strategy(
+                    strategy,
+                    depth,
+                    model_type,
+                    field_name,
+                )
+        finally:
+            self._path_stack.pop()
 
         try:
-            if isinstance(model_type, type) and issubclass(model_type, BaseModel):
-                return model_type(**values)
-            if is_dataclass(model_type):
-                return model_type(**values)
+            instance: Any | None = None
+            if (isinstance(model_type, type) and issubclass(model_type, BaseModel)) or is_dataclass(
+                model_type
+            ):
+                instance = model_type(**values)
+        except ValidationError as exc:
+            self._constraint_reporter.finish_model(
+                model_type,
+                success=False,
+                errors=exc.errors(),
+            )
+            return None
         except Exception:
+            self._constraint_reporter.finish_model(model_type, success=False)
             return None
-        return None
-
-    def _evaluate_strategy(self, strategy: StrategyResult, depth: int) -> Any:
-        if isinstance(strategy, UnionStrategy):
-            return self._evaluate_union(strategy, depth)
-        return self._evaluate_single(strategy, depth)
 
-    def _evaluate_union(self, strategy: UnionStrategy, depth: int) -> Any:
-        choices = strategy.choices
-        if not choices:
+        if instance is None:
+            self._constraint_reporter.finish_model(model_type, success=False)
             return None
 
-        selected = self.random.choice(choices) if strategy.policy == "random" else choices[0]
-        return self._evaluate_single(selected, depth)
+        self._constraint_reporter.finish_model(model_type, success=True)
+        return instance
 
-    def _evaluate_single(self, strategy: Strategy, depth: int) -> Any:
-        if self._should_return_none(strategy):
-            return None
+    def _evaluate_strategy(
+        self,
+        strategy: StrategyResult,
+        depth: int,
+        model_type: type[Any],
+        field_name: str,
+    ) -> Any:
+        if isinstance(strategy, UnionStrategy):
+            return self._evaluate_union(strategy, depth, model_type, field_name)
+        return self._evaluate_single(strategy, depth, model_type, field_name)
+
+    def _make_path_entry(self, model_type: type[Any], via_field: str | None) -> _PathEntry:
+        module = getattr(model_type, "__module__", "<unknown>")
+        qualname = getattr(
+            model_type,
+            "__qualname__",
+            getattr(model_type, "__name__", str(model_type)),
+        )
+        return _PathEntry(module=module, qualname=qualname, via_field=via_field)
 
-        summary = strategy.summary
-        enum_values = strategy.enum_values or summary.enum_values
+    def _apply_field_policies(self, field_name: str, strategy: StrategyResult) -> None:
+        if self._field_policy_set is None:
+            return
+        full_path, aliases = self._current_field_paths(field_name)
+        try:
+            policy_values = self._field_policy_set.resolve(full_path, aliases=aliases)
+        except FieldPolicyConflictError as exc:
+            raise ConfigError(str(exc)) from exc
 
-        if enum_values:
-            return self._select_enum_value(strategy, enum_values)
+        if not policy_values:
+            return
 
-        annotation = strategy.annotation
+        if isinstance(strategy, UnionStrategy):
+            union_override = policy_values.get("union_policy")
+            if union_override is not None:
+                strategy.policy = union_override
+            element_policy = {
+                key: policy_values[key]
+                for key in ("p_none", "enum_policy")
+                if key in policy_values and policy_values[key] is not None
+            }
+            if element_policy:
+                for choice in strategy.choices:
+                    self._apply_field_policy_to_strategy(choice, element_policy)
+            return
+
+        self._apply_field_policy_to_strategy(strategy, policy_values)
+
+    def _current_field_paths(self, field_name: str) -> tuple[str, tuple[str, ...]]:
+        if not self._path_stack:
+            return field_name, ()
+
+        full_segments: list[str] = []
+        name_segments: list[str] = []
+        model_segments: list[str] = []
+        field_segments: list[str] = []
+
+        for index, entry in enumerate(self._path_stack):
+            if index == 0:
+                full_segments.append(entry.full)
+                name_segments.append(entry.qualname)
+                model_segments.append(entry.qualname)
+            else:
+                if entry.via_field:
+                    full_segments.append(entry.via_field)
+                    name_segments.append(entry.via_field)
+                    field_segments.append(entry.via_field)
+                full_segments.append(entry.full)
+                name_segments.append(entry.qualname)
+                model_segments.append(entry.qualname)
+
+        full_path = ".".join((*full_segments, field_name))
+
+        alias_candidates: list[str] = []
+
+        alias_candidates.append(".".join((*name_segments, field_name)))
+        alias_candidates.append(".".join((*model_segments, field_name)))
+
+        if field_segments:
+            alias_candidates.append(".".join((*field_segments, field_name)))
+            root_fields = ".".join((name_segments[0], *field_segments, field_name))
+            alias_candidates.append(root_fields)
+
+        last_entry = self._path_stack[-1]
+        alias_candidates.append(".".join((last_entry.qualname, field_name)))
+        alias_candidates.append(".".join((last_entry.full, field_name)))
+        alias_candidates.append(field_name)
+
+        aliases = self._dedupe_paths(alias_candidates, exclude=full_path)
+        return full_path, aliases
 
-        if self._is_model_like(annotation):
-            return self._build_model_instance(annotation, depth=depth + 1)
+    @staticmethod
+    def _dedupe_paths(paths: Iterable[str], *, exclude: str) -> tuple[str, ...]:
+        seen: dict[str, None] = {}
+        for path in paths:
+            if not path or path == exclude or path in seen:
+                continue
+            seen[path] = None
+        return tuple(seen.keys())
 
-        if summary.type in {"list", "set", "tuple", "mapping"}:
-            return self._evaluate_collection(strategy, depth)
+    def _apply_field_policy_to_strategy(
+        self,
+        strategy: Strategy,
+        policy_values: Mapping[str, Any],
+    ) -> None:
+        if "p_none" in policy_values and policy_values["p_none"] is not None:
+            strategy.p_none = policy_values["p_none"]
+        if "enum_policy" in policy_values and policy_values["enum_policy"] is not None:
+            strategy.enum_policy = policy_values["enum_policy"]
 
-        if strategy.provider_ref is None:
+    def _evaluate_union(
+        self,
+        strategy: UnionStrategy,
+        depth: int,
+        model_type: type[Any],
+        field_name: str,
+    ) -> Any:
+        choices = strategy.choices
+        if not choices:
             return None
-        return self._call_strategy_provider(strategy)
+
+        selected = self.random.choice(choices) if strategy.policy == "random" else choices[0]
+        return self._evaluate_single(selected, depth, model_type, field_name)
+
+    def _evaluate_single(
+        self,
+        strategy: Strategy,
+        depth: int,
+        model_type: type[Any],
+        field_name: str,
+    ) -> Any:
+        summary = strategy.summary
+        self._constraint_reporter.record_field_attempt(model_type, field_name, summary)
+
+        if self._should_return_none(strategy):
+            value: Any = None
+        else:
+            enum_values = strategy.enum_values or summary.enum_values
+            if enum_values:
+                value = self._select_enum_value(strategy, enum_values)
+            else:
+                annotation = strategy.annotation
+
+                if self._is_model_like(annotation):
+                    value = self._build_model_instance(
+                        annotation,
+                        depth=depth + 1,
+                        via_field=field_name,
+                    )
+                elif summary.type in {"list", "set", "tuple", "mapping"}:
+                    value = self._evaluate_collection(strategy, depth)
+                else:
+                    if strategy.provider_ref is None:
+                        value = None
+                    else:
+                        value = self._call_strategy_provider(strategy)
+
+        self._constraint_reporter.record_field_value(field_name, value)
+        return value
 
     def _evaluate_collection(self, strategy: Strategy, depth: int) -> Any:
         summary = strategy.summary
@@ -154,13 +343,22 @@ class InstanceGenerator:
             return base_value
 
         if summary.type == "mapping":
-            return self._build_mapping_collection(base_value, item_annotation, depth)
+            return self._build_mapping_collection(
+                base_value,
+                item_annotation,
+                depth,
+                strategy.field_name,
+            )
 
         length = self._collection_length_from_value(base_value)
         count = max(1, length)
         items: list[Any] = []
         for _ in range(count):
-            nested = self._build_model_instance(item_annotation, depth=depth + 1)
+            nested = self._build_model_instance(
+                item_annotation,
+                depth=depth + 1,
+                via_field=strategy.field_name,
+            )
             if nested is not None:
                 items.append(nested)
 
@@ -180,6 +378,7 @@ class InstanceGenerator:
         base_value: Any,
         annotation: Any,
         depth: int,
+        field_name: str,
     ) -> dict[str, Any]:
         if isinstance(base_value, dict) and base_value:
             keys: Iterable[str] = base_value.keys()
@@ -190,7 +389,11 @@ class InstanceGenerator:
 
         result: dict[str, Any] = {}
         for key in keys:
-            nested = self._build_model_instance(annotation, depth=depth + 1)
+            nested = self._build_model_instance(
+                annotation,
+                depth=depth + 1,
+                via_field=field_name,
+            )
             if nested is not None:
                 result[str(key)] = nested
         return result
@@ -297,6 +500,7 @@ class InstanceGenerator:
             "summary": strategy.summary,
             "faker": self.faker,
             "random_generator": self.random,
+            "time_anchor": self.config.time_anchor,
         }
         kwargs.update(strategy.provider_kwargs)
 

pydantic_fixturegen/core/io_utils.py

@@ -7,6 +7,7 @@ import os
 import tempfile
 from dataclasses import dataclass
 from pathlib import Path
+from typing import Any
 
 __all__ = ["WriteResult", "write_atomic_text", "write_atomic_bytes"]
 
@@ -19,6 +20,7 @@ class WriteResult:
     wrote: bool
     skipped: bool
     reason: str | None = None
+    metadata: dict[str, Any] | None = None
 
 
 def write_atomic_text(
@@ -53,7 +55,13 @@ def _write_atomic(path: Path, data: bytes, *, hash_compare: bool) -> WriteResult
     if hash_compare and path.exists():
         existing = path.read_bytes()
         if _hash_bytes(existing) == digest:
-            return WriteResult(path=path, wrote=False, skipped=True, reason="unchanged")
+            return WriteResult(
+                path=path,
+                wrote=False,
+                skipped=True,
+                reason="unchanged",
+                metadata=None,
+            )
 
     with tempfile.NamedTemporaryFile(
         delete=False,
@@ -70,7 +78,7 @@ def _write_atomic(path: Path, data: bytes, *, hash_compare: bool) -> WriteResult
         temp_path.unlink(missing_ok=True)
         raise exc
 
-    return WriteResult(path=path, wrote=True, skipped=False, reason=None)
+    return WriteResult(path=path, wrote=True, skipped=False, reason=None, metadata=None)
 
 
 def _hash_bytes(data: bytes) -> str:

pydantic_fixturegen/core/path_template.py

@@ -0,0 +1,197 @@
+"""Utilities for rendering templated output paths."""
+
+from __future__ import annotations
+
+import datetime as _dt
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from string import Formatter
+from typing import Any
+
+from .errors import EmitError
+
+__all__ = [
+    "OutputTemplate",
+    "OutputTemplateContext",
+    "OutputTemplateError",
+]
+
+
+_ALLOWED_FIELDS = {"model", "case_index", "timestamp"}
+_PLACEHOLDER_PATTERN = re.compile(r"{([^{}]+)}")
+_SANITIZE_PATTERN = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+class OutputTemplateError(EmitError):
+    """Raised when a templated path cannot be rendered safely."""
+
+    def __init__(self, message: str, *, details: dict[str, object] | None = None) -> None:
+        super().__init__(message, details=details)
+
+
+@dataclass(slots=True)
+class OutputTemplateContext:
+    """Context data supplied when rendering an :class:`OutputTemplate`."""
+
+    model: str | None = None
+    timestamp: _dt.datetime | None = None
+
+
+class _StrictFormatter(Formatter):
+    def get_value(self, key: object, args: Sequence[Any], kwargs: Mapping[str, Any]) -> object:
+        if isinstance(key, str):
+            try:
+                return kwargs[key]
+            except KeyError as exc:
+                raise OutputTemplateError(
+                    f"Missing template variable '{{{key}}}'.",
+                    details={"field": key},
+                ) from exc
+        raise OutputTemplateError("Positional fields are not supported in templates.")
+
+
+class _TemplateTimestamp:
+    def __init__(self, value: _dt.datetime) -> None:
+        self._value = value
+
+    def __format__(self, format_spec: str) -> str:
+        if format_spec:
+            rendered = self._value.strftime(format_spec)
+        else:
+            rendered = self._value.strftime("%Y%m%dT%H%M%S")
+        sanitized = _sanitize_segment(rendered)
+        return sanitized or "timestamp"
+
+    def __str__(self) -> str:
+        return self.__format__("")
+
+
+class _TemplateString(str):
+    def __new__(cls, value: str) -> _TemplateString:
+        sanitized = _sanitize_segment(value)
+        return str.__new__(cls, sanitized or "artifact")
+
+
+class _TemplateCaseIndex(int):
+    def __new__(cls, value: int) -> _TemplateCaseIndex:
+        if value < 1:
+            raise OutputTemplateError(
+                "case_index must be >= 1",
+                details={"case_index": value},
+            )
+        return int.__new__(cls, value)
+
+    def __format__(self, format_spec: str) -> str:
+        formatted = format(int(self), format_spec) if format_spec else str(int(self))
+        return _sanitize_segment(formatted) or "1"
+
+    def __str__(self) -> str:
+        return self.__format__("")
+
+
+def _sanitize_segment(value: str) -> str:
+    sanitized = _SANITIZE_PATTERN.sub("_", value.strip())
+    return sanitized.strip("._-")
+
+
+def _collect_fields(template: str) -> set[str]:
+    return {match.group(1) for match in _PLACEHOLDER_PATTERN.finditer(template)}
+
+
+def _contains_placeholder(segment: str) -> bool:
+    return bool(_PLACEHOLDER_PATTERN.search(segment))
+
+
+class OutputTemplate:
+    """Render filesystem paths from user-supplied templates."""
+
+    def __init__(self, template: str | Path) -> None:
+        self._raw = str(template)
+        self._formatter = _StrictFormatter()
+        self._fields = _collect_fields(self._raw)
+        invalid = self._fields - _ALLOWED_FIELDS
+        if invalid:
+            raise OutputTemplateError(
+                "Unsupported template variable",
+                details={"fields": sorted(invalid)},
+            )
+
+    @property
+    def raw(self) -> str:
+        return self._raw
+
+    @property
+    def fields(self) -> set[str]:
+        return set(self._fields)
+
+    def uses_case_index(self) -> bool:
+        return "case_index" in self._fields
+
+    def has_dynamic_directories(self) -> bool:
+        candidate = Path(self._raw)
+        return any(_contains_placeholder(segment) for segment in candidate.parts[:-1])
+
+    def watch_parent(self) -> Path:
+        candidate = Path(self._raw)
+        parts = list(candidate.parts)
+        if len(parts) <= 1:
+            return Path(".")
+
+        stable: list[str] = []
+        for part in parts[:-1]:
+            if _contains_placeholder(part):
+                break
+            stable.append(part)
+
+        if not stable:
+            return Path(".")
+        return Path(*stable)
+
+    def preview_path(self) -> Path:
+        context = OutputTemplateContext(model="preview")
+        case_index = 1 if self.uses_case_index() else None
+        return self.render(context=context, case_index=case_index)
+
+    def render(
+        self,
+        *,
+        context: OutputTemplateContext | None = None,
+        case_index: int | None = None,
+    ) -> Path:
+        if not self._fields:
+            return Path(self._raw).expanduser()
+
+        ctx = context or OutputTemplateContext()
+        values: dict[str, object] = {}
+        if "model" in self._fields:
+            if ctx.model is None:
+                raise OutputTemplateError(
+                    "Template variable '{model}' requires a model context.",
+                )
+            values["model"] = _TemplateString(ctx.model)
+        if "timestamp" in self._fields:
+            timestamp = ctx.timestamp or _dt.datetime.now(_dt.timezone.utc)
+            values["timestamp"] = _TemplateTimestamp(timestamp)
+        if "case_index" in self._fields:
+            if case_index is None:
+                raise OutputTemplateError(
+                    "Template variable '{case_index}' requires an index.",
+                )
+            values["case_index"] = _TemplateCaseIndex(case_index)
+
+        rendered = self._formatter.format(self._raw, **values).strip()
+        if not rendered:
+            raise OutputTemplateError(
+                "Rendered template produced an empty path.",
+                details={"template": self._raw},
+            )
+
+        path = Path(rendered).expanduser()
+        if any(part == ".." for part in path.parts):
+            raise OutputTemplateError(
+                "Templates cannot traverse above the working directory.",
+                details={"path": rendered},
+            )
+        return path

pydantic_fixturegen/core/presets.py

@@ -0,0 +1,73 @@
+"""Preset definitions for curated generation policy bundles."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class PresetSpec:
+    """Descriptor for a preset and the configuration values it applies."""
+
+    name: str
+    description: str
+    settings: Mapping[str, Any]
+
+
+_PRESET_DEFINITIONS: dict[str, PresetSpec] = {
+    "boundary": PresetSpec(
+        name="boundary",
+        description=(
+            "Favor random union/enum selection and increase optional None probability for"
+            " boundary-focused datasets."
+        ),
+        settings={
+            "union_policy": "random",
+            "enum_policy": "random",
+            "p_none": 0.35,
+        },
+    ),
+    "boundary-max": PresetSpec(
+        name="boundary-max",
+        description=(
+            "Aggressive boundary exploration with high optional None probability and"
+            " randomized union/enum selection."
+        ),
+        settings={
+            "union_policy": "random",
+            "enum_policy": "random",
+            "p_none": 0.6,
+            "json": {"indent": 0},
+        },
+    ),
+}
+
+_ALIASES: dict[str, str] = {
+    "edge": "boundary",
+    "boundary-heavy": "boundary-max",
+}
+
+
+def normalize_preset_name(name: str) -> str:
+    """Normalize a preset name applying aliases and case folding."""
+
+    key = name.strip().lower()
+    return _ALIASES.get(key, key)
+
+
+def get_preset_spec(name: str) -> PresetSpec:
+    """Return the preset specification for ``name`` or raise ``KeyError``."""
+
+    normalized = normalize_preset_name(name)
+    return _PRESET_DEFINITIONS[normalized]
+
+
+def available_presets() -> list[PresetSpec]:
+    """Return the list of available preset specifications."""
+
+    return list(_PRESET_DEFINITIONS.values())
+
+
+__all__ = ["PresetSpec", "available_presets", "get_preset_spec", "normalize_preset_name"]