capper 0.4.1__tar.gz → 1.0.0__tar.gz

capper-1.0.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Odos Matthews
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

capper-1.0.0/PKG-INFO

@@ -0,0 +1,380 @@
+Metadata-Version: 2.4
+Name: capper
+Version: 1.0.0
+Summary: Semantic, typed wrappers for Faker with automatic Polyfactory integration
+Author-email: Odos Matthews <odosmatthews@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Odos Matthews
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+        
+Project-URL: Documentation, https://github.com/eddiethedean/capper#readme
+Project-URL: Repository, https://github.com/eddiethedean/capper
+Keywords: faker,testing,factories,polyfactory,hypothesis,pydantic
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+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-benchmark>=4.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"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Dynamic: license-file
+
+# Capper
+
+[![PyPI](https://img.shields.io/pypi/v/capper.svg)](https://pypi.org/project/capper/)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/capper/)
+[![CI](https://img.shields.io/github/actions/workflow/status/eddiethedean/capper/ci.yml?branch=main&label=CI%20(lint%2C%20types%2C%20tests%2C%20docs))](https://github.com/eddiethedean/capper/actions/workflows/ci.yml)
+[![Docs](https://readthedocs.org/projects/capper/badge/?version=latest)](https://capper.readthedocs.io/en/latest/)
+[![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/)
+
+Semantic, typed wrappers for [Faker](https://faker.readthedocs.io/) with automatic [Polyfactory](https://polyfactory.litestar.dev/) integration.
+
+**Source:** [github.com/eddiethedean/capper](https://github.com/eddiethedean/capper) · **Docs:** [capper.readthedocs.io](https://capper.readthedocs.io/en/latest/)
+
+---
+
+## 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:
+
+```python
+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](https://capper.readthedocs.io/en/latest/)**.
+
+---
+
+## Installation
+
+```bash
+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](https://capper.readthedocs.io/en/latest/user_guides/getting_started/)**.
+
+---
+
+## Quick example
+
+Using Capper with a Pydantic model and Polyfactory:
+
+```python
+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](https://capper.readthedocs.io/en/latest/#user-guides)**.
+
+---
+
+## CLI
+
+Generate fake values from the command line:
+
+```bash
+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:
+
+```python
+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](https://capper.readthedocs.io/en/latest/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](https://capper.readthedocs.io/en/latest/user_guides/getting_started/)
+  - [Models and factories](https://capper.readthedocs.io/en/latest/user_guides/models_and_factories/)
+  - [Reproducible data](https://capper.readthedocs.io/en/latest/user_guides/reproducible_data/)
+  - [Custom types](https://capper.readthedocs.io/en/latest/user_guides/custom_types/)
+  - [FastAPI + Pydantic](https://capper.readthedocs.io/en/latest/user_guides/fastapi_pydantic/)
+  - [Django patterns](https://capper.readthedocs.io/en/latest/user_guides/django_patterns/)
+  - [Dataclasses and attrs](https://capper.readthedocs.io/en/latest/user_guides/dataclasses_and_attrs/)
+  - [Test setup templates](https://capper.readthedocs.io/en/latest/user_guides/test_setup_templates/)
+  - [Project structure](https://capper.readthedocs.io/en/latest/user_guides/project_structure/)
+- **Types & API**:
+  - [Faker provider mapping](https://capper.readthedocs.io/en/latest/FAKER_PROVIDERS/)
+  - [API reference](https://capper.readthedocs.io/en/latest/api/)
+- **Design & roadmap**:
+  - [Package plan](https://capper.readthedocs.io/en/latest/capper_package_plan/)
+  - [Roadmap](https://capper.readthedocs.io/en/latest/ROADMAP/)
+- **Stability & support**:
+  - [Compatibility](https://capper.readthedocs.io/en/latest/compatibility/)
+  - [Security](https://capper.readthedocs.io/en/latest/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](https://capper.readthedocs.io/en/latest/compatibility/)** docs.
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest capper/tests
+```
+
+- **Lint & format**: `ruff format .` and `ruff check .`
+- **Type checking**: `mypy capper`
+- **Coverage**:
+
+  ```bash
+  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](https://capper.readthedocs.io/en/latest/SECURITY/)** for how to report issues and which versions are supported.
+
+---
+
+## License
+
+Capper is licensed under the **MIT License**. See `LICENSE` for details.
+
+# Capper
+
+[![PyPI](https://img.shields.io/pypi/v/capper.svg)](https://pypi.org/project/capper/)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/capper/)
+[![CI](https://img.shields.io/github/actions/workflow/status/eddiethedean/capper/ci.yml?branch=main&label=CI%20(lint%2C%20types%2C%20tests%2C%20docs))](https://github.com/eddiethedean/capper/actions/workflows/ci.yml)
+[![Docs](https://readthedocs.org/projects/capper/badge/?version=latest)](https://capper.readthedocs.io/en/latest/)
+[![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/)
+
+Semantic, typed wrappers for [Faker](https://faker.readthedocs.io/) with automatic [Polyfactory](https://polyfactory.litestar.dev/) integration.
+
+**Source:** [github.com/eddiethedean/capper](https://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](https://polyfactory.litestar.dev/) 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
+
+```bash
+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](docs/user_guides/getting_started.md) — install, first model, first factory
+  - [Models and factories](docs/user_guides/models_and_factories.md) — 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](docs/FAKER_PROVIDERS.md)** (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:
+
+```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 **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).
+
+### Support & maintenance
+
+- Supported Python and dependency versions, along with backport expectations for the 1.0.x line, are documented in [docs/compatibility.md](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](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
+
+```bash
+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](docs/user_guides/reproducible_data.md)**.
+
+## Publishing
+
+Releases are built and published to PyPI via [GitHub Actions](https://github.com/eddiethedean/capper/blob/main/.github/workflows/publish.yml). To publish:
+
+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.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](docs/README.md)** — overview and links to all documentation
+- **[API reference](docs/api.md)** — generated API docs (build with `mkdocs serve`; see [Contributing](CONTRIBUTING.md))
+- **[Contributing](CONTRIBUTING.md)** — dev setup and how to add new types
+- **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`
+  - [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
+- [Example notebooks](docs/notebooks/README.md) — Jupyter notebooks in `docs/notebooks/`