capper 1.0.0

Semantic, typed wrappers for Faker with automatic Polyfactory integration

Capper

Semantic, typed wrappers for Faker with automatic Polyfactory integration.

Source: github.com/eddiethedean/capper · Docs: capper.readthedocs.io

---

What is Capper?

Capper gives you semantic Faker types (like Name, Email, Price) that:

• Zero configuration: just import a type and use it in your models; Polyfactory knows how to generate values.
• Strongly typed: your models communicate intent instead of bare str fields.
• Multi-backend: works with Pydantic, dataclasses, attrs, and other Polyfactory-supported model types.
• Thread-safe & reproducible: per-thread Faker with helpers for seeding and locales.

You import types from the top level:

from capper import Name, Email

and use them anywhere you would use a string (or the relevant base type).

For the full story, see the Capper documentation.

---

Installation

pip install capper

• Python: 3.10+
• Core deps: Faker ≥ 20.0, Polyfactory ≥ 2.0 (installed automatically)
• Optional extras:
  • Pydantic support: pip install capper[pydantic]
  • Hypothesis strategies: pip install capper[hypothesis]

Step‑by‑step instructions live in the Getting started guide.

---

Quick example

Using Capper with a Pydantic model and Polyfactory:

from pydantic import BaseModel
from capper import Name, Email
from polyfactory.factories.pydantic_factory import ModelFactory


class User(BaseModel):
    name: Name
    email: Email


class UserFactory(ModelFactory[User]):
    pass


if __name__ == "__main__":
    user = UserFactory.build()
    print(user)

For more patterns (dataclasses and attrs, FastAPI, Django-style service layers, seeding, and custom types), see the User guides.

---

CLI

Generate fake values from the command line:

capper generate Name Email --count 5
capper generate Name Email --count 3 --seed 42

• Types: same names as the Python types (e.g. Name, Email, Address).
• Flags:
  • -n / --count: number of rows
  • -s / --seed: seed for reproducible output

CLI usage examples are covered in the getting started and models/factories guides on Read the Docs.

---

Types and providers

Capper exports all public types from the top level, for example:

from capper import Name, FirstName, LastName, Address, Email, Price

To see:

• the full list of types, and
• which Faker provider each one uses,

visit the Faker providers page.

---

Documentation

Most detail lives in the hosted docs:

• Docs home: https://capper.readthedocs.io/en/latest/
• User guides (with runnable examples):
  • Getting started
  • Models and factories
  • Reproducible data
  • Custom types
  • FastAPI + Pydantic
  • Django patterns
  • Dataclasses and attrs
  • Test setup templates
  • Project structure
• Types & API:
  • Faker provider mapping
  • API reference
• Design & roadmap:
  • Package plan
  • Roadmap
• Stability & support:
  • Compatibility
  • Security

If you are unsure where to start, begin at the docs home and follow the “User guides” flow.

---

Compatibility and support

• Runtime targets: Python 3.10+, Faker ≥ 20.0, Polyfactory ≥ 2.0.
• Semantic versioning: Capper follows SemVer; the 1.x line maintains a stable public API.
• Support & backports: policy, supported versions, and backport rules are described in the Compatibility docs.

---

Development

pip install -e ".[dev]"
pytest capper/tests

• Lint & format: ruff format . and ruff check .

• Type checking: mypy capper

• Coverage:

  pytest capper/tests --cov=capper --cov-report=term-missing --cov-fail-under=98
  

For contributor guidance (branching, testing, release process), see CONTRIBUTING.md and the maintenance‑oriented guides on Read the Docs.

---

Security

• CI security checks:
  • pip-audit runs in CI to scan dependencies.
  • A scheduled “latest deps” workflow tests Capper against current Faker and Polyfactory releases.
• Policy & reporting: see the Security page for how to report issues and which versions are supported.

---

License

Capper is licensed under the MIT License. See LICENSE for details.

Capper

Semantic, typed wrappers for Faker with automatic Polyfactory integration.

Source: github.com/eddiethedean/capper

CI pipeline

The ci.yml workflow runs on pushes and PRs to main and includes:

