capper 0.5.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

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

With Pydantic (requires capper[pydantic]):

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

user = UserFactory.build()
print(user.name)
print(user.email)

Example output (varies each run):

Paul Blair
[e-mail]

With dataclasses (no Pydantic needed):

from dataclasses import dataclass
from capper import Name, Email
from polyfactory.factories import DataclassFactory

@dataclass
class User:
    name: Name
    email: Email

class UserFactory(DataclassFactory[User]):
    pass

user = UserFactory.build()
print(user.name)
print(user.email)

Example output (varies each run):

Carly Jenkins
[e-mail]

Works automatically. No extra steps. IDE autocompletion.

New to Capper? See the Getting started guide and run the examples in docs/examples/.

Available types

• Person: Name, FirstName, LastName, Job
• Geo: Address, City, Country
• Internet: Email, URL, IP, UserName
• Commerce: Company, Product, Currency, Price
• Date/time: Date, DateTime, Time
• Text: Paragraph, Sentence
• Phone: PhoneNumber, CountryCallingCode
• Finance: CreditCardNumber, CreditCardExpiry, CreditCardProvider
• File: FilePath, FileName, FileExtension
• Misc: UUID
• Color: HexColor
• Barcode: EAN13, EAN8

Import from the top level: from capper import Name, Email, Address, ...
See docs/FAKER_PROVIDERS.md for the Faker provider used by each type.

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.

What's new in 0.4.0

• Thread safety: Capper is now thread-safe via a per-thread Faker proxy; seed() and use_faker() only affect the current thread.
• Reliability and coverage: Phase 9 adds a coverage gate (≥ 98% for capper/), targeted edge-case tests, and a lightweight performance check in CI.
• Tooling and docs: CI runs Ruff, mypy, tests (with coverage gate), and a strict MkDocs build on all supported Python versions; docs and roadmap have been updated to reflect Phase 9.

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).

Reproducibility: Capper and Polyfactory share the same Faker instance, so one seed controls both capper types and built-in types (str, int, etc.):

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

class User(BaseModel):
    name: Name

class UserFactory(ModelFactory[User]):
    pass

# Either way seeds the shared Faker (same effect):
seed(42)
user1 = UserFactory.build()

UserFactory.seed_random(42)
user2 = UserFactory.build()  # same data as user1 if you seed the same before each

Use UserFactory.__random_seed__ = 42 to seed once when the factory class is created, or call seed(42) / UserFactory.seed_random(42) before each build for identical builds. For a custom locale (e.g. German names), use use_faker(Faker('de_DE')) so both Capper and Polyfactory use the same Faker instance; 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/