Capper documentation
Documentation for the Capper package — semantic Faker types with automatic Polyfactory integration.
| Document | Description |
|---|---|
| README.md | Install, usage, examples, and publishing. Start here. |
| capper_package_plan.md | Design, layout, registration, and development plan. |
| ROADMAP.md | Phases, current status, and release milestones. |
| FAKER_PROVIDERS.md | Mapping of each capper type to its Faker provider. |
| compatibility.md | Version support, upgrade guidance, deprecation policy, and versioning. |
| extending.md | Third-party type packs: shipping your own FakerType bundles. |
| notebooks/README.md | Example Jupyter notebooks. |
User guides
Step-by-step guides with runnable examples (run from repo root with Capper installed: python docs/examples/<name>.py):
| Guide | Description |
|---|---|
| user_guides/getting_started.md | Install, first Pydantic model, first factory. |
| user_guides/models_and_factories.md | Pydantic vs dataclasses, batches, mixing Capper and built-in types. |
| user_guides/reproducible_data.md | Seeding with seed(), seed_random(), and __random_seed__. |
| user_guides/custom_types.md | Custom FakerType subclasses and faker_kwargs. |
| user_guides/fastapi_pydantic.md | FastAPI-style tests and API payloads with Pydantic models and Capper factories. |
| user_guides/django_patterns.md | Django-style patterns using Capper-backed schemas and factories alongside Django models/serializers. |
| user_guides/dataclasses_and_attrs.md | Dataclasses-only and attrs-heavy projects using DataclassFactory. |
| user_guides/test_setup_templates.md | pytest and Hypothesis setup templates (seeding, fixtures, base factories). |
| user_guides/project_structure.md | Suggested layout and naming for Capper-heavy projects and type packs. |
Runnable scripts for each guide live in docs/examples/.
Example notebooks
Jupyter notebooks demonstrate Capper usage with runnable examples.
| Notebook | Description |
|---|---|
| 01_getting_started.ipynb | First Pydantic model with Name and Email. |
| 02_models_and_batch.ipynb | Pydantic, dataclass, batch(), mixing Capper and built-in types. |
| 03_reproducible_data.ipynb | Seeding with seed() and seed_random(). |
| 04_custom_types.ipynb | Custom FakerType subclasses and faker_kwargs. |
Full list and run instructions: notebooks/README.md.
Types and API
For the full list of Capper types and the Faker provider used by each, see
FAKER_PROVIDERS.md. Import types from the top level: from capper import Name, Email, ....
Quick links
- Using capper: See the main README for install and examples (Pydantic, dataclass, seed, kwargs).
- User guides: getting_started → models and factories → reproducible data → custom types.
- How it works: Package plan —
FakerType, auto-registration, optional Pydantic. - What’s next: Roadmap — phases and versions.
- Type → Faker: Faker providers — which Faker method each type uses.
- Compatibility: Version support and deprecation — Faker/Polyfactory/Python and upgrade notes.
- Type packs: Extending Capper — building third-party packages of FakerType subclasses.