conformly 0.7.0__tar.gz → 0.7.2__tar.gz

{conformly-0.7.0/src/conformly.egg-info → conformly-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conformly
-Version: 0.7.0
+Version: 0.7.2
 Summary: Generate valid & invalid test data from your typed schemas
 Author-email: Nikita Shabanov <nik.shabanov2024@gmail.com>
 License: MIT
@@ -71,6 +71,7 @@ No factories, no hardcoded fixtures, no drift when schema changes.
 - [User Cases](#use-cases)
 - [Nested Models](#nested-models)
 - [Collections](#collections)
+- [Experimental](#experimental)
 - [Development](#development)
 - [Changelog](#changelog)
 - [License](#license)
@@ -242,8 +243,8 @@ path("profile.name").violate(V.PATTERN_MISMATCH)
 - `"first"` - violate the first constrained field (for `case`) or take the first N constrained fields (for `cases`)
 - `"all_violations"` - generate one invalid case per every available violations including constraints, structural and type violations (ignores count)
 - `"overrides"` - default values for fields in current generation
-> If a field is selected for invalidation → override is ignored
-> Otherwise → override is applied
+> Note: If a field is selected for invalidation → override is ignored.
+> Otherwise → override is applied.
 ```python
 overrides=[
     path(User, lambda u: u.full_name).set("Amogus"),
@@ -560,6 +561,24 @@ case(Model)
 
 This ensures consistent output format (list) while preserving uniqueness guarantees.
 
+### Tuple support
+
+Fixed tuples and variadic tuples (`tuple[T, ...]`) are generated in their declared
+order. Element annotations and nested models are handled independently:
+
+```python
+@dataclass
+class Event:
+    point: tuple[float, float]
+    labels: tuple[str, ...]
+
+case(Event, valid=True)
+# -> {"point": (1.2, 3.4), "labels": ("abc", "def")}
+```
+
+For invalid generation, a constrained tuple element is selected and invalidated
+without changing the other elements.
+
 ### Dict support
 
 `conformly` supports generation of `dict[K, V]`, where K must be a hashable type (`str` or `Enum`) and `V` can be any supported type (primitives, nested models, etc.).
@@ -606,6 +625,31 @@ invalid = case(Inventory, valid=False, strategy=path("products").violate(V.TOO_S
 - Uniqueness for non-hashable elements (e.g., dicts) is best-effort (based on structural comparison fallback)
 - Dictionary keys are restricted to `str` and `Enum` types; complex objects as keys are not supported
 
+## Experimental
+
+> APIs in this section are experimental and may change in future minor releases.
+
+### Tracing
+
+`Tracer` captures metadata about case generation, making it easier to debug, reproduce, and report generated test cases.
+
+```python
+from conformly import case, Email
+from conformly.tracer import Tracer
+
+tracer = Tracer()
+
+payload = case(User, valid=False, tracer=tracer)
+
+trace = tracer.build()
+
+print(trace.target_path)
+print(trace.generated_value)
+print(trace.seed)
+```
+
+The trace includes generation metadata such as the target path, generated value, violation type, random seed, and value source.
+
 
 ## Development
 

{conformly-0.7.0 → conformly-0.7.2}/README.md

@@ -38,6 +38,7 @@ No factories, no hardcoded fixtures, no drift when schema changes.
 - [User Cases](#use-cases)
 - [Nested Models](#nested-models)
 - [Collections](#collections)
+- [Experimental](#experimental)
 - [Development](#development)
 - [Changelog](#changelog)
 - [License](#license)
@@ -209,8 +210,8 @@ path("profile.name").violate(V.PATTERN_MISMATCH)
 - `"first"` - violate the first constrained field (for `case`) or take the first N constrained fields (for `cases`)
 - `"all_violations"` - generate one invalid case per every available violations including constraints, structural and type violations (ignores count)
 - `"overrides"` - default values for fields in current generation
-> If a field is selected for invalidation → override is ignored
-> Otherwise → override is applied
+> Note: If a field is selected for invalidation → override is ignored.
+> Otherwise → override is applied.
 ```python
 overrides=[
     path(User, lambda u: u.full_name).set("Amogus"),
@@ -527,6 +528,24 @@ case(Model)
 
 This ensures consistent output format (list) while preserving uniqueness guarantees.
 
+### Tuple support
+
+Fixed tuples and variadic tuples (`tuple[T, ...]`) are generated in their declared
+order. Element annotations and nested models are handled independently:
+
+```python
+@dataclass
+class Event:
+    point: tuple[float, float]
+    labels: tuple[str, ...]
+
+case(Event, valid=True)
+# -> {"point": (1.2, 3.4), "labels": ("abc", "def")}
+```
+
+For invalid generation, a constrained tuple element is selected and invalidated
+without changing the other elements.
+
 ### Dict support
 
 `conformly` supports generation of `dict[K, V]`, where K must be a hashable type (`str` or `Enum`) and `V` can be any supported type (primitives, nested models, etc.).
@@ -573,6 +592,31 @@ invalid = case(Inventory, valid=False, strategy=path("products").violate(V.TOO_S
 - Uniqueness for non-hashable elements (e.g., dicts) is best-effort (based on structural comparison fallback)
 - Dictionary keys are restricted to `str` and `Enum` types; complex objects as keys are not supported
 
+## Experimental
+
+> APIs in this section are experimental and may change in future minor releases.
+
+### Tracing
+
+`Tracer` captures metadata about case generation, making it easier to debug, reproduce, and report generated test cases.
+
+```python
+from conformly import case, Email
+from conformly.tracer import Tracer
+
+tracer = Tracer()
+
+payload = case(User, valid=False, tracer=tracer)
+
+trace = tracer.build()
+
+print(trace.target_path)
+print(trace.generated_value)
+print(trace.seed)
+```
+
+The trace includes generation metadata such as the target path, generated value, violation type, random seed, and value source.
+
 
 ## Development
 

{conformly-0.7.0 → conformly-0.7.2}/pyproject.toml

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

{conformly-0.7.0 → conformly-0.7.2}/src/conformly/_internal/api/case.py

@@ -7,6 +7,7 @@ from .path import PathSelector
 from conformly._internal.generator.context import create_context
 from conformly._internal.generator.orchestration import generate_invalid, generate_valid
 from conformly._internal.parser import ModelSpec
+from conformly._internal.tracer import Tracer
 from conformly._internal.types import CaseStrategy
 
 
@@ -18,6 +19,7 @@ def case(
     strategy: CaseStrategy | PathSelector = "first",
     overrides: list[PathSelector] | None = None,
     allow_type_mismatch: bool = False,
+    tracer: Tracer | None = None,
 ) -> dict[str, Any]:
     """
     Generate a single example of a model.
@@ -79,6 +81,12 @@ def case(
     _overrides = normalize_overrides(model, overrides)
 
     if valid:
+        if tracer:
+            raise api_error(
+                "Tracing is only available for invalid generation",
+                code="tracing_for_valid",
+            )
+
         if allow_type_mismatch:
             raise api_error(
                 "Type mismatch is only available for invalid generation",
@@ -103,6 +111,9 @@ def case(
             strategy=strategy,
         )
 
+    if tracer and isinstance(strategy, PathSelector):
+        tracer.set_target_path(strategy.raw_path)
+
     task = plan_tasks(
         model,
         ctx=ctx,
@@ -111,4 +122,4 @@ def case(
         count=1,
         allow_type_mismatch=allow_type_mismatch,
     )[0]
-    return generate_invalid(ctx, model, task, _overrides)
+    return generate_invalid(ctx, model, task, _overrides, tracer)

{conformly-0.7.0 → conformly-0.7.2}/src/conformly/_internal/generator/orchestration.py

@@ -10,7 +10,8 @@ from conformly._internal.resolver import (
     ResolvedModel,
     create_minimal_semantic,
 )
-from conformly._internal.resolver.semantics import ListSemantic
+from conformly._internal.resolver.semantics import ListSemantic, TupleSemantic
+from conformly._internal.tracer import Tracer, ValueSource
 from conformly._internal.types import UNSET, FieldKind, FieldPath, ViolationType
 
 
@@ -30,7 +31,10 @@ def generate_invalid(
     model: ResolvedModel,
     task: PlannedTask,
     overrides: dict[FieldPath, Any] | None = None,
+    tracer: Tracer | None = None,
 ) -> dict[str, Any]:
+    if tracer:
+        tracer.set_seed(ctx.seed)
     return _built_dict_with_violations(
         ctx=ctx,
         model=model,
@@ -38,6 +42,7 @@ def generate_invalid(
         depth=0,
         violations=task.allowed_violations,
         overrides=overrides,
+        tracer=tracer,
     )
 
 
@@ -48,6 +53,7 @@ def _built_dict_with_violations(
     depth: int,
     violations: tuple[ViolationType, ...],
     overrides: dict[FieldPath, Any] | None = None,
+    tracer: Tracer | None = None,
 ) -> dict[str, Any]:
     result: dict[str, Any] = {}
     target_index = target_path[depth]
@@ -66,7 +72,7 @@ def _built_dict_with_violations(
 
     for i in range(0, target_index):
         field = fields[i]
-        result[field.name] = generate_field(ctx, field, None, overrides)
+        result[field.name] = generate_field(ctx, field, None, overrides, tracer)
 
     if target_index < total_fields:
         field = fields[target_index]
@@ -79,7 +85,7 @@ def _built_dict_with_violations(
                     field=field.name,
                 )
 
-            value = generate_field(ctx, field, violations, overrides)
+            value = generate_field(ctx, field, violations, overrides, tracer)
             if value is not UNSET:
                 result[field.name] = value
 
@@ -98,18 +104,19 @@ def _built_dict_with_violations(
                 depth=depth + 1,
                 violations=violations,
                 overrides=overrides,
+                tracer=tracer,
             )
 
     else:
         for i, field in enumerate(fields):
-            result[field.name] = generate_field(ctx, field)
+            result[field.name] = generate_field(ctx, field, tracer=tracer)
 
         key, value = _generate_extra_field_value(ctx)
         result[key] = value
 
     for i in range(target_index + 1, total_fields):
         field = fields[i]
-        result[field.name] = generate_field(ctx, field)
+        result[field.name] = generate_field(ctx, field, tracer=tracer)
 
     return result
 
@@ -119,38 +126,69 @@ def generate_field(
     field: ResolvedField,
     violations: tuple[ViolationType, ...] | None = None,
     overrides: dict[FieldPath, Any] | None = None,
+    tracer: Tracer | None = None,
 ) -> Any:
     if violations is None:
         if overrides and field.path in overrides:
-            return overrides[field.path]
+            value = overrides[field.path]
+            if tracer:
+                tracer.set_value_source(ValueSource.OVERRIDDEN)
+                tracer.set_generated_value(value)
+            return value
 
         if field.nullable:
             return None
 
         if field.default is not UNSET:
+            if tracer:
+                tracer.set_value_source(ValueSource.MODEL_DEFAULT)
+
             default = field.default
             if callable(default):
+                if tracer:
+                    tracer.set_generated_value(default())
                 return default()
 
-            return field.default
+            if tracer:
+                tracer.set_generated_value(default())
+
+            return default
 
-        if field.nested_model and not isinstance(field.semantic, ListSemantic):
+        if field.nested_model and not isinstance(
+            field.semantic, (ListSemantic, TupleSemantic)
+        ):
             return generate_valid(ctx, field.nested_model, overrides)
 
     violation = _choose_violation(violations)
 
+    if tracer:
+        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)
-        return get_generator(mismatch_kind).generate_value(ctx, mismatch_semantic, None)
+        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
 
-    return get_generator(field.semantic.kind).generate_value(
+    value = get_generator(field.semantic.kind).generate_value(
         ctx, field.semantic, violation
     )
 
+    if tracer:
+        tracer.set_generated_value(value)
+
+    return value
+
 
 def _choose_violation(
     violations: tuple[ViolationType, ...] | None,

{conformly-0.7.0 → conformly-0.7.2}/src/conformly/_internal/generator/registry.py

@@ -12,6 +12,7 @@ from .types import (
     ipvany,
     list,
     string,
+    tuple,
     url,
     uuid,
 )
@@ -30,6 +31,7 @@ _GENERATORS: dict[FieldKind, TypeGeneratorProtocol] = {
     FieldKind.IPvAny: ipvany,
     FieldKind.LIST: list,
     FieldKind.DICT: dictionaries,
+    FieldKind.TUPLE: tuple,
     FieldKind.UUID: uuid,
     FieldKind.URL: url,
     FieldKind.HTTPURL: url,
@@ -51,6 +53,7 @@ _MISMATCH_MAPPING: dict[FieldKind, FieldKind] = {
     FieldKind.UUID: FieldKind.FLOAT,
     FieldKind.URL: FieldKind.FLOAT,
     FieldKind.HTTPURL: FieldKind.INTEGER,
+    FieldKind.TUPLE: FieldKind.INTEGER,
 }
 
 

conformly-0.7.2/src/conformly/_internal/generator/types/tuple.py

@@ -0,0 +1,93 @@
+from typing import Any
+
+from ..context import GenerationContext
+from ._utils import generate_collection_item
+
+from conformly._internal.resolver.semantics import TupleSemantic
+from conformly._internal.types import ViolationType
+from conformly.exceptions import PlanningError
+
+
+def _supports_violation(semantic: Any, violation: ViolationType) -> bool:
+    from conformly._internal.planner.field import _define_allowed_violation_types
+
+    try:
+        return violation in _define_allowed_violation_types(semantic)
+    except PlanningError:
+        return False
+
+
+def generate_value(
+    ctx: GenerationContext,
+    semantic: TupleSemantic,
+    violation: ViolationType | None = None,
+) -> tuple[Any, ...]:
+    if violation is None:
+        return _generate_valid_tuple(ctx, semantic)
+
+    return _generate_invalid_tuple(ctx, semantic, violation)
+
+
+def _generate_valid_tuple(
+    ctx: GenerationContext, semantic: TupleSemantic
+) -> tuple[Any, ...]:
+    if not semantic.is_variadic:
+        elements = semantic.elements_semantics
+    else:
+        min_len = semantic.length_range.min_length if semantic.length_range else 1
+        max_len = semantic.length_range.max_length if semantic.length_range else 3
+        length = ctx.rng.randint(min_len or 1, max_len or 3)
+        elements = semantic.elements_semantics * length
+
+    return tuple(
+        generate_collection_item(ctx, item_semantic, nested_model, None)
+        for item_semantic, nested_model in elements
+    )
+
+
+def _generate_invalid_tuple(
+    ctx: GenerationContext, semantic: TupleSemantic, violation: ViolationType
+) -> tuple[Any, ...]:
+    if violation in (ViolationType.TOO_LESS_ITEMS, ViolationType.TOO_MANY_ITEMS):
+        if not semantic.is_variadic:
+            return _generate_valid_tuple(ctx, semantic)
+
+        min_len = semantic.length_range.min_length if semantic.length_range else 1
+        max_len = semantic.length_range.max_length if semantic.length_range else 3
+        length = (
+            max(0, min_len - 1)
+            if violation == ViolationType.TOO_LESS_ITEMS
+            else (max_len or 3) + 1
+        )
+        return tuple(
+            generate_collection_item(ctx, *semantic.elements_semantics[0], None)
+            for _ in range(length)
+        )
+
+    if semantic.is_variadic:
+        min_len = semantic.length_range.min_length if semantic.length_range else 1
+        max_len = semantic.length_range.max_length if semantic.length_range else 3
+        length = ctx.rng.randint(min_len or 1, max_len or 3)
+        elements = semantic.elements_semantics * length
+    else:
+        elements = semantic.elements_semantics
+
+    candidates = [
+        i
+        for i, (item_semantic, _) in enumerate(elements)
+        if _supports_violation(item_semantic, violation)
+    ]
+    violate_idx = (
+        ctx.rng.choice(candidates)
+        if candidates
+        else ctx.rng.randint(0, len(elements) - 1)
+    )
+    return tuple(
+        generate_collection_item(
+            ctx,
+            item_semantic,
+            nested_model,
+            (violation,) if i == violate_idx else None,
+        )
+        for i, (item_semantic, nested_model) in enumerate(elements)
+    )

{conformly-0.7.0 → conformly-0.7.2}/src/conformly/_internal/parser/core/field.py

@@ -2,7 +2,14 @@ from collections.abc import Callable
 from typing import Any
 
 from ..extractors.constraints import split_collection_constraints
-from ..extractors.types import DictNode, ListNode, ScalarNode, TypeNode, normalize_type
+from ..extractors.types import (
+    DictNode,
+    ListNode,
+    ScalarNode,
+    TupleNode,
+    TypeNode,
+    normalize_type,
+)
 from ..models import ElementSpec, FieldSpec
 
 from conformly._internal.constraints import Constraint
@@ -41,6 +48,22 @@ def build_field_spec(
                 nullable=node.nullable,
             )
 
+        case TupleNode():
+            element_constraints, collection_constraints = split_collection_constraints(
+                external_constraints
+            )
+
+            return FieldSpec(
+                name=name,
+                collection_type=node.origin,
+                collection_constraints=(*node.constraints, *collection_constraints),
+                items=tuple(
+                    resolve_element(i, name, element_constraints) for i in node.items
+                ),
+                default=default,
+                nullable=node.nullable,
+            )
+
         case DictNode():
             return FieldSpec(
                 name=name,

{conformly-0.7.0 → conformly-0.7.2}/src/conformly/_internal/parser/extractors/types.py

@@ -37,6 +37,16 @@ class ListNode:
     item: "TypeNode"
 
 
+@dataclass(frozen=True, slots=True)
+class TupleNode:
+    kind: Literal["tuple"]
+    runtime_type: Any
+    origin: type
+    nullable: bool
+    constraints: tuple[Constraint, ...]
+    items: tuple["TypeNode", ...]
+
+
 @dataclass(frozen=True, slots=True)
 class DictNode:
     kind: Literal["dict"]
@@ -47,7 +57,7 @@ class DictNode:
     value: "TypeNode"
 
 
-TypeNode = ScalarNode | ListNode | DictNode
+TypeNode = ScalarNode | ListNode | DictNode | TupleNode
 
 
 def normalize_type(field_type: Any, field_name: str) -> TypeNode:
@@ -116,6 +126,32 @@ def _build_node(
             item=item,
         )
 
+    if origin is tuple:
+        if not args:
+            raise SchemaError(
+                f"Field '{field_name}': '{origin.__name__}' must be parameterized",
+                context={
+                    "code": "empty_collection",
+                    "field_name": field_name,
+                    "field_type": repr(t),
+                },
+            )
+        items: list[TypeNode] = []
+        if len(args) == 2 and args[1] is Ellipsis:
+            items.append(normalize_type(args[0], field_name))
+        else:
+            for i, _ in enumerate(args):
+                item = normalize_type(args[i], field_name)
+                items.append(item)
+        return TupleNode(
+            kind="tuple",
+            runtime_type=origin,
+            origin=origin,
+            nullable=nullable,
+            constraints=constraints,
+            items=tuple(items),
+        )
+
     if origin is dict:
         if len(args) != 2:
             raise SchemaError(

{conformly-0.7.0 → conformly-0.7.2}/src/conformly/_internal/parser/models.py

@@ -23,6 +23,7 @@ class FieldSpec:
     collection_type: type | None = None
     collection_constraints: tuple[Constraint, ...] = ()
     item: ElementSpec | None = None
+    items: tuple[ElementSpec, ...] | None = None
     key: ElementSpec | None = None
     value: ElementSpec | None = None
     nullable: bool = False
@@ -38,6 +39,7 @@ class FieldSpec:
         return (
             (self.element is not None and len(self.element.constraints) != 0)
             or (self.item is not None and len(self.item.constraints) != 0)
+            or any(len(item.constraints) != 0 for item in (self.items or ()))
             or (self.key is not None and len(self.key.constraints) != 0)
             or (self.value is not None and len(self.value.constraints) != 0)
             or len(self.collection_constraints) != 0
@@ -47,6 +49,7 @@ class FieldSpec:
         return (
             (self.element is not None and self.element.nested_model is not None)
             or (self.item is not None and self.item.nested_model is not None)
+            or any(item.nested_model is not None for item in (self.items or ()))
             or (self.key is not None and self.key.nested_model is not None)
             or (self.value is not None and self.value.nested_model is not None)
         )

{conformly-0.7.0 → conformly-0.7.2}/src/conformly/_internal/planner/field.py

@@ -11,6 +11,7 @@ from conformly._internal.resolver.semantics import (
     NumericSemantic,
     ObjectSemantic,
     StringSemantic,
+    TupleSemantic,
     UUIDSemantic,
 )
 from conformly._internal.resolver.semantics.dict import DictSemantic
@@ -123,6 +124,9 @@ def _define_allowed_violation_types(
         case DictSemantic(kind=FieldKind.DICT):
             violations = _define_dict_violations(semantic)
 
+        case TupleSemantic(kind=FieldKind.TUPLE):
+            violations = _define_tuple_violations(semantic)
+
         case EnumSemantic(kind=FieldKind.ENUM):
             violations = [ViolationType.NOT_ALLOWED_VALUE]
 
@@ -252,3 +256,20 @@ def _safe_define(semantic: FieldSemantics) -> list[ViolationType]:
         return list(_define_allowed_violation_types(semantic, False, False))
     except PlanningError:
         return []
+
+
+def _define_tuple_violations(semantic: TupleSemantic) -> list[ViolationType]:
+    result: list[ViolationType] = []
+
+    if semantic.is_variadic and semantic.length_range is not None:
+        if semantic.length_range.min_length > 0:
+            result.append(ViolationType.TOO_LESS_ITEMS)
+        if semantic.length_range.max_length is not None:
+            result.append(ViolationType.TOO_MANY_ITEMS)
+
+    for item_semantic, _ in semantic.elements_semantics:
+        for violation in _safe_define(item_semantic):
+            if violation not in result:
+                result.append(violation)
+
+    return result