• Linting: ruff check . and ruff format --check .
• Type checking: mypy capper
• Tests: pytest -n auto capper/tests -v -m "not benchmark" --cov=capper --cov-report=term-missing --cov-fail-under=98
• Docs: mkdocs build --strict

Why Capper?

• Zero config — Import a type; Polyfactory uses the right Faker provider. No manual registration.
• Typed — Use Name, Email, PhoneNumber, etc. in your models for clear intent and IDE support.
• Multi-backend — Works with Pydantic, dataclasses, attrs, and other Polyfactory-supported model types.
• Thread-safe — Per-thread Faker via a proxy; seeding and locales are isolated per thread, so concurrent tests are safe.
• Optional Pydantic — Install capper alone for dataclasses/attrs; add capper[pydantic] when you use Pydantic models.

Install

pip install capper

Requires Python 3.10+, Faker >= 20.0, and Polyfactory >= 2.0. Optional extras:

• Pydantic (for Pydantic models): pip install capper[pydantic]
• Hypothesis (for property-based tests with st.from_type(...)): pip install capper[hypothesis]

Usage

• Quick start: define a Pydantic model or dataclass using Capper types (e.g. Name, Email), create a Polyfactory factory, and call Factory.build() / Factory.batch().
• Guided examples: see the docs:
  • Getting started — install, first model, first factory
  • Models and factories — Pydantic vs dataclasses, batches, mixing Capper and built-in types

Available types

Import from the top level: from capper import Name, Email, Address, ....
See the Faker provider mapping (or the hosted docs) for the full list of types and which Faker provider each uses.

Optional kwargs: Subclass FakerType and set faker_kwargs to pass arguments to the Faker provider (e.g. faker_kwargs = {"nb_words": 10} for Sentence).

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:

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 Python 3.10+, Faker >= 20.0, and Polyfactory >= 2.0. For version ranges, upgrade guidance, the versioning policy, and the deprecation policy, see Compatibility.

Support & maintenance

• Supported Python and dependency versions, along with backport expectations for the 1.0.x line, are documented in docs/compatibility.md.
• Critical bug fixes and compatibility fixes may be backported to the latest 1.0.x release; new features land in minor releases.

Security

• The CI pipeline includes a dependency vulnerability scan using pip-audit (see .github/workflows/ci.yml).
• A separate compatibility workflow (compat-latest.yml) runs tests against the latest Faker and Polyfactory versions.
• For details on supported versions and how to report security issues, see SECURITY.md.

What's new in 1.0.0

• Production-ready, stable API: Capper 1.0.0 promotes the 0.5.x feature set (Phases 9–11) to a stable, production-ready API with documented compatibility and versioning guarantees.
• Governance and maintenance: Added governance and maintenance documentation (issue/PR templates, code of conduct, maintainer expectations, release and maintenance review checklists) to support long-term evolution.
• Security and compatibility: CI now includes pip-audit and a scheduled latest-deps workflow; the security policy and compatibility docs describe how issues are reported, triaged, and backported.

Development

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. CI requires coverage ≥ 98% for the capper/ package (--cov-fail-under=98).

For seeding, locales, and reproducible test data patterns, see Reproducible data.

Publishing

Releases are built and published to PyPI via GitHub Actions. To publish:

1. Update 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.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/*.

Documentation

• Docs index — overview and links to all documentation
• API reference — generated API docs (build with mkdocs serve; see Contributing)
• Contributing — dev setup and how to add new types
• User guides (step-by-step, with runnable examples):
  • Getting started — install, first model, first factory
  • Models and factories — Pydantic, dataclasses, batches
  • Reproducible data — seeding for tests and demos
  • Custom types — FakerType subclasses and faker_kwargs
  • FastAPI + Pydantic — API payloads and tests using Capper-backed Pydantic models
  • Django patterns — Django-style schemas, factories, and service tests
  • Dataclasses and attrs — non-Pydantic projects with DataclassFactory
  • Test setup templates — pytest/Hypothesis fixtures and seeding patterns
  • Project structure — organizing Capper types, factories, and type packs
• Package plan — design and rationale
• Roadmap — development phases and status
• Faker provider mapping — which Faker method each type uses
• Example notebooks — Jupyter notebooks in docs/notebooks/