conformly 0.7.4__tar.gz → 0.9.0__tar.gz

conformly-0.9.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: conformly
+Version: 0.9.0
+Summary: Generate valid & invalid test data from your typed schemas
+Author-email: Nikita Shabanov <nik.shabanov2024@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/nashabanov/conformly
+Project-URL: Repository, https://github.com/nashabanov/conformly.git
+Project-URL: Issues, https://github.com/nashabanov/conformly/issues
+Keywords: testing,fixtures,test-data,dataclasses,validation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rstr>=3.2.2
+Provides-Extra: pydantic
+Requires-Dist: pydantic<3.0.0,>=2.0.0; extra == "pydantic"
+Requires-Dist: email-validator>=2.0.0; extra == "pydantic"
+Provides-Extra: attrs
+Requires-Dist: attrs>=23.0.0; extra == "attrs"
+Provides-Extra: all
+Requires-Dist: pydantic<3.0.0,>=2.0.0; extra == "all"
+Requires-Dist: email-validator>=2.0.0; extra == "all"
+Requires-Dist: attrs>=23.0.0; extra == "all"
+Dynamic: license-file
+
+# conformly
+
+[![CI](https://github.com/nashabanov/conformly/actions/workflows/ci.yaml/badge.svg)](https://github.com/nashabanov/conformly/actions/workflows/ci.yaml)
+[![codecov](https://codecov.io/github/nashabanov/conformly/graph/badge.svg?branch=main)](https://codecov.io/github/nashabanov/conformly)
+[![PyPI](https://img.shields.io/pypi/v/conformly.svg)](https://pypi.org/project/conformly/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/conformly.svg)](https://pypi.org/project/conformly/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Declarative test data generator for Python.**
+
+Define constraints once in type annotations — generate both valid and minimal invalid test data automatically.
+No factories, no hardcoded fixtures, no drift when schema changes.
+
+Conformly turns typed schemas into dictionaries for fixtures and validation tests.
+Use the same schema for happy-path payloads and targeted negative cases.
+
+## Key capabilities
+
+- **Constraint-driven generation** from type annotations and model metadata.
+- **Minimal invalid cases** targeting one field and a selected violation.
+- **Schema as the single source of truth** for test data.
+- Dataclasses and TypedDicts, with optional Pydantic and attrs integrations.
+- Nested models, collections, reproducible seeds, and field overrides.
+
+## Installation
+
+Requires Python 3.12 or newer.
+
+```bash
+pip install conformly
+# Optional integrations:
+pip install 'conformly[pydantic]'
+pip install 'conformly[attrs]'
+```
+
+## Quickstart
+
+```python
+from dataclasses import dataclass
+from typing import Annotated
+
+from conformly import GreaterOrEqual, MaxLength, MinLength, V, case, path
+
+
+@dataclass
+class CreateUser:
+    username: Annotated[str, MinLength(3), MaxLength(32)]
+    age: Annotated[int, GreaterOrEqual(18)]
+
+
+payload = case(CreateUser)
+assert 3 <= len(payload["username"]) <= 32
+assert payload["age"] >= 18
+
+invalid = case(
+    CreateUser, valid=False, target=path("age").violate(V.BELOW_MIN)
+)
+assert invalid["age"] < 18
+assert 3 <= len(invalid["username"]) <= 32
+```
+
+Results are dictionaries, not model instances. Invalid generation targets one
+field; only the selected violation is guaranteed on that target. Defaults and
+overrides are trusted rather than validated. See the
+[invalid generation contract](https://github.com/nashabanov/conformly/blob/main/docs/strategies.md#invalid-generation-contract).
+
+## Documentation and examples
+
+Start with [Getting started](https://github.com/nashabanov/conformly/blob/main/docs/getting-started.md), browse the
+[documentation index](https://github.com/nashabanov/conformly/blob/main/docs/README.md), or run the [examples](https://github.com/nashabanov/conformly/blob/main/examples/README.md).
+The [API reference](https://github.com/nashabanov/conformly/blob/main/docs/api-reference.md) lists parameters and defaults.
+
+## Development and contributing
+
+See [CONTRIBUTING.md](https://github.com/nashabanov/conformly/blob/main/CONTRIBUTING.md) for setup and checks, and
+[CHANGELOG.md](https://github.com/nashabanov/conformly/blob/main/CHANGELOG.md) for release notes and migration guidance.
+
+## License
+
+MIT — see [LICENSE](https://github.com/nashabanov/conformly/blob/main/LICENSE).

conformly-0.9.0/README.md

@@ -0,0 +1,80 @@
+# conformly
+
+[![CI](https://github.com/nashabanov/conformly/actions/workflows/ci.yaml/badge.svg)](https://github.com/nashabanov/conformly/actions/workflows/ci.yaml)
+[![codecov](https://codecov.io/github/nashabanov/conformly/graph/badge.svg?branch=main)](https://codecov.io/github/nashabanov/conformly)
+[![PyPI](https://img.shields.io/pypi/v/conformly.svg)](https://pypi.org/project/conformly/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/conformly.svg)](https://pypi.org/project/conformly/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Declarative test data generator for Python.**
+
+Define constraints once in type annotations — generate both valid and minimal invalid test data automatically.
+No factories, no hardcoded fixtures, no drift when schema changes.
+
+Conformly turns typed schemas into dictionaries for fixtures and validation tests.
+Use the same schema for happy-path payloads and targeted negative cases.
+
+## Key capabilities
+
+- **Constraint-driven generation** from type annotations and model metadata.
+- **Minimal invalid cases** targeting one field and a selected violation.
+- **Schema as the single source of truth** for test data.
+- Dataclasses and TypedDicts, with optional Pydantic and attrs integrations.
+- Nested models, collections, reproducible seeds, and field overrides.
+
+## Installation
+
+Requires Python 3.12 or newer.
+
+```bash
+pip install conformly
+# Optional integrations:
+pip install 'conformly[pydantic]'
+pip install 'conformly[attrs]'
+```
+
+## Quickstart
+
+```python
+from dataclasses import dataclass
+from typing import Annotated
+
+from conformly import GreaterOrEqual, MaxLength, MinLength, V, case, path
+
+
+@dataclass
+class CreateUser:
+    username: Annotated[str, MinLength(3), MaxLength(32)]
+    age: Annotated[int, GreaterOrEqual(18)]
+
+
+payload = case(CreateUser)
+assert 3 <= len(payload["username"]) <= 32
+assert payload["age"] >= 18
+
+invalid = case(
+    CreateUser, valid=False, target=path("age").violate(V.BELOW_MIN)
+)
+assert invalid["age"] < 18
+assert 3 <= len(invalid["username"]) <= 32
+```
+
+Results are dictionaries, not model instances. Invalid generation targets one
+field; only the selected violation is guaranteed on that target. Defaults and
+overrides are trusted rather than validated. See the
+[invalid generation contract](https://github.com/nashabanov/conformly/blob/main/docs/strategies.md#invalid-generation-contract).
+
+## Documentation and examples
+
+Start with [Getting started](https://github.com/nashabanov/conformly/blob/main/docs/getting-started.md), browse the
+[documentation index](https://github.com/nashabanov/conformly/blob/main/docs/README.md), or run the [examples](https://github.com/nashabanov/conformly/blob/main/examples/README.md).
+The [API reference](https://github.com/nashabanov/conformly/blob/main/docs/api-reference.md) lists parameters and defaults.
+
+## Development and contributing
+
+See [CONTRIBUTING.md](https://github.com/nashabanov/conformly/blob/main/CONTRIBUTING.md) for setup and checks, and
+[CHANGELOG.md](https://github.com/nashabanov/conformly/blob/main/CHANGELOG.md) for release notes and migration guidance.
+
+## License
+
+MIT — see [LICENSE](https://github.com/nashabanov/conformly/blob/main/LICENSE).

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

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

{conformly-0.7.4 → conformly-0.9.0}/src/conformly/__init__.py

@@ -18,7 +18,7 @@ from ._internal.constraints import (
     Pattern,
     UniqueItems,
 )
-from ._internal.fields import Email, IPv4, IPv6, IPvAny
+from ._internal.fields import Email, HttpUrl, IPv4, IPv6, IPvAny, Url
 from ._internal.types import ViolationType as V
 from .exceptions import ConformlyError
 
@@ -27,6 +27,7 @@ __all__ = [
     "Email",
     "GreaterOrEqual",
     "GreaterThan",
+    "HttpUrl",
     "IPv4",
     "IPv6",
     "IPvAny",
@@ -40,6 +41,7 @@ __all__ = [
     "OneOf",
     "Pattern",
     "UniqueItems",
+    "Url",
     "V",
     "case",
     "cases",

conformly-0.9.0/src/conformly/_internal/api/_utils.py

@@ -0,0 +1,162 @@
+from typing import Any
+
+from ._errors import api_error
+from .path import PathSelector
+
+from conformly._internal.generator import GenerationContext
+from conformly._internal.parser import ModelSpec, parse_model
+from conformly._internal.planner import PlannedTask, plan_violation_task, select_paths
+from conformly._internal.resolver import ResolvedModel, resolve_model
+from conformly._internal.types import CasesStrategy, FieldPath
+
+
+def ensure_model_or_spec(
+    model_or_spec: ModelSpec | ResolvedModel | type,
+) -> ResolvedModel:
+    if isinstance(model_or_spec, ResolvedModel):
+        return model_or_spec
+
+    if isinstance(model_or_spec, ModelSpec):
+        return resolve_model(model_or_spec)
+
+    return resolve_model(parse_model(model_or_spec))
+
+
+def normalize_overrides(
+    model: ResolvedModel, overrides: list[PathSelector] | None
+) -> dict[FieldPath, Any] | None:
+    if overrides is None:
+        return None
+
+    normalized_overrides: dict[FieldPath, Any] = {}
+
+    for v in overrides:
+        if (
+            not isinstance(v, PathSelector)
+            or not v.has_override
+            or v.forced_violation is not None
+        ):
+            raise api_error(
+                "Overrides must be selectors configured with .set(value)",
+                code="invalid_override_selector",
+                path=v.raw_path if isinstance(v, PathSelector) else None,
+            )
+        if v.raw_path not in model.name_to_path:
+            raise api_error(
+                "Override path not found",
+                code="invalid_override_path",
+                path=v.raw_path,
+                available=list(model.name_to_path),
+            )
+        path = model.name_to_path[v.raw_path]
+        normalized_overrides[path] = v.override
+
+    return normalized_overrides
+
+
+def validate_selection(
+    *,
+    valid: bool,
+    strategy: CasesStrategy,
+    target: PathSelector | None,
+    allow_all: bool,
+    count: int = 1,
+) -> None:
+    if valid and strategy != "first":
+        raise api_error(
+            "Strategy selection is only applicable when valid=False",
+            code="invalid_strategy_for_valid",
+            strategy=strategy,
+        )
+    supported = (
+        ("first", "random", "all", "all_violations")
+        if allow_all
+        else ("first", "random")
+    )
+    if not isinstance(strategy, str) or strategy not in supported:
+        raise api_error(
+            "Unsupported strategy",
+            code="unsupported_strategy",
+            function="cases" if allow_all else "case",
+            strategy=strategy,
+            available=list(supported),
+        )
+    if target is not None:
+        if not isinstance(target, PathSelector):
+            raise api_error(
+                "Target must be a PathSelector; use path('field')",
+                code="invalid_target",
+            )
+        if valid:
+            raise api_error(
+                "Target selection is only applicable when valid=False",
+                code="invalid_target_for_valid",
+                target=target.raw_path,
+            )
+        if strategy != "first":
+            raise api_error(
+                "Explicit targets require strategy='first'",
+                code="invalid_strategy_for_target",
+                strategy=strategy,
+                target=target.raw_path,
+            )
+        if count != 1:
+            raise api_error(
+                "Explicit targets require count=1",
+                code="invalid_count_for_target",
+                count=count,
+                target=target.raw_path,
+            )
+
+
+def plan_tasks(
+    model: ResolvedModel,
+    *,
+    ctx: GenerationContext,
+    strategy: CasesStrategy,
+    target: PathSelector | None = None,
+    allow_all: bool,
+    count: int = 1,
+    allow_type_mismatch: bool = False,
+    allow_structural_violations: bool = False,
+    split_by_violations: bool = False,
+) -> list[PlannedTask]:
+    forced_violation = target.forced_violation if target is not None else None
+
+    paths = select_paths(
+        model,
+        ctx=ctx,
+        strategy=strategy,
+        target=target.raw_path if target is not None else None,
+        forced_violation=forced_violation,
+        allow_all=allow_all,
+        count=count,
+        allow_type_mismatch=allow_type_mismatch,
+        allow_structural_violations=allow_structural_violations,
+    )
+
+    if split_by_violations:
+        return [
+            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
+            ).allowed_violations
+        ]
+
+    return [
+        plan_violation_task(
+            model=model,
+            path=path,
+            allow_type_mismatch=allow_type_mismatch,
+            allow_structural_violations=allow_structural_violations,
+            forced_violation=forced_violation,
+        )
+        for path in paths
+    ]

{conformly-0.7.4 → conformly-0.9.0}/src/conformly/_internal/api/case.py

@@ -1,7 +1,12 @@
 from typing import Any
 
 from ._errors import api_error
-from ._utils import ensure_model_or_spec, normalize_overrides, plan_tasks
+from ._utils import (
+    ensure_model_or_spec,
+    normalize_overrides,
+    plan_tasks,
+    validate_selection,
+)
 from .path import PathSelector
 
 from conformly._internal.generator.context import create_context
@@ -16,7 +21,8 @@ def case(
     *,
     valid: bool = True,
     seed: int | None = None,
-    strategy: CaseStrategy | PathSelector = "first",
+    strategy: CaseStrategy = "first",
+    target: PathSelector | None = None,
     overrides: list[PathSelector] | None = None,
     allow_type_mismatch: bool = False,
     tracer: Tracer | None = None,
@@ -52,16 +58,10 @@ def case(
 
             - "random": violate a random constrained field
 
-            - "field_name":
-                violate a specific field using a dotted path
-                (e.g. strategy="user.email")
-
-            - "field_name::violation":
-                violate a specific field with specific type
-                (e.g. strategy="user.profile::below_min")
-
-            - PathSelector DSL:
-                path("user.email").violate(V.TOO_SHORT)
+        target:
+            Optional selector from path("field") or path(Model, lambda m: m.field).
+            Only available with valid=False and strategy="first".
+            Use .violate(V.X) to request an exact violation.
 
         overrides:
             Optional list of `PathSelector` to set field values.
@@ -99,27 +99,22 @@ def case(
                 flag="allow_type_mismatch",
             )
 
-        if strategy != "first":
-            raise api_error(
-                "Strategy selection is only applicable when valid=False",
-                code="invalid_strategy_for_valid",
-                strategy=strategy,
-            )
+    validate_selection(
+        valid=valid,
+        strategy=strategy,
+        target=target,
+        allow_all=False,
+        count=1,
+    )
 
+    if valid:
         return generate_valid(ctx, model, _overrides)
 
-    if strategy == "all":
-        raise api_error(
-            "The 'all' strategy is not supported in 'case()' — use 'cases()' instead",
-            code="unsupported_strategy",
-            function="case",
-            strategy=strategy,
-        )
-
     task = plan_tasks(
         model,
         ctx=ctx,
         strategy=strategy,
+        target=target,
         allow_all=False,
         count=1,
         allow_type_mismatch=allow_type_mismatch,

{conformly-0.7.4 → conformly-0.9.0}/src/conformly/_internal/api/cases.py

@@ -1,8 +1,13 @@
 from typing import Any
 
 from ._errors import api_error
-from ._utils import ensure_model_or_spec, normalize_overrides, plan_tasks
-from .path import PathSelector, parse_strategy_input
+from ._utils import (
+    ensure_model_or_spec,
+    normalize_overrides,
+    plan_tasks,
+    validate_selection,
+)
+from .path import PathSelector
 
 from conformly._internal.generator.context import create_context
 from conformly._internal.generator.orchestration import generate_invalid, generate_valid
@@ -15,7 +20,8 @@ def cases(
     *,
     valid: bool = True,
     seed: int | None = None,
-    strategy: CasesStrategy | PathSelector = "first",
+    strategy: CasesStrategy = "first",
+    target: PathSelector | None = None,
     count: int = 1,
     allow_type_mismatch: bool = False,
     allow_structural_violations: bool = False,
@@ -60,19 +66,13 @@ def cases(
                 generate one invalid case per every available violations
                 including constraints, structural and type violations (ignores count)
 
-            - "field_name":
-                violate a specific field using a dotted path
-                (e.g. strategy="user.email")
-
-            - "field_name::violation":
-                violate a specific field with specific type
-                (e.g. strategy="user.profile::below_min")
-
-            - PathSelector DSL:
-                path("user.email").violate(V.TOO_SHORT)
+        target:
+            Optional selector from path("field") or path(Model, lambda m: m.field).
+            Only available with valid=False and strategy="first".
+            Use .violate(V.X) to request an exact violation.
 
         count:
-            Number of cases to generate (ignored if strategy="all").
+            Number of cases; target requires 1. Enumeration ignores count.
 
         overrides:
             Optional list of `PathSelector` to set field values.
@@ -89,7 +89,7 @@ def cases(
             violations and cases with extra field in each model.
             Structural violations are available only when:
                 - valid=False
-                - strategy="all"
+                - strategy="all" or "all_violations", or an explicit violation
 
     Returns:
         A list of dictionaries.
@@ -122,59 +122,39 @@ def cases(
                 flag="allow_structural_violations",
             )
 
-        if strategy != "first":
-            raise api_error(
-                "Strategy selection is only applicable when valid=False",
-                code="invalid_strategy_for_valid",
-                strategy=strategy,
-            )
+    validate_selection(
+        valid=valid,
+        strategy=strategy,
+        target=target,
+        allow_all=True,
+        count=count,
+    )
 
+    if valid:
         return [generate_valid(ctx, model, _overrides) for _ in range(count)]
 
-    field_strategy, forced_violation = parse_strategy_input(strategy)
-
     if (
         allow_structural_violations
-        and field_strategy not in ("all", "all_violations")
-        and forced_violation is None
+        and strategy not in ("all", "all_violations")
+        and (target is None or target.forced_violation is None)
     ):
         raise api_error(
             "Structural violations require strategy='all', 'all_violations', "
-            "or explicit '::' syntax",
+            "or an explicit violation on target",
             code="invalid_strategy_for_structural",
             strategy=strategy,
         )
 
-    if strategy == "all":
-        tasks = plan_tasks(
-            model,
-            ctx=ctx,
-            strategy="all",
-            allow_all=True,
-            allow_type_mismatch=allow_type_mismatch,
-            allow_structural_violations=allow_structural_violations,
-            split_by_violations=False,
-        )
-
-    elif strategy == "all_violations":
-        tasks = plan_tasks(
-            model,
-            ctx=ctx,
-            strategy="all",
-            allow_all=True,
-            allow_type_mismatch=allow_type_mismatch,
-            allow_structural_violations=allow_structural_violations,
-            split_by_violations=True,
-        )
-
-    else:
-        tasks = plan_tasks(
-            model,
-            ctx=ctx,
-            strategy=strategy,
-            allow_all=False,
-            count=count,
-            allow_type_mismatch=allow_type_mismatch,
-        )
+    tasks = plan_tasks(
+        model,
+        ctx=ctx,
+        strategy="all" if strategy == "all_violations" else strategy,
+        target=target,
+        allow_all=True,
+        count=count,
+        allow_type_mismatch=allow_type_mismatch,
+        allow_structural_violations=allow_structural_violations,
+        split_by_violations=strategy == "all_violations",
+    )
 
     return [generate_invalid(ctx, model, task, _overrides) for task in tasks]

{conformly-0.7.4 → conformly-0.9.0}/src/conformly/_internal/api/path.py

@@ -13,10 +13,11 @@ class PathSelector:
     raw_path: str
     forced_violation: ViolationType | None = None
     override: Any | None = None
+    has_override: bool = False
 
     def set(self, override: Any) -> "PathSelector":
         """Override field value"""
-        return PathSelector(self.raw_path, override=override)
+        return PathSelector(self.raw_path, override=override, has_override=True)
 
     def violate(self, violation: ViolationType) -> "PathSelector":
         """Force violation type"""
@@ -39,7 +40,7 @@ def path[T](
 
     Supports two usage modes:
 
-    1. String mode (simple, backward-compatible):
+    1. String mode (simple):
         path("user.email").violate(V.TOO_SHORT)
         path("bio").violate(V.TOO_LONG)
 
@@ -62,8 +63,8 @@ def path[T](
     Notes:
         - String paths are not validated immediately. Validation occurs during
           the planning stage against the resolved model structure.
-        - Lambda paths require source code availability (.py files). In REPL
-          or Jupyter, use the string mode.
+        - Lambda paths execute against an attribute proxy and work in REPLs
+          and notebooks.
     """
     if isinstance(target, str):
         if expr is not None:
@@ -83,25 +84,3 @@ def path[T](
 
     raw_path = extract_path_from_proxy(expr)
     return PathSelector(raw_path)
-
-
-def parse_strategy_input(
-    strategy: str | PathSelector,
-) -> tuple[str, ViolationType | None]:
-    if isinstance(strategy, PathSelector):
-        return strategy.raw_path, strategy.forced_violation
-
-    if "::" in strategy:
-        field_part, violation_part = strategy.split("::", 1)
-        try:
-            v_type = ViolationType(violation_part)
-            return field_part, v_type
-        except ValueError:
-            available = [v.value for v in ViolationType]
-            raise api_error(
-                f"Unknown violation type '{violation_part}'",
-                code="invalid_violation_type",
-                requested=violation_part,
-                available=available,
-            )
-    return strategy, None