capper 0.4.0__tar.gz → 0.5.0__tar.gz

{capper-0.4.0 → capper-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capper
-Version: 0.4.0
+Version: 0.5.0
 Summary: Semantic, typed wrappers for Faker with automatic Polyfactory integration
 Author-email: Odos Matthews <odosmatthews@gmail.com>
 Project-URL: Documentation, https://github.com/eddiethedean/capper#readme
@@ -160,7 +160,7 @@ Use `-n`/`--count` for the number of rows and `-s`/`--seed` for reproducible out
 
 ## Compatibility
 
-Capper targets **Python 3.10+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. For version ranges, upgrade guidance, and the deprecation policy, see [Compatibility](docs/compatibility.md).
+Capper targets **Python 3.10+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. For version ranges, upgrade guidance, the versioning policy, and the deprecation policy, see [Compatibility](docs/compatibility.md).
 
 ## What's new in 0.4.0
 
@@ -208,7 +208,7 @@ Releases are built and published to PyPI via [GitHub Actions](https://github.com
 
 1. Update [CHANGELOG.md](CHANGELOG.md): move Unreleased entries into a new version section and date it.
 2. Add a `PYPI_API_TOKEN` secret (PyPI API token) to the repo.
-3. Create a GitHub release (tag e.g. `v0.4.0`). The workflow runs tests, builds the package, and uploads to PyPI.
+3. Create a GitHub release (tag e.g. `v0.4.1`). The workflow runs tests, builds the package, and uploads to PyPI.
 
 To build and upload manually: `pip install build twine`, `python -m build`, `twine upload dist/*`.
 
@@ -222,6 +222,11 @@ To build and upload manually: `pip install build twine`, `python -m build`, `twi
   - [Models and factories](docs/user_guides/models_and_factories.md) — Pydantic, dataclasses, batches
   - [Reproducible data](docs/user_guides/reproducible_data.md) — seeding for tests and demos
   - [Custom types](docs/user_guides/custom_types.md) — `FakerType` subclasses and `faker_kwargs`
+  - [FastAPI + Pydantic](docs/user_guides/fastapi_pydantic.md) — API payloads and tests using Capper-backed Pydantic models
+  - [Django patterns](docs/user_guides/django_patterns.md) — Django-style schemas, factories, and service tests
+  - [Dataclasses and attrs](docs/user_guides/dataclasses_and_attrs.md) — non-Pydantic projects with `DataclassFactory`
+  - [Test setup templates](docs/user_guides/test_setup_templates.md) — pytest/Hypothesis fixtures and seeding patterns
+  - [Project structure](docs/user_guides/project_structure.md) — organizing Capper types, factories, and type packs
 - [Package plan](docs/capper_package_plan.md) — design and rationale
 - [Roadmap](docs/ROADMAP.md) — development phases and status
 - [Faker provider mapping](docs/FAKER_PROVIDERS.md) — which Faker method each type uses

{capper-0.4.0 → capper-0.5.0}/README.md

@@ -132,7 +132,7 @@ Use `-n`/`--count` for the number of rows and `-s`/`--seed` for reproducible out
 
 ## Compatibility
 
-Capper targets **Python 3.10+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. For version ranges, upgrade guidance, and the deprecation policy, see [Compatibility](docs/compatibility.md).
+Capper targets **Python 3.10+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. For version ranges, upgrade guidance, the versioning policy, and the deprecation policy, see [Compatibility](docs/compatibility.md).
 
 ## What's new in 0.4.0
 
@@ -180,7 +180,7 @@ Releases are built and published to PyPI via [GitHub Actions](https://github.com
 
 1. Update [CHANGELOG.md](CHANGELOG.md): move Unreleased entries into a new version section and date it.
 2. Add a `PYPI_API_TOKEN` secret (PyPI API token) to the repo.
-3. Create a GitHub release (tag e.g. `v0.4.0`). The workflow runs tests, builds the package, and uploads to PyPI.
+3. Create a GitHub release (tag e.g. `v0.4.1`). The workflow runs tests, builds the package, and uploads to PyPI.
 
 To build and upload manually: `pip install build twine`, `python -m build`, `twine upload dist/*`.
 
@@ -194,6 +194,11 @@ To build and upload manually: `pip install build twine`, `python -m build`, `twi
   - [Models and factories](docs/user_guides/models_and_factories.md) — Pydantic, dataclasses, batches
   - [Reproducible data](docs/user_guides/reproducible_data.md) — seeding for tests and demos
   - [Custom types](docs/user_guides/custom_types.md) — `FakerType` subclasses and `faker_kwargs`
+  - [FastAPI + Pydantic](docs/user_guides/fastapi_pydantic.md) — API payloads and tests using Capper-backed Pydantic models
+  - [Django patterns](docs/user_guides/django_patterns.md) — Django-style schemas, factories, and service tests
+  - [Dataclasses and attrs](docs/user_guides/dataclasses_and_attrs.md) — non-Pydantic projects with `DataclassFactory`
+  - [Test setup templates](docs/user_guides/test_setup_templates.md) — pytest/Hypothesis fixtures and seeding patterns
+  - [Project structure](docs/user_guides/project_structure.md) — organizing Capper types, factories, and type packs
 - [Package plan](docs/capper_package_plan.md) — design and rationale
 - [Roadmap](docs/ROADMAP.md) — development phases and status
 - [Faker provider mapping](docs/FAKER_PROVIDERS.md) — which Faker method each type uses

{capper-0.4.0 → capper-0.5.0}/capper/__init__.py

@@ -11,7 +11,7 @@ try:
 
     __version__ = _version("capper")
 except Exception:  # Package not installed (e.g. dev tree) or metadata missing
-    __version__ = "0.4.0"
+    __version__ = "0.5.0"
 
 from .barcode import EAN8, EAN13
 from .base import FakerType, faker, seed, use_faker

capper-0.5.0/capper/_deprecations.py

@@ -0,0 +1,29 @@
+"""Internal helpers for deprecation warnings.
+
+Use warn_deprecated() to emit consistent DeprecationWarning messages.
+"""
+
+from __future__ import annotations
+
+from warnings import warn
+
+
+def warn_deprecated(
+    name: str,
+    *,
+    removal_version: str,
+    alternative: str | None = None,
+    stacklevel: int = 2,
+) -> None:
+    """Emit a standardized DeprecationWarning for a Capper API.
+
+    Args:
+        name: Fully qualified name of the deprecated API.
+        removal_version: Target version where the API is expected to be removed.
+        alternative: Optional string describing the preferred replacement.
+        stacklevel: Passed through to warnings.warn to point at the caller.
+    """
+    message = f"{name} is deprecated and will be removed in {removal_version}."
+    if alternative:
+        message += f" Use {alternative} instead."
+    warn(message, DeprecationWarning, stacklevel=stacklevel)

{capper-0.4.0 → capper-0.5.0}/capper/cli.py

@@ -1,6 +1,7 @@
 """CLI for ad-hoc fake data generation."""
 
 import argparse
+import difflib
 import sys
 from typing import Mapping, Sequence, Type
 
@@ -32,14 +33,26 @@ def _generate_rows(types: Sequence[Type[FakerType]], count: int) -> list[str]:
     return rows
 
 
+def _unknown_type_message(name: str, registry: Mapping[str, Type[FakerType]]) -> str:
+    known_names = sorted(registry)
+    suggestions = difflib.get_close_matches(name, known_names, n=3)
+    parts = [f"Unknown type: {name}."]
+    if suggestions:
+        parts.append(f" Did you mean: {', '.join(suggestions)}?")
+    else:
+        sample = ", ".join(known_names[:5])
+        parts.append(f" Known types include: {sample}, ...")
+    parts.append(" See the Capper docs or `FAKER_PROVIDERS.md` for the full list.")
+    return "".join(parts)
+
+
 def cmd_generate(args: argparse.Namespace) -> int:
     """Run generate subcommand."""
     registry = _type_registry()
     types: list[Type[FakerType]] = []
     for name in args.types:
         if name not in registry:
-            known = ", ".join(sorted(registry))
-            print(f"Unknown type: {name}. Known: {known}", file=sys.stderr)
+            print(_unknown_type_message(name, registry), file=sys.stderr)
             return 1
         types.append(registry[name])
 
@@ -54,11 +67,23 @@ def cmd_generate(args: argparse.Namespace) -> int:
 def main() -> int:
     """Entry point for the capper CLI."""
     parser = argparse.ArgumentParser(
-        prog="capper", description="Capper: fake data via Faker types."
+        prog="capper",
+        description="Capper: fake data via Faker-backed types, integrated with Polyfactory.",
+        epilog=(
+            "Examples:\n"
+            "  capper generate Name Email --count 5\n"
+            "  capper generate Name Email --count 3 --seed 42\n"
+            "\n"
+            "Type names match the Python types, e.g. Name, Email, Address."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     subparsers = parser.add_subparsers(dest="command", required=True)
 
-    gen = subparsers.add_parser("generate", help="Generate fake values for one or more types.")
+    gen = subparsers.add_parser(
+        "generate",
+        help="Generate tab-separated fake values for one or more Capper types.",
+    )
     gen.add_argument(
         "types",
         nargs="+",

{capper-0.4.0 → capper-0.5.0}/capper/tests/test_cli.py

@@ -62,6 +62,7 @@ def test_cli_unknown_type_exits_nonzero_and_stderr(capsys: pytest.CaptureFixture
         err = capsys.readouterr().err
         assert "Unknown type" in err
         assert "NonExistentType" in err
+        assert "Known types include" in err or "Did you mean" in err
     finally:
         sys.argv = orig_argv
 

capper-0.5.0/capper/tests/test_deprecations.py

@@ -0,0 +1,26 @@
+"""Tests for the internal deprecation helper."""
+
+from __future__ import annotations
+
+from warnings import catch_warnings, simplefilter
+
+from capper._deprecations import warn_deprecated
+
+
+def test_warn_deprecated_emits_standard_message() -> None:
+    """warn_deprecated() emits a DeprecationWarning with the expected text."""
+    with catch_warnings(record=True) as caught:
+        simplefilter("always", DeprecationWarning)
+        warn_deprecated(
+            "capper.some_api",
+            removal_version="0.6.0",
+            alternative="capper.new_api",
+            stacklevel=1,
+        )
+
+    assert caught, "Expected at least one DeprecationWarning"
+    warning = caught[0]
+    assert issubclass(warning.category, DeprecationWarning)
+    message = str(warning.message)
+    assert "capper.some_api is deprecated and will be removed in 0.6.0." in message
+    assert "Use capper.new_api instead." in message

{capper-0.4.0 → capper-0.5.0}/capper/tests/test_edge_cases.py

@@ -10,13 +10,13 @@ from capper.base import FakerType
 
 
 def test_version_fallback_when_metadata_missing() -> None:
-    """When importlib.metadata.version raises, __version__ falls back to 0.4.0."""
+    """When importlib.metadata.version raises, __version__ falls back to the bundled version."""
     with patch("importlib.metadata.version", side_effect=Exception("no metadata")):
         if "capper" in sys.modules:
             del sys.modules["capper"]
         import capper as capper_mod
 
-        assert capper_mod.__version__ == "0.4.0"
+        assert capper_mod.__version__ == "0.5.0"
     # Reimport so later tests see the real version
     if "capper" in sys.modules:
         del sys.modules["capper"]

{capper-0.4.0 → capper-0.5.0}/capper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capper
-Version: 0.4.0
+Version: 0.5.0
 Summary: Semantic, typed wrappers for Faker with automatic Polyfactory integration
 Author-email: Odos Matthews <odosmatthews@gmail.com>
 Project-URL: Documentation, https://github.com/eddiethedean/capper#readme
@@ -160,7 +160,7 @@ Use `-n`/`--count` for the number of rows and `-s`/`--seed` for reproducible out
 
 ## Compatibility
 
-Capper targets **Python 3.10+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. For version ranges, upgrade guidance, and the deprecation policy, see [Compatibility](docs/compatibility.md).
+Capper targets **Python 3.10+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. For version ranges, upgrade guidance, the versioning policy, and the deprecation policy, see [Compatibility](docs/compatibility.md).
 
 ## What's new in 0.4.0
 
@@ -208,7 +208,7 @@ Releases are built and published to PyPI via [GitHub Actions](https://github.com
 
 1. Update [CHANGELOG.md](CHANGELOG.md): move Unreleased entries into a new version section and date it.
 2. Add a `PYPI_API_TOKEN` secret (PyPI API token) to the repo.
-3. Create a GitHub release (tag e.g. `v0.4.0`). The workflow runs tests, builds the package, and uploads to PyPI.
+3. Create a GitHub release (tag e.g. `v0.4.1`). The workflow runs tests, builds the package, and uploads to PyPI.
 
 To build and upload manually: `pip install build twine`, `python -m build`, `twine upload dist/*`.
 
@@ -222,6 +222,11 @@ To build and upload manually: `pip install build twine`, `python -m build`, `twi
   - [Models and factories](docs/user_guides/models_and_factories.md) — Pydantic, dataclasses, batches
   - [Reproducible data](docs/user_guides/reproducible_data.md) — seeding for tests and demos
   - [Custom types](docs/user_guides/custom_types.md) — `FakerType` subclasses and `faker_kwargs`
+  - [FastAPI + Pydantic](docs/user_guides/fastapi_pydantic.md) — API payloads and tests using Capper-backed Pydantic models
+  - [Django patterns](docs/user_guides/django_patterns.md) — Django-style schemas, factories, and service tests
+  - [Dataclasses and attrs](docs/user_guides/dataclasses_and_attrs.md) — non-Pydantic projects with `DataclassFactory`
+  - [Test setup templates](docs/user_guides/test_setup_templates.md) — pytest/Hypothesis fixtures and seeding patterns
+  - [Project structure](docs/user_guides/project_structure.md) — organizing Capper types, factories, and type packs
 - [Package plan](docs/capper_package_plan.md) — design and rationale
 - [Roadmap](docs/ROADMAP.md) — development phases and status
 - [Faker provider mapping](docs/FAKER_PROVIDERS.md) — which Faker method each type uses

{capper-0.4.0 → capper-0.5.0}/capper.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 README.md
 pyproject.toml
 capper/__init__.py
+capper/_deprecations.py
 capper/barcode.py
 capper/base.py
 capper/cli.py
@@ -28,6 +29,7 @@ capper/tests/__init__.py
 capper/tests/benchmark_core.py
 capper/tests/conftest.py
 capper/tests/test_cli.py
+capper/tests/test_deprecations.py
 capper/tests/test_docs_examples.py
 capper/tests/test_edge_cases.py
 capper/tests/test_hypothesis_strategies.py

{capper-0.4.0 → capper-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "capper"
-version = "0.4.0"
+version = "0.5.0"
 description = "Semantic, typed wrappers for Faker with automatic Polyfactory integration"
 readme = "README.md"
 requires-python = ">=3.10"