capper 0.1.0__tar.gz → 0.2.0__tar.gz

{capper-0.1.0/capper.egg-info → capper-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capper
-Version: 0.1.0
+Version: 0.2.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
@@ -11,16 +11,22 @@ Requires-Dist: Faker>=20.0
 Requires-Dist: Polyfactory>=2.0
 Provides-Extra: pydantic
 Requires-Dist: pydantic>=2.0; extra == "pydantic"
+Provides-Extra: hypothesis
+Requires-Dist: hypothesis>=6.0; extra == "hypothesis"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.0; extra == "dev"
 Requires-Dist: pydantic>=2.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
 
 # Capper
 
 [![PyPI](https://img.shields.io/pypi/v/capper.svg)](https://pypi.org/project/capper/)
-[![Python](https://img.shields.io/pypi/pyversions/capper.svg)](https://pypi.org/project/capper/)
-[![CI](https://img.shields.io/github/actions/workflow/status/eddiethedean/capper/publish.yml?branch=main)](https://github.com/eddiethedean/capper/actions/workflows/publish.yml)
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://pypi.org/project/capper/)
+[![CI](https://img.shields.io/github/actions/workflow/status/eddiethedean/capper/ci.yml?branch=main&label=CI)](https://github.com/eddiethedean/capper/actions/workflows/ci.yml)
 [![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://docs.astral.sh/ruff/)
 [![mypy](https://img.shields.io/badge/mypy-checked-blue.svg)](https://mypy-lang.org/)
 
@@ -41,11 +47,10 @@ Semantic, typed wrappers for [Faker](https://faker.readthedocs.io/) with automat
 pip install capper
 ```
 
-Requires **Python 3.9+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. For **Pydantic** models, install the optional extra:
+Requires **Python 3.9+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. Optional extras:
 
-```bash
-pip install capper[pydantic]
-```
+- **Pydantic** (for Pydantic models): `pip install capper[pydantic]`
+- **Hypothesis** (for property-based tests with `st.from_type(...)`): `pip install capper[hypothesis]`
 
 ## Usage
 
@@ -104,6 +109,8 @@ oevans@example.com
 
 Works automatically. No extra steps. IDE autocompletion.
 
+**New to Capper?** See the [Getting started](docs/user_guides/getting_started.md) guide and run the examples in `docs/examples/`.
+
 ## Available types
 
 - **Person**: `Name`, `FirstName`, `LastName`, `Job`
@@ -122,6 +129,17 @@ See [docs/FAKER_PROVIDERS.md](https://github.com/eddiethedean/capper/blob/main/d
 
 **Custom types:** Subclass `FakerType`, set `faker_provider` to the Faker method name (e.g. `"company"`), and optionally `faker_kwargs`. The type auto-registers with Polyfactory when the class is defined.
 
+## CLI
+
+Generate fake values from the command line:
+
+```bash
+capper generate Name Email --count 5
+capper generate Name Email --count 3 --seed 42
+```
+
+Use `-n`/`--count` for the number of rows and `-s`/`--seed` for reproducible output. Type names are the same as the Python types (e.g. `Name`, `Email`, `Address`).
+
 ## Compatibility
 
 Capper targets **Faker >= 20.0** and **Polyfactory >= 2.0**. Major Faker upgrades may change or rename provider methods; if a type fails, check [Faker's changelog](https://faker.readthedocs.io/en/stable/changelog.html) and [docs/FAKER_PROVIDERS.md](https://github.com/eddiethedean/capper/blob/main/docs/FAKER_PROVIDERS.md) and update the provider name if needed.
@@ -133,6 +151,8 @@ pip install -e ".[dev]"
 pytest capper/tests
 ```
 
+Lint and type-check: `ruff check .`, `ruff format .`, `mypy capper`.
+
 Run tests with coverage: `pytest capper/tests --cov=capper --cov-report=term-missing`.
 
 **Reproducibility:** Capper and Polyfactory share the same Faker instance, so one seed controls both capper types and built-in types (`str`, `int`, etc.):
@@ -163,13 +183,19 @@ Use `UserFactory.__random_seed__ = 42` to seed once when the factory class is cr
 Releases are built and published to PyPI via [GitHub Actions](https://github.com/eddiethedean/capper/blob/main/.github/workflows/publish.yml). To publish:
 
 1. Add a `PYPI_API_TOKEN` secret (PyPI API token) to the repo.
-2. Create a GitHub release (tag e.g. `v0.1.0`). The workflow runs tests, builds the package, and uploads to PyPI.
+2. Create a GitHub release (tag e.g. `v0.2.0`). 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/*`.
 
-## Links
-
-- [Documentation index](https://github.com/eddiethedean/capper/blob/main/docs/README.md) — overview of all docs
-- [Package plan](https://github.com/eddiethedean/capper/blob/main/docs/capper_package_plan.md) — design and rationale
-- [Roadmap](https://github.com/eddiethedean/capper/blob/main/docs/ROADMAP.md) — development phases and status
-- [Faker provider mapping](https://github.com/eddiethedean/capper/blob/main/docs/FAKER_PROVIDERS.md) — type-to-provider reference
+## Documentation
+
+- **[Docs index](docs/README.md)** — overview and links to all documentation
+- **User guides** (step-by-step, with runnable examples):
+  - [Getting started](docs/user_guides/getting_started.md) — install, first model, first factory
+  - [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`
+- [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
+- [Example notebooks](docs/notebooks/README.md) — Jupyter notebooks in `docs/notebooks/`

capper-0.1.0/PKG-INFO → capper-0.2.0/README.md

@@ -1,26 +1,8 @@
-Metadata-Version: 2.4
-Name: capper
-Version: 0.1.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
-Project-URL: Repository, https://github.com/eddiethedean/capper
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-Requires-Dist: Faker>=20.0
-Requires-Dist: Polyfactory>=2.0
-Provides-Extra: pydantic
-Requires-Dist: pydantic>=2.0; extra == "pydantic"
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == "dev"
-Requires-Dist: pytest-cov>=4.0; extra == "dev"
-Requires-Dist: pydantic>=2.0; extra == "dev"
-
 # Capper
 
 [![PyPI](https://img.shields.io/pypi/v/capper.svg)](https://pypi.org/project/capper/)
-[![Python](https://img.shields.io/pypi/pyversions/capper.svg)](https://pypi.org/project/capper/)
-[![CI](https://img.shields.io/github/actions/workflow/status/eddiethedean/capper/publish.yml?branch=main)](https://github.com/eddiethedean/capper/actions/workflows/publish.yml)
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://pypi.org/project/capper/)
+[![CI](https://img.shields.io/github/actions/workflow/status/eddiethedean/capper/ci.yml?branch=main&label=CI)](https://github.com/eddiethedean/capper/actions/workflows/ci.yml)
 [![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://docs.astral.sh/ruff/)
 [![mypy](https://img.shields.io/badge/mypy-checked-blue.svg)](https://mypy-lang.org/)
 
@@ -41,11 +23,10 @@ Semantic, typed wrappers for [Faker](https://faker.readthedocs.io/) with automat
 pip install capper
 ```
 
-Requires **Python 3.9+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. For **Pydantic** models, install the optional extra:
+Requires **Python 3.9+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. Optional extras:
 
-```bash
-pip install capper[pydantic]
-```
+- **Pydantic** (for Pydantic models): `pip install capper[pydantic]`
+- **Hypothesis** (for property-based tests with `st.from_type(...)`): `pip install capper[hypothesis]`
 
 ## Usage
 
@@ -104,6 +85,8 @@ oevans@example.com
 
 Works automatically. No extra steps. IDE autocompletion.
 
+**New to Capper?** See the [Getting started](docs/user_guides/getting_started.md) guide and run the examples in `docs/examples/`.
+
 ## Available types
 
 - **Person**: `Name`, `FirstName`, `LastName`, `Job`
@@ -122,6 +105,17 @@ See [docs/FAKER_PROVIDERS.md](https://github.com/eddiethedean/capper/blob/main/d
 
 **Custom types:** Subclass `FakerType`, set `faker_provider` to the Faker method name (e.g. `"company"`), and optionally `faker_kwargs`. The type auto-registers with Polyfactory when the class is defined.
 
+## CLI
+
+Generate fake values from the command line:
+
+```bash
+capper generate Name Email --count 5
+capper generate Name Email --count 3 --seed 42
+```
+
+Use `-n`/`--count` for the number of rows and `-s`/`--seed` for reproducible output. Type names are the same as the Python types (e.g. `Name`, `Email`, `Address`).
+
 ## Compatibility
 
 Capper targets **Faker >= 20.0** and **Polyfactory >= 2.0**. Major Faker upgrades may change or rename provider methods; if a type fails, check [Faker's changelog](https://faker.readthedocs.io/en/stable/changelog.html) and [docs/FAKER_PROVIDERS.md](https://github.com/eddiethedean/capper/blob/main/docs/FAKER_PROVIDERS.md) and update the provider name if needed.
@@ -133,6 +127,8 @@ pip install -e ".[dev]"
 pytest capper/tests
 ```
 
+Lint and type-check: `ruff check .`, `ruff format .`, `mypy capper`.
+
 Run tests with coverage: `pytest capper/tests --cov=capper --cov-report=term-missing`.
 
 **Reproducibility:** Capper and Polyfactory share the same Faker instance, so one seed controls both capper types and built-in types (`str`, `int`, etc.):
@@ -163,13 +159,19 @@ Use `UserFactory.__random_seed__ = 42` to seed once when the factory class is cr
 Releases are built and published to PyPI via [GitHub Actions](https://github.com/eddiethedean/capper/blob/main/.github/workflows/publish.yml). To publish:
 
 1. Add a `PYPI_API_TOKEN` secret (PyPI API token) to the repo.
-2. Create a GitHub release (tag e.g. `v0.1.0`). The workflow runs tests, builds the package, and uploads to PyPI.
+2. Create a GitHub release (tag e.g. `v0.2.0`). 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/*`.
 
-## Links
-
-- [Documentation index](https://github.com/eddiethedean/capper/blob/main/docs/README.md) — overview of all docs
-- [Package plan](https://github.com/eddiethedean/capper/blob/main/docs/capper_package_plan.md) — design and rationale
-- [Roadmap](https://github.com/eddiethedean/capper/blob/main/docs/ROADMAP.md) — development phases and status
-- [Faker provider mapping](https://github.com/eddiethedean/capper/blob/main/docs/FAKER_PROVIDERS.md) — type-to-provider reference
+## Documentation
+
+- **[Docs index](docs/README.md)** — overview and links to all documentation
+- **User guides** (step-by-step, with runnable examples):
+  - [Getting started](docs/user_guides/getting_started.md) — install, first model, first factory
+  - [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`
+- [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
+- [Example notebooks](docs/notebooks/README.md) — Jupyter notebooks in `docs/notebooks/`

{capper-0.1.0 → capper-0.2.0}/capper/__init__.py

@@ -2,6 +2,8 @@
 
 Import types (e.g. ``Name``, ``Email``) and use them in Pydantic models, dataclasses,
 or attrs; Polyfactory will generate values via Faker. Use ``seed(n)`` for reproducibility.
+With Hypothesis installed (pip install capper[hypothesis]), import capper.strategies
+and use st.from_type(Name) for property-based tests.
 """
 
 from .base import FakerType, faker, seed
@@ -9,7 +11,7 @@ from .commerce import Company, Currency, Price, Product
 from .date_time import Date, DateTime, Time
 from .finance import CreditCardExpiry, CreditCardNumber, CreditCardProvider
 from .geo import Address, City, Country
-from .internet import Email, IP, URL, UserName
+from .internet import IP, URL, Email, UserName
 from .person import FirstName, Job, LastName, Name
 from .phone import CountryCallingCode, PhoneNumber
 from .text import Paragraph, Sentence

{capper-0.1.0 → capper-0.2.0}/capper/base.py

@@ -32,9 +32,7 @@ def _install_pydantic_schema() -> None:
     except ImportError:
         return
 
-    def __get_pydantic_core_schema__(
-        source_type: Any, handler: GetCoreSchemaHandler
-    ) -> CoreSchema:
+    def __get_pydantic_core_schema__(source_type: Any, handler: GetCoreSchemaHandler) -> CoreSchema:
         """Validate as str then coerce to the FakerType subclass."""
         return core_schema.no_info_after_validator_function(source_type, handler(str))
 
@@ -42,11 +40,12 @@ def _install_pydantic_schema() -> None:
 
 
 class FakerType(str):
-    """Base class for semantic Faker types; subclasses are auto-registered with Polyfactory.
+    """Base class for semantic Faker types; subclasses auto-register with Polyfactory.
 
     Subclasses must set a non-empty ``faker_provider`` (the Faker method name).
     Optional ``faker_kwargs`` is a dict of keyword arguments passed to that provider
     (e.g. ``faker_kwargs = {"nb_words": 10}`` for ``sentence``).
+    When Hypothesis is installed, use ``st.from_type(YourFakerType)`` for property-based tests.
     """
 
     faker_provider: str = ""
@@ -66,6 +65,7 @@ def _register(cls: type, provider_name: str) -> None:
     provider_kwargs = getattr(cls, "faker_kwargs", None) or {}
 
     def _provide() -> str:
-        return getattr(faker, provider_name)(**provider_kwargs)
+        value = getattr(faker, provider_name)(**provider_kwargs)
+        return str(value)
 
     BaseFactory.add_provider(cls, _provide)

capper-0.2.0/capper/cli.py

@@ -0,0 +1,79 @@
+"""CLI for ad-hoc fake data generation."""
+
+import argparse
+import sys
+from typing import Type
+
+import capper
+
+from .base import FakerType, faker, seed
+
+
+def _type_registry() -> dict[str, Type[FakerType]]:
+    """Map type name -> FakerType subclass (only types with faker_provider)."""
+    registry: dict[str, Type[FakerType]] = {}
+    for name in getattr(capper, "__all__", []):
+        if name in ("FakerType", "faker", "seed"):
+            continue
+        obj = getattr(capper, name, None)
+        provider = getattr(obj, "faker_provider", None)
+        if (
+            isinstance(obj, type)
+            and issubclass(obj, FakerType)
+            and isinstance(provider, str)
+            and len(provider) > 0
+        ):
+            registry[name] = obj
+    return registry
+
+
+def _generate_one(typ: Type[FakerType]) -> str:
+    """Generate a single value for the given FakerType."""
+    provider = getattr(typ, "faker_provider", "")
+    kwargs = getattr(typ, "faker_kwargs", None) or {}
+    value = getattr(faker, provider)(**kwargs)
+    return str(value)
+
+
+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)
+            return 1
+        types.append(registry[name])
+
+    if args.seed is not None:
+        seed(args.seed)
+
+    count = max(0, args.count)
+    for _ in range(count):
+        row = [_generate_one(t) for t in types]
+        print("\t".join(row))
+    return 0
+
+
+def main() -> int:
+    """Entry point for the capper CLI."""
+    parser = argparse.ArgumentParser(
+        prog="capper", description="Capper: fake data via Faker types."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    gen = subparsers.add_parser("generate", help="Generate fake values for one or more types.")
+    gen.add_argument(
+        "types",
+        nargs="+",
+        metavar="TYPE",
+        help="Type names (e.g. Name, Email).",
+    )
+    gen.add_argument("-n", "--count", type=int, default=1, help="Number of rows (default: 1).")
+    gen.add_argument("-s", "--seed", type=int, default=None, help="Seed for reproducible output.")
+    gen.set_defaults(func=cmd_generate)
+
+    args = parser.parse_args()
+    result: int = args.func(args)
+    return result

capper-0.2.0/capper/strategies.py

@@ -0,0 +1,80 @@
+"""Hypothesis strategies for Capper types (optional; requires hypothesis>=6.0).
+
+Use ``st.from_type(Name)`` after importing capper and capper.strategies, or call
+``strategies.for_type(Name)`` to get a strategy that generates instances of that type.
+"""
+
+from typing import Type, TypeVar
+
+from hypothesis import strategies as st
+
+from .base import FakerType, faker
+from .commerce import Company, Currency, Price, Product
+from .date_time import Date, DateTime, Time
+from .finance import CreditCardExpiry, CreditCardNumber, CreditCardProvider
+from .geo import Address, City, Country
+from .internet import IP, URL, Email, UserName
+from .person import FirstName, Job, LastName, Name
+from .phone import CountryCallingCode, PhoneNumber
+from .text import Paragraph, Sentence
+
+T = TypeVar("T", bound=FakerType)
+
+# All built-in FakerType subclasses for registration
+_BUILTIN_TYPES: tuple[type[FakerType], ...] = (
+    Address,
+    City,
+    Company,
+    Country,
+    CountryCallingCode,
+    CreditCardExpiry,
+    CreditCardNumber,
+    CreditCardProvider,
+    Currency,
+    Date,
+    DateTime,
+    Email,
+    FirstName,
+    IP,
+    Job,
+    LastName,
+    Name,
+    Paragraph,
+    PhoneNumber,
+    Price,
+    Product,
+    Sentence,
+    Time,
+    URL,
+    UserName,
+)
+
+
+def for_type(cls: Type[T]) -> st.SearchStrategy[T]:
+    """Return a Hypothesis strategy that generates instances of the given FakerType subclass."""
+    provider = getattr(cls, "faker_provider", None)
+    if not provider:
+        raise ValueError(f"{cls.__name__} has no faker_provider")
+    kwargs = getattr(cls, "faker_kwargs", None) or {}
+
+    @st.composite
+    def _draw(draw: st.DrawFn) -> T:
+        seed_val = draw(st.integers(min_value=0, max_value=2**32 - 1))
+        faker.seed_instance(seed_val)
+        value = getattr(faker, provider)(**kwargs)
+        return cls(str(value))
+
+    return _draw()
+
+
+def _register_strategies() -> None:
+    """Register all built-in Capper types with Hypothesis so st.from_type() works."""
+    from hypothesis.strategies import register_type_strategy
+
+    for typ in _BUILTIN_TYPES:
+        register_type_strategy(typ, for_type(typ))
+
+
+_register_strategies()
+
+__all__ = ["for_type"]

capper-0.2.0/capper/tests/test_docs_examples.py

@@ -0,0 +1,34 @@
+"""Ensure docs/examples/*.py run without error (user guide code)."""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+# Repo root: parent of capper/tests
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+
+
+@pytest.mark.parametrize(
+    "script",
+    ["getting_started", "models_and_factories", "reproducible_data", "custom_types"],
+)
+def test_docs_example_runs(script: str) -> None:
+    """Run each docs example script; fail if it exits non-zero."""
+    path = REPO_ROOT / "docs" / "examples" / f"{script}.py"
+    assert path.exists(), f"Missing {path}"
+    env = os.environ.copy()
+    env["PYTHONPATH"] = str(REPO_ROOT) + os.pathsep + env.get("PYTHONPATH", "")
+    result = subprocess.run(
+        [sys.executable, str(path)],
+        cwd=str(REPO_ROOT),
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=10,
+    )
+    assert result.returncode == 0, (
+        f"docs/examples/{script}.py failed:\nstdout:\n{result.stdout}\nstderr:\n{result.stderr}"
+    )

capper-0.2.0/capper/tests/test_hypothesis_strategies.py

@@ -0,0 +1,34 @@
+"""Tests for Hypothesis strategies (require capper[hypothesis])."""
+
+import pytest
+
+pytest.importorskip("hypothesis")
+
+from hypothesis import given
+from hypothesis import strategies as st
+
+import capper.strategies  # noqa: F401 - register types with Hypothesis
+from capper import Email, Name
+
+
+@given(st.from_type(Name))
+def test_from_type_name_produces_non_empty_string(name: Name) -> None:
+    """st.from_type(Name) yields non-empty Name instances."""
+    assert isinstance(name, Name)
+    assert isinstance(name, str)
+    assert len(name) > 0
+
+
+@given(st.from_type(Email))
+def test_from_type_email_contains_at(email: Email) -> None:
+    """st.from_type(Email) yields strings containing '@'."""
+    assert isinstance(email, Email)
+    assert "@" in email
+    assert len(email) > 0
+
+
+@given(capper.strategies.for_type(Name))
+def test_for_type_name_produces_name(name: Name) -> None:
+    """strategies.for_type(Name) yields Name instances."""
+    assert isinstance(name, Name)
+    assert len(name) > 0

{capper-0.1.0 → capper-0.2.0}/capper/tests/test_polyfactory_integration.py

@@ -1,10 +1,10 @@
-"""Tests for Polyfactory integration: ModelFactory, DataclassFactory, shared Faker, auto-registration."""
+"""Tests for Polyfactory: ModelFactory, DataclassFactory, shared Faker, auto-registration."""
 
 from dataclasses import dataclass
 
-from pydantic import BaseModel
 from polyfactory.factories import DataclassFactory
 from polyfactory.factories.pydantic_factory import ModelFactory
+from pydantic import BaseModel
 
 from capper import Email, Name
 
@@ -50,14 +50,15 @@ def test_seed_random_and_capper_seed_produce_same_value() -> None:
 
 def test_model_factory_uses_capper_faker() -> None:
     """Asserts ModelFactory.__faker__ is capper's faker to document the shared instance."""
-    import capper
     from polyfactory.factories.pydantic_factory import ModelFactory
 
+    import capper
+
     assert ModelFactory.__faker__ is capper.faker
 
 
 def test_dataclass_factory_builds_with_capper_types() -> None:
-    """Builds a dataclass with Name and Email via DataclassFactory; asserts non-empty and valid email."""
+    """Dataclass with Name/Email via DataclassFactory; asserts non-empty and valid email."""
 
     @dataclass
     class Person:
@@ -94,11 +95,12 @@ def test_dataclass_factory_batch() -> None:
 
 
 def test_capper_types_auto_registered_with_polyfactory() -> None:
-    """Asserts that importing capper registers types so Polyfactory can build a model with PhoneNumber."""
-    from capper import PhoneNumber
+    """Importing capper registers types so Polyfactory can build a model with PhoneNumber."""
     from polyfactory.factories.pydantic_factory import ModelFactory
     from pydantic import BaseModel
 
+    from capper import PhoneNumber
+
     class Contact(BaseModel):
         phone: PhoneNumber
 

{capper-0.1.0 → capper-0.2.0}/capper/tests/test_types.py

@@ -3,6 +3,8 @@
 import pytest
 
 from capper import (
+    IP,
+    URL,
     Address,
     City,
     Company,
@@ -16,7 +18,6 @@ from capper import (
     DateTime,
     Email,
     FirstName,
-    IP,
     Job,
     LastName,
     Name,
@@ -26,7 +27,6 @@ from capper import (
     Product,
     Sentence,
     Time,
-    URL,
     UserName,
 )
 
@@ -62,7 +62,7 @@ from capper import (
     ],
 )
 def test_type_generates_non_empty_string(type_class: type) -> None:
-    """Asserts each type's Faker provider exists and returns a non-empty value (provider availability)."""
+    """Each type's Faker provider exists and returns a non-empty value."""
     from faker import Faker
 
     faker = Faker()
@@ -77,13 +77,13 @@ def test_type_generates_non_empty_string(type_class: type) -> None:
     [Name, Email, PhoneNumber, FirstName, Address, Sentence, CreditCardNumber],
 )
 def test_model_factory_builds_capper_type(type_class: type) -> None:
-    """Builds a Pydantic model with a single capper type via ModelFactory; asserts non-empty and type."""
-    from typing import Any
+    """Pydantic model with one capper type via ModelFactory; asserts non-empty and type."""
+    from typing import Any, Type
 
     from polyfactory.factories.pydantic_factory import ModelFactory
     from pydantic import create_model
 
-    model_cls: type[Any] = create_model("Model", value=(type_class, ...))
+    model_cls: Type[Any] = create_model("Model", value=(type_class, ...))
 
     class ModelFactoryCls(ModelFactory[model_cls]):  # type: ignore[valid-type]
         pass
@@ -94,7 +94,7 @@ def test_model_factory_builds_capper_type(type_class: type) -> None:
 
 
 def test_faker_kwargs_support() -> None:
-    """Asserts types can set faker_kwargs and provider is called with them; builds via ModelFactory and checks value."""
+    """faker_kwargs passed to provider; ModelFactory builds and checks value."""
     from capper.base import FakerType
 
     class ShortSentence(FakerType):
@@ -123,10 +123,11 @@ def test_faker_kwargs_support() -> None:
 
 def test_seed_reproducibility(seeded_faker: None) -> None:
     """Builds twice after seeding with same value; asserts identical generated name."""
-    from capper import Name, seed
     from polyfactory.factories.pydantic_factory import ModelFactory
     from pydantic import BaseModel
 
+    from capper import Name, seed
+
     class User(BaseModel):
         name: Name
 

capper-0.1.0/README.md → capper-0.2.0/capper.egg-info/PKG-INFO

@@ -1,8 +1,32 @@
+Metadata-Version: 2.4
+Name: capper
+Version: 0.2.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
+Project-URL: Repository, https://github.com/eddiethedean/capper
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: Faker>=20.0
+Requires-Dist: Polyfactory>=2.0
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.0; extra == "pydantic"
+Provides-Extra: hypothesis
+Requires-Dist: hypothesis>=6.0; extra == "hypothesis"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.0; extra == "dev"
+Requires-Dist: pydantic>=2.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+
 # Capper
 
 [![PyPI](https://img.shields.io/pypi/v/capper.svg)](https://pypi.org/project/capper/)
-[![Python](https://img.shields.io/pypi/pyversions/capper.svg)](https://pypi.org/project/capper/)
-[![CI](https://img.shields.io/github/actions/workflow/status/eddiethedean/capper/publish.yml?branch=main)](https://github.com/eddiethedean/capper/actions/workflows/publish.yml)
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://pypi.org/project/capper/)
+[![CI](https://img.shields.io/github/actions/workflow/status/eddiethedean/capper/ci.yml?branch=main&label=CI)](https://github.com/eddiethedean/capper/actions/workflows/ci.yml)
 [![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://docs.astral.sh/ruff/)
 [![mypy](https://img.shields.io/badge/mypy-checked-blue.svg)](https://mypy-lang.org/)
 
@@ -23,11 +47,10 @@ Semantic, typed wrappers for [Faker](https://faker.readthedocs.io/) with automat
 pip install capper
 ```
 
-Requires **Python 3.9+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. For **Pydantic** models, install the optional extra:
+Requires **Python 3.9+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. Optional extras:
 
-```bash
-pip install capper[pydantic]
-```
+- **Pydantic** (for Pydantic models): `pip install capper[pydantic]`
+- **Hypothesis** (for property-based tests with `st.from_type(...)`): `pip install capper[hypothesis]`
 
 ## Usage
 
@@ -86,6 +109,8 @@ oevans@example.com
 
 Works automatically. No extra steps. IDE autocompletion.
 
+**New to Capper?** See the [Getting started](docs/user_guides/getting_started.md) guide and run the examples in `docs/examples/`.
+
 ## Available types
 
 - **Person**: `Name`, `FirstName`, `LastName`, `Job`
@@ -104,6 +129,17 @@ See [docs/FAKER_PROVIDERS.md](https://github.com/eddiethedean/capper/blob/main/d
 
 **Custom types:** Subclass `FakerType`, set `faker_provider` to the Faker method name (e.g. `"company"`), and optionally `faker_kwargs`. The type auto-registers with Polyfactory when the class is defined.
 
+## CLI
+
+Generate fake values from the command line:
+
+```bash
+capper generate Name Email --count 5
+capper generate Name Email --count 3 --seed 42
+```
+
+Use `-n`/`--count` for the number of rows and `-s`/`--seed` for reproducible output. Type names are the same as the Python types (e.g. `Name`, `Email`, `Address`).
+
 ## Compatibility
 
 Capper targets **Faker >= 20.0** and **Polyfactory >= 2.0**. Major Faker upgrades may change or rename provider methods; if a type fails, check [Faker's changelog](https://faker.readthedocs.io/en/stable/changelog.html) and [docs/FAKER_PROVIDERS.md](https://github.com/eddiethedean/capper/blob/main/docs/FAKER_PROVIDERS.md) and update the provider name if needed.
@@ -115,6 +151,8 @@ pip install -e ".[dev]"
 pytest capper/tests
 ```
 
+Lint and type-check: `ruff check .`, `ruff format .`, `mypy capper`.
+
 Run tests with coverage: `pytest capper/tests --cov=capper --cov-report=term-missing`.
 
 **Reproducibility:** Capper and Polyfactory share the same Faker instance, so one seed controls both capper types and built-in types (`str`, `int`, etc.):
@@ -145,13 +183,19 @@ Use `UserFactory.__random_seed__ = 42` to seed once when the factory class is cr
 Releases are built and published to PyPI via [GitHub Actions](https://github.com/eddiethedean/capper/blob/main/.github/workflows/publish.yml). To publish:
 
 1. Add a `PYPI_API_TOKEN` secret (PyPI API token) to the repo.
-2. Create a GitHub release (tag e.g. `v0.1.0`). The workflow runs tests, builds the package, and uploads to PyPI.
+2. Create a GitHub release (tag e.g. `v0.2.0`). 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/*`.
 
-## Links
-
-- [Documentation index](https://github.com/eddiethedean/capper/blob/main/docs/README.md) — overview of all docs
-- [Package plan](https://github.com/eddiethedean/capper/blob/main/docs/capper_package_plan.md) — design and rationale
-- [Roadmap](https://github.com/eddiethedean/capper/blob/main/docs/ROADMAP.md) — development phases and status
-- [Faker provider mapping](https://github.com/eddiethedean/capper/blob/main/docs/FAKER_PROVIDERS.md) — type-to-provider reference
+## Documentation
+
+- **[Docs index](docs/README.md)** — overview and links to all documentation
+- **User guides** (step-by-step, with runnable examples):
+  - [Getting started](docs/user_guides/getting_started.md) — install, first model, first factory
+  - [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`
+- [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
+- [Example notebooks](docs/notebooks/README.md) — Jupyter notebooks in `docs/notebooks/`

{capper-0.1.0 → capper-0.2.0}/capper.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ README.md
 pyproject.toml
 capper/__init__.py
 capper/base.py
+capper/cli.py
 capper/commerce.py
 capper/date_time.py
 capper/finance.py
@@ -9,14 +10,18 @@ capper/geo.py
 capper/internet.py
 capper/person.py
 capper/phone.py
+capper/strategies.py
 capper/text.py
 capper.egg-info/PKG-INFO
 capper.egg-info/SOURCES.txt
 capper.egg-info/dependency_links.txt
+capper.egg-info/entry_points.txt
 capper.egg-info/requires.txt
 capper.egg-info/top_level.txt
 capper/examples/user_factory.py
 capper/tests/__init__.py
 capper/tests/conftest.py
+capper/tests/test_docs_examples.py
+capper/tests/test_hypothesis_strategies.py
 capper/tests/test_polyfactory_integration.py
 capper/tests/test_types.py

capper-0.2.0/capper.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+capper = capper.cli:main

{capper-0.1.0 → capper-0.2.0}/capper.egg-info/requires.txt

@@ -4,7 +4,14 @@ Polyfactory>=2.0
 [dev]
 pytest>=7.0
 pytest-cov>=4.0
+pytest-xdist>=3.0
 pydantic>=2.0
+ruff>=0.4
+mypy>=1.0
+hypothesis>=6.0
+
+[hypothesis]
+hypothesis>=6.0
 
 [pydantic]
 pydantic>=2.0

{capper-0.1.0 → capper-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "capper"
-version = "0.1.0"
+version = "0.2.0"
 description = "Semantic, typed wrappers for Faker with automatic Polyfactory integration"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -20,16 +20,26 @@ dependencies = [
 pydantic = [
     "pydantic>=2.0",
 ]
+hypothesis = [
+    "hypothesis>=6.0",
+]
 dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
+    "pytest-xdist>=3.0",
     "pydantic>=2.0",
+    "ruff>=0.4",
+    "mypy>=1.0",
+    "hypothesis>=6.0",
 ]
 
 [project.urls]
 Documentation = "https://github.com/eddiethedean/capper#readme"
 Repository = "https://github.com/eddiethedean/capper"
 
+[project.scripts]
+capper = "capper.cli:main"
+
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["capper*"]
@@ -38,3 +48,17 @@ include = ["capper*"]
 testpaths = ["capper/tests"]
 pythonpath = ["."]
 addopts = ["-v", "--tb=short"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+exclude = ["docs/notebooks"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false

{capper-0.1.0 → capper-0.2.0}/capper/examples/user_factory.py

@@ -4,8 +4,8 @@ Run: python -m capper.examples.user_factory
 Output varies each run; use capper.seed(n) for reproducible data.
 """
 
-from pydantic import BaseModel
 from polyfactory.factories.pydantic_factory import ModelFactory
+from pydantic import BaseModel
 
 from capper import Email, Name