conformly 0.7.3__tar.gz → 0.7.4__tar.gz

{conformly-0.7.3/src/conformly.egg-info → conformly-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conformly
-Version: 0.7.3
+Version: 0.7.4
 Summary: Generate valid & invalid test data from your typed schemas
 Author-email: Nikita Shabanov <nik.shabanov2024@gmail.com>
 License: MIT
@@ -297,17 +297,43 @@ For `case(Model, valid=False, strategy="<field>")`:
 - **If `allow_structural_violations=True`**, generator may substitute field missing in place of any other violations (avaliable only with `strategy="all"`)
 - **Exactly one field is targeted** (the one specified by `strategy`).
 - **The generator will violate constraints** for that field, making it invalid.
-- **If a field has multiple constraints**, the violated constraint may be chosen by generator logic (not necessarily the one you expect).
+- **Inside collections**, planning selects a compatible dictionary key, value, or
+  element before generation. Fixed tuples retain their length and order; unrelated
+  elements, keys, values, and model fields remain valid.
+- **Only the selected violation is guaranteed on its target**. Other constraints
+  on that same target are not guaranteed to remain satisfied. A `DUPLICATE`
+  violation preserves an allowed collection length; collections with a maximum
+  size below two cannot be targeted for duplication.
+- **Explicit impossible or unsupported violations raise `PlanningError`**;
+  empty-only collections do not offer element violations.
 - **For numeric bounds**, invalid values may violate the lower or upper bound (e.g., `age > 120` or `age < 18`).
 - **For float bounds**, invalid generation may produce `inf` when violating the upper boundary.
 
-If you need **deterministic control** over which exact constraint to violate, that is not implemented in yet (see Roadmap).
+Request an exact violation with `strategy="items::below_min"` or
+`path(Model, lambda m: m.items).violate(V.BELOW_MIN)`. Otherwise, the planner uses
+violation priority and chooses the first compatible key, value, or tuple element.
 
 ## Optional Fields and Defaults
 
-- If a field is **optional** (`Optional[T]`), valid generation may produce `None`.
-- If a field has a **default value**, valid generation returns the default.
-- Invalid generation **requires at least one constraint** on the targeted field (raises `ValueError` otherwise).
+- For untargeted fields, priority is **override → nullable `None` → model default
+  or default factory → generation**. Nullable fields currently always return `None`
+  without an override, even with a non-`None` default; their factories are not called.
+- Model defaults, factory results and overrides are trusted and returned without
+  validation. `valid=True` guarantees the validity of generated values, not of
+  caller-supplied data. An invalid supplied value can also make an unrelated field
+  invalid when generating a negative case.
+- Invalid targets bypass their defaults, nullable priority and overrides. Other
+  fields retain the priority above. Default factories are called once per generated
+  payload when selected by this priority; attrs factories requiring `self` are unsupported.
+- TypedDict `NotRequired[T]` controls key presence independently of whether `T`
+  accepts `None`. Valid generation currently includes these keys with values of `T`;
+  `NotRequired[int]` does not become a present `None`.
+- `MISSING_FIELD` is offered only for required fields: nullable required fields can
+  be removed, but fields with defaults and TypedDict `NotRequired` keys cannot.
+  `EXTRA_FIELD` is offered for Pydantic only with `extra="forbid"`; `ignore` and
+  `allow` accept extra data. Other adapters treat undeclared keys as structural violations.
+- A target needs an applicable semantic, type or structural violation; impossible
+  explicit requests raise `PlanningError`.
 
 ## Constraints
 
@@ -327,6 +353,19 @@ If you need **deterministic control** over which exact constraint to violate, th
 | Collection | `MaxItems(n)` | `max_length=n` (for lists in `Field(...)`) |
 | Collection | `UniqueItems(bool)` | `set[T]`, `frozenset[T]` |
 
+`Pattern` uses Python regex search semantics, consistent with Pydantic: a match
+anywhere in the string is sufficient. Use anchors (`^...$`) to require a whole-string
+match. Pattern mismatches are verified; unsuccessful inversion raises a structured
+`GenerationError` instead of returning a matching value. Obvious universal patterns
+(such as `(?s).*`) are excluded from automatic planning, and explicit mismatch
+requests raise `PlanningError`.
+
+`MultipleOf` requires a finite positive divisor. For floats, a quotient within
+`1e-9` of an integer is treated as a multiple (no relative tolerance). Integer
+`NOT_MULTIPLE` requests for divisors such as `1` or `0.5`, which divide every integer,
+raise `PlanningError` and are excluded from automatic planning. A bounded range
+without a representable multiple raises `GenerationError` with code `no_multiples_of`.
+
 > Important: Pydantic's constr(), conint(), and functional validators are not interpreted as constraints.
 > Use Field() parameters for constraint extraction.
 
@@ -751,6 +790,3 @@ Contributions welcome!
 - Add tests for new functionality
 - Run `uv run -m pytest` and `uv run -m ruff check .`
 - Submit a pull request
-
-Test collection and assertion audit findings, including deferred collection checks,
-are documented in [the test audit](docs/test-audit.md).

{conformly-0.7.3 → conformly-0.7.4}/README.md

@@ -264,17 +264,43 @@ For `case(Model, valid=False, strategy="<field>")`:
 - **If `allow_structural_violations=True`**, generator may substitute field missing in place of any other violations (avaliable only with `strategy="all"`)
 - **Exactly one field is targeted** (the one specified by `strategy`).
 - **The generator will violate constraints** for that field, making it invalid.
-- **If a field has multiple constraints**, the violated constraint may be chosen by generator logic (not necessarily the one you expect).
+- **Inside collections**, planning selects a compatible dictionary key, value, or
+  element before generation. Fixed tuples retain their length and order; unrelated
+  elements, keys, values, and model fields remain valid.
+- **Only the selected violation is guaranteed on its target**. Other constraints
+  on that same target are not guaranteed to remain satisfied. A `DUPLICATE`
+  violation preserves an allowed collection length; collections with a maximum
+  size below two cannot be targeted for duplication.
+- **Explicit impossible or unsupported violations raise `PlanningError`**;
+  empty-only collections do not offer element violations.
 - **For numeric bounds**, invalid values may violate the lower or upper bound (e.g., `age > 120` or `age < 18`).
 - **For float bounds**, invalid generation may produce `inf` when violating the upper boundary.
 
-If you need **deterministic control** over which exact constraint to violate, that is not implemented in yet (see Roadmap).
+Request an exact violation with `strategy="items::below_min"` or
+`path(Model, lambda m: m.items).violate(V.BELOW_MIN)`. Otherwise, the planner uses
+violation priority and chooses the first compatible key, value, or tuple element.
 
 ## Optional Fields and Defaults
 
-- If a field is **optional** (`Optional[T]`), valid generation may produce `None`.
-- If a field has a **default value**, valid generation returns the default.
-- Invalid generation **requires at least one constraint** on the targeted field (raises `ValueError` otherwise).
+- For untargeted fields, priority is **override → nullable `None` → model default
+  or default factory → generation**. Nullable fields currently always return `None`
+  without an override, even with a non-`None` default; their factories are not called.
+- Model defaults, factory results and overrides are trusted and returned without
+  validation. `valid=True` guarantees the validity of generated values, not of
+  caller-supplied data. An invalid supplied value can also make an unrelated field
+  invalid when generating a negative case.
+- Invalid targets bypass their defaults, nullable priority and overrides. Other
+  fields retain the priority above. Default factories are called once per generated
+  payload when selected by this priority; attrs factories requiring `self` are unsupported.
+- TypedDict `NotRequired[T]` controls key presence independently of whether `T`
+  accepts `None`. Valid generation currently includes these keys with values of `T`;
+  `NotRequired[int]` does not become a present `None`.
+- `MISSING_FIELD` is offered only for required fields: nullable required fields can
+  be removed, but fields with defaults and TypedDict `NotRequired` keys cannot.
+  `EXTRA_FIELD` is offered for Pydantic only with `extra="forbid"`; `ignore` and
+  `allow` accept extra data. Other adapters treat undeclared keys as structural violations.
+- A target needs an applicable semantic, type or structural violation; impossible
+  explicit requests raise `PlanningError`.
 
 ## Constraints
 
@@ -294,6 +320,19 @@ If you need **deterministic control** over which exact constraint to violate, th
 | Collection | `MaxItems(n)` | `max_length=n` (for lists in `Field(...)`) |
 | Collection | `UniqueItems(bool)` | `set[T]`, `frozenset[T]` |
 
+`Pattern` uses Python regex search semantics, consistent with Pydantic: a match
+anywhere in the string is sufficient. Use anchors (`^...$`) to require a whole-string
+match. Pattern mismatches are verified; unsuccessful inversion raises a structured
+`GenerationError` instead of returning a matching value. Obvious universal patterns
+(such as `(?s).*`) are excluded from automatic planning, and explicit mismatch
+requests raise `PlanningError`.
+
+`MultipleOf` requires a finite positive divisor. For floats, a quotient within
+`1e-9` of an integer is treated as a multiple (no relative tolerance). Integer
+`NOT_MULTIPLE` requests for divisors such as `1` or `0.5`, which divide every integer,
+raise `PlanningError` and are excluded from automatic planning. A bounded range
+without a representable multiple raises `GenerationError` with code `no_multiples_of`.
+
 > Important: Pydantic's constr(), conint(), and functional validators are not interpreted as constraints.
 > Use Field() parameters for constraint extraction.
 
@@ -718,6 +757,3 @@ Contributions welcome!
 - Add tests for new functionality
 - Run `uv run -m pytest` and `uv run -m ruff check .`
 - Submit a pull request
-
-Test collection and assertion audit findings, including deferred collection checks,
-are documented in [the test audit](docs/test-audit.md).

{conformly-0.7.3 → conformly-0.7.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "conformly"
-version = "0.7.3"
+version = "0.7.4"
 description = "Generate valid & invalid test data from your typed schemas"
 readme = "README.md"
 requires-python = ">=3.12"

{conformly-0.7.3 → conformly-0.7.4}/src/conformly/_internal/api/_utils.py

@@ -62,7 +62,13 @@ def plan_tasks(
 
     if split_by_violations:
         return [
-            PlannedTask(path=path, allowed_violations=(violation,))
+            plan_violation_task(
+                model,
+                path,
+                allow_type_mismatch,
+                allow_structural_violations,
+                forced_violation=violation,
+            )
             for path in paths
             for violation in plan_violation_task(
                 model, path, allow_type_mismatch, allow_structural_violations

{conformly-0.7.3 → conformly-0.7.4}/src/conformly/_internal/generator/orchestration.py

@@ -5,12 +5,19 @@ from .context import GenerationContext
 from .registry import choose_mismatch_kind, get_generator
 
 from conformly._internal.planner import PlannedTask
+from conformly._internal.planner.model import CollectionTarget
 from conformly._internal.resolver import (
     ResolvedField,
     ResolvedModel,
     create_minimal_semantic,
 )
-from conformly._internal.resolver.semantics import ListSemantic, TupleSemantic
+from conformly._internal.resolver.semantics import (
+    DictSemantic,
+    FieldSemantics,
+    ListSemantic,
+    ObjectSemantic,
+    TupleSemantic,
+)
 from conformly._internal.tracer import Tracer, ValueSource
 from conformly._internal.types import UNSET, FieldKind, FieldPath, ViolationType
 
@@ -43,6 +50,8 @@ def generate_invalid(
         violations=task.allowed_violations,
         overrides=overrides,
         tracer=tracer,
+        collection_target=task.collection_target,
+        collection_steps=task.collection_steps,
     )
 
 
@@ -55,6 +64,8 @@ def _built_dict_with_violations(
     overrides: dict[FieldPath, Any] | None = None,
     tracer: Tracer | None = None,
     path_names: tuple[str, ...] = (),
+    collection_target: CollectionTarget | None = None,
+    collection_steps: tuple[tuple[FieldPath, CollectionTarget], ...] = (),
 ) -> dict[str, Any]:
     result: dict[str, Any] = {}
     target_index = target_path[depth]
@@ -88,7 +99,9 @@ def _built_dict_with_violations(
 
             if tracer:
                 tracer.set_target_path(".".join((*path_names, field.name)))
-            value = generate_field(ctx, field, violations, overrides, tracer)
+            value = generate_field(
+                ctx, field, violations, overrides, tracer, collection_target
+            )
             if value is not UNSET:
                 result[field.name] = value
 
@@ -100,7 +113,7 @@ def _built_dict_with_violations(
                     field=field.name,
                 )
 
-            result[field.name] = _built_dict_with_violations(
+            nested_value = _built_dict_with_violations(
                 ctx=ctx,
                 model=field.nested_model,
                 target_path=target_path,
@@ -109,8 +122,27 @@ def _built_dict_with_violations(
                 overrides=overrides,
                 tracer=tracer,
                 path_names=(*path_names, field.name),
+                collection_target=collection_target,
+                collection_steps=collection_steps,
             )
 
+            if isinstance(field.semantic, (ListSemantic, DictSemantic)):
+                step = next(
+                    (t for p, t in collection_steps if p == target_path[: depth + 1]),
+                    None,
+                )
+                if step is None:
+                    raise generation_error(
+                        "Nested collection requires a planned target",
+                        code="missing_collection_target",
+                    )
+                container = _generate_nested_collection(
+                    ctx, field.semantic, step, nested_value
+                )
+                result[field.name] = container
+            else:
+                result[field.name] = nested_value
+
     else:
         key, value = _generate_extra_field_value(ctx)
         suffix = 1
@@ -137,6 +169,7 @@ def generate_field(
     violations: tuple[ViolationType, ...] | None = None,
     overrides: dict[FieldPath, Any] | None = None,
     tracer: Tracer | None = None,
+    collection_target: CollectionTarget | None = None,
 ) -> Any:
     if violations is None:
         if overrides and field.path in overrides:
@@ -160,7 +193,7 @@ def generate_field(
             return value
 
         if field.nested_model and not isinstance(
-            field.semantic, (ListSemantic, TupleSemantic)
+            field.semantic, (ListSemantic, DictSemantic, TupleSemantic)
         ):
             return generate_valid(ctx, field.nested_model, overrides)
 
@@ -170,31 +203,50 @@ def generate_field(
         tracer.set_violation(violation)
         tracer.set_value_source(ValueSource.GENERATED)
 
-    if violation == ViolationType.TYPE_MISMATCH:
-        mismatch_kind = choose_mismatch_kind(field.semantic.kind)
-        mismatch_semantic = create_minimal_semantic(mismatch_kind)
-        value = get_generator(mismatch_kind).generate_value(
-            ctx, mismatch_semantic, None
-        )
-        if tracer:
-            tracer.set_generated_value(value)
-        return value
-
-    if violation == ViolationType.MISSING_FIELD:
-        if tracer:
-            tracer.set_generated_value(UNSET)
-        return UNSET
-
-    value = get_generator(field.semantic.kind).generate_value(
-        ctx, field.semantic, violation
+    value = generate_semantic_value(
+        ctx, field.semantic, field.nested_model, violations, collection_target
     )
-
     if tracer:
         tracer.set_generated_value(value)
-
     return value
 
 
+def generate_semantic_value(
+    ctx: GenerationContext,
+    semantic: FieldSemantics,
+    nested_model: ResolvedModel | None,
+    violations: tuple[ViolationType, ...] | None,
+    collection_target: CollectionTarget | None = None,
+) -> Any:
+    """Generate directly from resolved semantics, without synthetic field models."""
+    violation = _choose_violation(violations)
+    if violation == ViolationType.TYPE_MISMATCH:
+        mismatch_kind = choose_mismatch_kind(semantic.kind)
+        return get_generator(mismatch_kind).generate_value(
+            ctx, create_minimal_semantic(mismatch_kind), None
+        )
+    if violation == ViolationType.MISSING_FIELD:
+        return UNSET
+    if nested_model is not None and isinstance(semantic, ObjectSemantic):
+        if violation is not None:
+            raise generation_error(
+                "Nested model violation requires a field target",
+                code="missing_nested_target",
+            )
+        return generate_valid(ctx, nested_model)
+    from .types import dictionaries, list as lists, tuple as tuples
+
+    if isinstance(semantic, ListSemantic):
+        return lists.generate_value(ctx, semantic, violation, target=collection_target)
+    if isinstance(semantic, DictSemantic):
+        return dictionaries.generate_value(
+            ctx, semantic, violation, target=collection_target
+        )
+    if isinstance(semantic, TupleSemantic):
+        return tuples.generate_value(ctx, semantic, violation, target=collection_target)
+    return get_generator(semantic.kind).generate_value(ctx, semantic, violation)
+
+
 def _choose_violation(
     violations: tuple[ViolationType, ...] | None,
 ) -> ViolationType | None:
@@ -209,3 +261,28 @@ def _generate_extra_field_value(ctx: GenerationContext) -> tuple[str, Any]:
     value = get_generator(semantic.kind).generate_value(ctx, semantic, None)
     key = "extra"
     return (key, value)
+
+
+def _generate_nested_collection(
+    ctx: GenerationContext,
+    semantic: ListSemantic | DictSemantic,
+    target: CollectionTarget,
+    nested_value: dict[str, Any],
+) -> Any:
+    from .types._utils import calculate_valid_collection_range, unique_collection_range
+    from .types.dictionaries import _generate_dict_of_length
+    from .types.list import _generate_list_of_length
+
+    lower, upper = calculate_valid_collection_range(semantic)
+    if isinstance(semantic, DictSemantic):
+        lower, upper = unique_collection_range(
+            lower, upper, semantic.key_semantic, collection="dict"
+        )
+        length = ctx.rng.randint(lower, upper)
+        return _generate_dict_of_length(
+            ctx, semantic, length, target=target, target_value=nested_value
+        )
+    length = ctx.rng.randint(lower, upper)
+    result = _generate_list_of_length(ctx, semantic, length - 1)
+    result.insert(target.index, nested_value)
+    return result

conformly-0.7.4/src/conformly/_internal/generator/types/_utils.py

@@ -0,0 +1,84 @@
+from typing import Any
+
+from .._errors import generation_error
+from ..context import GenerationContext
+
+from conformly._internal.resolver import ResolvedModel
+from conformly._internal.resolver.semantics import (
+    DictSemantic,
+    FieldSemantics,
+    ListSemantic,
+    TupleSemantic,
+)
+from conformly._internal.resolver.semantics._domains import finite_cardinality
+from conformly._internal.types import ViolationType
+from conformly.exceptions import GenerationError
+
+
+def calculate_valid_collection_range(
+    semantic: ListSemantic | DictSemantic | TupleSemantic,
+) -> tuple[int, int]:
+    """Choose a small default range without overriding declared size limits."""
+    if semantic.length_range is None:
+        return 1, 3
+    lower = semantic.length_range.min_length
+    upper = semantic.length_range.max_length
+    if upper == 0:
+        return lower, 0
+    lower = max(1, lower)
+    return lower, upper if upper is not None else max(3, lower)
+
+
+def unique_collection_range(
+    lower: int,
+    upper: int,
+    semantic: FieldSemantics,
+    *,
+    collection: str,
+    extra_values: int = 0,
+) -> tuple[int, int]:
+    cardinality = finite_cardinality(semantic)
+    if cardinality is not None:
+        cardinality += extra_values
+        if lower > cardinality:
+            raise generation_error(
+                "Collection size exceeds the number of distinct valid values",
+                code="impossible_collection_size",
+                collection=collection,
+                requested_size=lower,
+                cardinality=cardinality,
+            )
+        upper = min(upper, cardinality)
+    return lower, upper
+
+
+def collection_retry_error(
+    *, collection: str, requested_size: int, generated_size: int, attempts: int
+) -> GenerationError:
+    return generation_error(
+        "Could not fill collection with distinct valid values",
+        code="collection_retry_exhausted",
+        collection=collection,
+        requested_size=requested_size,
+        generated_size=generated_size,
+        attempts=attempts,
+    )
+
+
+def is_hashable(value: Any) -> bool:
+    try:
+        hash(value)
+        return True
+    except TypeError:
+        return False
+
+
+def generate_collection_item(
+    ctx: GenerationContext,
+    item_semantic: FieldSemantics,
+    item_nested_model: ResolvedModel | None,
+    violations: tuple[ViolationType, ...] | None,
+) -> Any:
+    from ..orchestration import generate_semantic_value
+
+    return generate_semantic_value(ctx, item_semantic, item_nested_model, violations)

conformly-0.7.4/src/conformly/_internal/generator/types/dictionaries.py

@@ -0,0 +1,137 @@
+from typing import Any
+
+from .._errors import generation_error
+from ..context import GenerationContext
+from ._utils import (
+    calculate_valid_collection_range,
+    collection_retry_error,
+    generate_collection_item,
+    is_hashable,
+    unique_collection_range,
+)
+
+from conformly._internal.planner.model import CollectionTarget
+from conformly._internal.resolver.semantics import DictSemantic
+from conformly._internal.types import UNSET, ViolationType
+
+
+def generate_value(
+    ctx: GenerationContext,
+    semantic: DictSemantic,
+    violation: ViolationType | None = None,
+    *,
+    target: CollectionTarget | None = None,
+) -> dict[Any, Any]:
+    return (
+        _generate_valid_dict(ctx, semantic)
+        if violation is None
+        else _generate_invalid_dict(ctx, semantic, violation, target)
+    )
+
+
+def _generate_valid_dict(
+    ctx: GenerationContext, semantic: DictSemantic
+) -> dict[Any, Any]:
+    min_len, max_len = calculate_valid_collection_range(semantic)
+
+    min_len, max_len = unique_collection_range(
+        min_len, max_len, semantic.key_semantic, collection="dict"
+    )
+    length = ctx.rng.randint(min_len, max_len)
+    return _generate_dict_of_length(ctx, semantic, length)
+
+
+def _generate_dict_of_length(
+    ctx: GenerationContext,
+    semantic: DictSemantic,
+    length: int,
+    violation: ViolationType | None = None,
+    target: CollectionTarget | None = None,
+    target_value: Any = UNSET,
+) -> dict[Any, Any]:
+    result: dict[Any, Any] = {}
+    max_attempts = max(100, length * 20)
+    for _ in range(max_attempts):
+        if len(result) == length:
+            return result
+        is_target = target is not None and len(result) == target.index
+        key_violation = (
+            (violation,)
+            if is_target
+            and target is not None
+            and target.side == "key"
+            and violation is not None
+            else None
+        )
+        value_violation = (
+            (violation,)
+            if is_target
+            and target is not None
+            and target.side == "value"
+            and violation is not None
+            else None
+        )
+        key = generate_collection_item(ctx, semantic.key_semantic, None, key_violation)
+        if not is_hashable(key) or key in result:
+            continue
+        result[key] = (
+            target_value
+            if is_target and target_value is not UNSET
+            else generate_collection_item(
+                ctx,
+                semantic.value_semantic,
+                semantic.value_nested_model,
+                value_violation,
+            )
+        )
+    if len(result) == length:
+        return result
+    raise collection_retry_error(
+        collection="dict",
+        requested_size=length,
+        generated_size=len(result),
+        attempts=max_attempts,
+    )
+
+
+def _generate_invalid_dict(
+    ctx: GenerationContext,
+    semantic: DictSemantic,
+    violation: ViolationType,
+    target: CollectionTarget | None,
+) -> dict[Any, Any]:
+    min_len, max_len = calculate_valid_collection_range(semantic)
+    if violation == ViolationType.TOO_LESS_ITEMS:
+        lower = semantic.length_range.min_length if semantic.length_range else min_len
+        length = max(0, lower - 1)
+        unique_collection_range(
+            length, length, semantic.key_semantic, collection="dict"
+        )
+        return _generate_dict_of_length(ctx, semantic, length)
+    if violation == ViolationType.TOO_MANY_ITEMS:
+        length = max_len + 1
+        unique_collection_range(
+            length, length, semantic.key_semantic, collection="dict"
+        )
+        return _generate_dict_of_length(ctx, semantic, length)
+    if target is None or target.side not in ("key", "value"):
+        raise generation_error(
+            "Dictionary violation requires a planned key or value target",
+            code="missing_collection_target",
+        )
+    min_len, max_len = unique_collection_range(
+        min_len,
+        max_len,
+        semantic.key_semantic,
+        collection="dict",
+        extra_values=1 if target.side == "key" else 0,
+    )
+    length = ctx.rng.randint(min_len, max_len)
+    if not 0 <= target.index < length:
+        raise generation_error(
+            "Dictionary target is outside collection",
+            code="invalid_collection_target",
+            index=target.index,
+            size=length,
+        )
+    return _generate_dict_of_length(ctx, semantic, length, violation, target)