capper 0.1.0__tar.gz

capper-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+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)
+[![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)
+
+## 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.
+- **Optional Pydantic** — Install `capper` alone for dataclasses/attrs; add `capper[pydantic]` when you use Pydantic models.
+
+## Install
+
+```bash
+pip install capper
+```
+
+Requires **Python 3.9+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. For **Pydantic** models, install the optional extra:
+
+```bash
+pip install capper[pydantic]
+```
+
+## Usage
+
+**With Pydantic** (requires `capper[pydantic]`):
+
+```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
+
+user = UserFactory.build()
+print(user.name)
+print(user.email)
+```
+
+Example output (varies each run):
+
+```
+Paul Blair
+linda00@example.net
+```
+
+**With dataclasses** (no Pydantic needed):
+
+```python
+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
+oevans@example.com
+```
+
+Works automatically. No extra steps. IDE autocompletion.
+
+## 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`
+
+Import from the top level: `from capper import Name, Email, Address, ...`  
+See [docs/FAKER_PROVIDERS.md](https://github.com/eddiethedean/capper/blob/main/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.
+
+## 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.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest capper/tests
+```
+
+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.):
+
+```python
+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.
+
+## 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. 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.
+
+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

capper-0.1.0/README.md

@@ -0,0 +1,157 @@
+# 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)
+[![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)
+
+## 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.
+- **Optional Pydantic** — Install `capper` alone for dataclasses/attrs; add `capper[pydantic]` when you use Pydantic models.
+
+## Install
+
+```bash
+pip install capper
+```
+
+Requires **Python 3.9+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. For **Pydantic** models, install the optional extra:
+
+```bash
+pip install capper[pydantic]
+```
+
+## Usage
+
+**With Pydantic** (requires `capper[pydantic]`):
+
+```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
+
+user = UserFactory.build()
+print(user.name)
+print(user.email)
+```
+
+Example output (varies each run):
+
+```
+Paul Blair
+linda00@example.net
+```
+
+**With dataclasses** (no Pydantic needed):
+
+```python
+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
+oevans@example.com
+```
+
+Works automatically. No extra steps. IDE autocompletion.
+
+## 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`
+
+Import from the top level: `from capper import Name, Email, Address, ...`  
+See [docs/FAKER_PROVIDERS.md](https://github.com/eddiethedean/capper/blob/main/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.
+
+## 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.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest capper/tests
+```
+
+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.):
+
+```python
+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.
+
+## 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. 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.
+
+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

capper-0.1.0/capper/__init__.py

@@ -0,0 +1,46 @@
+"""Capper: semantic Faker types with automatic Polyfactory integration.
+
+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.
+"""
+
+from .base import FakerType, faker, seed
+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 .person import FirstName, Job, LastName, Name
+from .phone import CountryCallingCode, PhoneNumber
+from .text import Paragraph, Sentence
+
+__all__ = [
+    "Address",
+    "City",
+    "Company",
+    "Country",
+    "CountryCallingCode",
+    "CreditCardExpiry",
+    "CreditCardNumber",
+    "CreditCardProvider",
+    "Currency",
+    "Date",
+    "DateTime",
+    "Email",
+    "FakerType",
+    "FirstName",
+    "IP",
+    "Job",
+    "LastName",
+    "Name",
+    "Paragraph",
+    "PhoneNumber",
+    "Price",
+    "Product",
+    "Sentence",
+    "Time",
+    "URL",
+    "UserName",
+    "faker",
+    "seed",
+]

capper-0.1.0/capper/base.py

@@ -0,0 +1,71 @@
+"""FakerType base class and shared Faker instance with automatic Polyfactory registration.
+
+The module-level ``faker`` is attached to Polyfactory's BaseFactory so that one seed
+controls both capper types and built-in types. Use ``seed(n)`` for reproducible data.
+"""
+
+from typing import Any
+
+from faker import Faker
+from polyfactory.factories.base import BaseFactory
+
+faker = Faker()
+
+# Share this Faker with Polyfactory so one seed controls both capper types and built-in types.
+BaseFactory.__faker__ = faker
+
+
+def seed(seed_value: int) -> None:
+    """Seed the shared Faker instance for reproducible data.
+
+    Args:
+        seed_value: Integer seed; same value produces the same sequence of values.
+    """
+    faker.seed_instance(seed_value)
+
+
+def _install_pydantic_schema() -> None:
+    """If Pydantic is available, attach __get_pydantic_core_schema__ to FakerType."""
+    try:
+        from pydantic import GetCoreSchemaHandler
+        from pydantic_core import CoreSchema, core_schema
+    except ImportError:
+        return
+
+    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))
+
+    FakerType.__get_pydantic_core_schema__ = __get_pydantic_core_schema__  # type: ignore[attr-defined]
+
+
+class FakerType(str):
+    """Base class for semantic Faker types; subclasses are auto-registered 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``).
+    """
+
+    faker_provider: str = ""
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        super().__init_subclass__(**kwargs)
+        provider = getattr(cls, "faker_provider", None)
+        if provider:
+            _register(cls, provider)
+
+
+_install_pydantic_schema()
+
+
+def _register(cls: type, provider_name: str) -> None:
+    """Register a FakerType subclass with Polyfactory so factories can generate values."""
+    provider_kwargs = getattr(cls, "faker_kwargs", None) or {}
+
+    def _provide() -> str:
+        return getattr(faker, provider_name)(**provider_kwargs)
+
+    BaseFactory.add_provider(cls, _provide)

capper-0.1.0/capper/commerce.py

@@ -0,0 +1,27 @@
+"""Commerce-related semantic Faker types (company, product, currency, price)."""
+
+from .base import FakerType
+
+
+class Company(FakerType):
+    """Company name. Uses Faker provider ``company``."""
+
+    faker_provider = "company"
+
+
+class Product(FakerType):
+    """Product/catch phrase. Uses Faker provider ``catch_phrase``."""
+
+    faker_provider = "catch_phrase"
+
+
+class Currency(FakerType):
+    """Currency code. Uses Faker provider ``currency_code``."""
+
+    faker_provider = "currency_code"
+
+
+class Price(FakerType):
+    """Price tag string. Uses Faker provider ``pricetag``."""
+
+    faker_provider = "pricetag"

capper-0.1.0/capper/date_time.py

@@ -0,0 +1,21 @@
+"""Date/time-related semantic Faker types (date, datetime, time as strings)."""
+
+from .base import FakerType
+
+
+class Date(FakerType):
+    """Date string. Uses Faker provider ``date``."""
+
+    faker_provider = "date"
+
+
+class DateTime(FakerType):
+    """ISO 8601 datetime string. Uses Faker provider ``iso8601``."""
+
+    faker_provider = "iso8601"
+
+
+class Time(FakerType):
+    """Time string. Uses Faker provider ``time``."""
+
+    faker_provider = "time"

capper-0.1.0/capper/examples/user_factory.py

@@ -0,0 +1,29 @@
+"""Example: Pydantic model with capper types and Polyfactory ModelFactory.
+
+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 capper import Email, Name
+
+
+class User(BaseModel):
+    """Example Pydantic model with capper types."""
+
+    name: Name
+    email: Email
+
+
+class UserFactory(ModelFactory[User]):
+    """Polyfactory factory for User; uses capper's Faker for name and email."""
+
+    pass
+
+
+if __name__ == "__main__":
+    user = UserFactory.build()
+    print(user.name)
+    print(user.email)

capper-0.1.0/capper/finance.py

@@ -0,0 +1,21 @@
+"""Finance / credit card semantic Faker types."""
+
+from .base import FakerType
+
+
+class CreditCardNumber(FakerType):
+    """Credit card number string. Uses Faker provider ``credit_card_number``."""
+
+    faker_provider = "credit_card_number"
+
+
+class CreditCardExpiry(FakerType):
+    """Credit card expiry string. Uses Faker provider ``credit_card_expire``."""
+
+    faker_provider = "credit_card_expire"
+
+
+class CreditCardProvider(FakerType):
+    """Credit card provider name. Uses Faker provider ``credit_card_provider``."""
+
+    faker_provider = "credit_card_provider"

capper-0.1.0/capper/geo.py

@@ -0,0 +1,21 @@
+"""Geography-related semantic Faker types (address, city, country)."""
+
+from .base import FakerType
+
+
+class Address(FakerType):
+    """Street address. Uses Faker provider ``address``."""
+
+    faker_provider = "address"
+
+
+class City(FakerType):
+    """City name. Uses Faker provider ``city``."""
+
+    faker_provider = "city"
+
+
+class Country(FakerType):
+    """Country name. Uses Faker provider ``country``."""
+
+    faker_provider = "country"

capper-0.1.0/capper/internet.py

@@ -0,0 +1,27 @@
+"""Internet-related semantic Faker types (email, URL, IP, username)."""
+
+from .base import FakerType
+
+
+class Email(FakerType):
+    """Email address. Uses Faker provider ``email``."""
+
+    faker_provider = "email"
+
+
+class URL(FakerType):
+    """URL. Uses Faker provider ``url``."""
+
+    faker_provider = "url"
+
+
+class IP(FakerType):
+    """IPv4 address. Uses Faker provider ``ipv4``."""
+
+    faker_provider = "ipv4"
+
+
+class UserName(FakerType):
+    """Username. Uses Faker provider ``user_name``."""
+
+    faker_provider = "user_name"

capper-0.1.0/capper/person.py

@@ -0,0 +1,27 @@
+"""Person-related semantic Faker types (name, job)."""
+
+from .base import FakerType
+
+
+class Name(FakerType):
+    """Full name. Uses Faker provider ``name``."""
+
+    faker_provider = "name"
+
+
+class FirstName(FakerType):
+    """First/given name. Uses Faker provider ``first_name``."""
+
+    faker_provider = "first_name"
+
+
+class LastName(FakerType):
+    """Last/family name. Uses Faker provider ``last_name``."""
+
+    faker_provider = "last_name"
+
+
+class Job(FakerType):
+    """Job title. Uses Faker provider ``job``."""
+
+    faker_provider = "job"

capper-0.1.0/capper/phone.py

@@ -0,0 +1,15 @@
+"""Phone-related semantic Faker types (phone number, country calling code)."""
+
+from .base import FakerType
+
+
+class PhoneNumber(FakerType):
+    """Phone number string. Uses Faker provider ``phone_number``."""
+
+    faker_provider = "phone_number"
+
+
+class CountryCallingCode(FakerType):
+    """Country calling code. Uses Faker provider ``country_calling_code``."""
+
+    faker_provider = "country_calling_code"

capper-0.1.0/capper/tests/__init__.py

@@ -0,0 +1 @@
+"""Capper test suite."""

capper-0.1.0/capper/tests/conftest.py

@@ -0,0 +1,11 @@
+"""Shared pytest fixtures for capper tests."""
+
+import pytest
+
+
+@pytest.fixture
+def seeded_faker() -> None:
+    """Seed the shared Faker (capper + Polyfactory) with 42 for reproducible test data."""
+    from capper import seed
+
+    seed(42)

capper-0.1.0/capper/tests/test_polyfactory_integration.py

@@ -0,0 +1,110 @@
+"""Tests for Polyfactory integration: 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 capper import Email, Name
+
+
+class User(BaseModel):
+    name: Name
+    email: Email
+
+
+class UserFactory(ModelFactory[User]):
+    pass
+
+
+def test_user_factory_builds_with_capper_types() -> None:
+    """Builds a User with Name and Email via ModelFactory; asserts non-empty and valid email."""
+    user = UserFactory.build()
+    assert isinstance(user.name, (str, Name))
+    assert isinstance(user.email, (str, Email))
+    assert len(user.name) > 0
+    assert "@" in user.email
+
+
+def test_user_factory_builds_batch() -> None:
+    """Builds a batch of users; asserts count and that each has non-empty name and email."""
+    users = UserFactory.batch(3)
+    assert len(users) == 3
+    for user in users:
+        assert isinstance(user, User)
+        assert len(user.name) > 0
+        assert "@" in user.email
+
+
+def test_seed_random_and_capper_seed_produce_same_value() -> None:
+    """Builds with UserFactory.seed_random(42) and with capper.seed(42) yield the same name."""
+    from capper import seed
+
+    UserFactory.seed_random(42)
+    user_after_seed_random = UserFactory.build()
+    seed(42)
+    user_after_capper_seed = UserFactory.build()
+    assert user_after_seed_random.name == user_after_capper_seed.name
+
+
+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
+
+    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
+    class Person:
+        name: Name
+        email: Email
+
+    class PersonFactory(DataclassFactory[Person]):
+        pass
+
+    person = PersonFactory.build()
+    assert isinstance(person.name, (str, Name))
+    assert isinstance(person.email, (str, Email))
+    assert len(person.name) > 0
+    assert "@" in person.email
+
+
+def test_dataclass_factory_batch() -> None:
+    """Builds a batch of dataclass instances; asserts count and non-empty name and email."""
+
+    @dataclass
+    class Person:
+        name: Name
+        email: Email
+
+    class PersonFactory(DataclassFactory[Person]):
+        pass
+
+    people = PersonFactory.batch(2)
+    assert len(people) == 2
+    for person in people:
+        assert isinstance(person, Person)
+        assert len(person.name) > 0
+        assert "@" in person.email
+
+
+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
+    from polyfactory.factories.pydantic_factory import ModelFactory
+    from pydantic import BaseModel
+
+    class Contact(BaseModel):
+        phone: PhoneNumber
+
+    class ContactFactory(ModelFactory[Contact]):
+        pass
+
+    contact = ContactFactory.build()
+    assert isinstance(contact.phone, (str, PhoneNumber))
+    assert len(contact.phone) > 0

capper-0.1.0/capper/tests/test_types.py

@@ -0,0 +1,140 @@
+"""Tests for capper types: Faker provider availability, ModelFactory registration, kwargs, seed."""
+
+import pytest
+
+from capper import (
+    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,
+)
+
+
+@pytest.mark.parametrize(
+    "type_class",
+    [
+        Name,
+        FirstName,
+        LastName,
+        Job,
+        Address,
+        City,
+        Country,
+        Email,
+        URL,
+        IP,
+        UserName,
+        Company,
+        Product,
+        Currency,
+        Price,
+        Date,
+        DateTime,
+        Time,
+        Paragraph,
+        Sentence,
+        PhoneNumber,
+        CountryCallingCode,
+        CreditCardNumber,
+        CreditCardExpiry,
+        CreditCardProvider,
+    ],
+)
+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)."""
+    from faker import Faker
+
+    faker = Faker()
+    provider_name = getattr(type_class, "faker_provider")
+    value = getattr(faker, provider_name)()
+    assert isinstance(value, (str, type_class))
+    assert len(str(value)) > 0
+
+
+@pytest.mark.parametrize(
+    "type_class",
+    [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
+
+    from polyfactory.factories.pydantic_factory import ModelFactory
+    from pydantic import create_model
+
+    model_cls: type[Any] = create_model("Model", value=(type_class, ...))
+
+    class ModelFactoryCls(ModelFactory[model_cls]):  # type: ignore[valid-type]
+        pass
+
+    instance: Any = ModelFactoryCls.build()
+    assert isinstance(instance.value, (str, type_class))
+    assert len(str(instance.value)) > 0
+
+
+def test_faker_kwargs_support() -> None:
+    """Asserts types can set faker_kwargs and provider is called with them; builds via ModelFactory and checks value."""
+    from capper.base import FakerType
+
+    class ShortSentence(FakerType):
+        faker_provider = "sentence"
+        faker_kwargs = {"nb_words": 5}
+
+    from faker import Faker
+
+    faker = Faker()
+    value = getattr(faker, "sentence")(**ShortSentence.faker_kwargs)
+    assert isinstance(value, str) and len(value) > 0
+
+    # Polyfactory uses the same kwargs via registration
+    from polyfactory.factories.pydantic_factory import ModelFactory as PFModelFactory
+    from pydantic import BaseModel
+
+    class FakerKwargsModel(BaseModel):
+        text: ShortSentence
+
+    class FakerKwargsModelFactory(PFModelFactory[FakerKwargsModel]):
+        pass
+
+    instance = FakerKwargsModelFactory.build()
+    assert isinstance(instance.text, (str, ShortSentence)) and len(instance.text) > 0
+
+
+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
+
+    class User(BaseModel):
+        name: Name
+
+    class UserFactory(ModelFactory[User]):
+        pass
+
+    seed(42)
+    user1 = UserFactory.build()
+    seed(42)
+    user2 = UserFactory.build()
+    assert user1.name == user2.name

capper-0.1.0/capper/text.py

@@ -0,0 +1,15 @@
+"""Text-related semantic Faker types (paragraph, sentence)."""
+
+from .base import FakerType
+
+
+class Paragraph(FakerType):
+    """Paragraph of text. Uses Faker provider ``paragraph``."""
+
+    faker_provider = "paragraph"
+
+
+class Sentence(FakerType):
+    """Single sentence. Uses Faker provider ``sentence``."""
+
+    faker_provider = "sentence"

capper-0.1.0/capper.egg-info/PKG-INFO

@@ -0,0 +1,175 @@
+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)
+[![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)
+
+## 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.
+- **Optional Pydantic** — Install `capper` alone for dataclasses/attrs; add `capper[pydantic]` when you use Pydantic models.
+
+## Install
+
+```bash
+pip install capper
+```
+
+Requires **Python 3.9+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. For **Pydantic** models, install the optional extra:
+
+```bash
+pip install capper[pydantic]
+```
+
+## Usage
+
+**With Pydantic** (requires `capper[pydantic]`):
+
+```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
+
+user = UserFactory.build()
+print(user.name)
+print(user.email)
+```
+
+Example output (varies each run):
+
+```
+Paul Blair
+linda00@example.net
+```
+
+**With dataclasses** (no Pydantic needed):
+
+```python
+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
+oevans@example.com
+```
+
+Works automatically. No extra steps. IDE autocompletion.
+
+## 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`
+
+Import from the top level: `from capper import Name, Email, Address, ...`  
+See [docs/FAKER_PROVIDERS.md](https://github.com/eddiethedean/capper/blob/main/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.
+
+## 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.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest capper/tests
+```
+
+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.):
+
+```python
+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.
+
+## 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. 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.
+
+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

capper-0.1.0/capper.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+README.md
+pyproject.toml
+capper/__init__.py
+capper/base.py
+capper/commerce.py
+capper/date_time.py
+capper/finance.py
+capper/geo.py
+capper/internet.py
+capper/person.py
+capper/phone.py
+capper/text.py
+capper.egg-info/PKG-INFO
+capper.egg-info/SOURCES.txt
+capper.egg-info/dependency_links.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_polyfactory_integration.py
+capper/tests/test_types.py

capper-0.1.0/capper.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

capper-0.1.0/capper.egg-info/requires.txt

@@ -0,0 +1,10 @@
+Faker>=20.0
+Polyfactory>=2.0
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0
+pydantic>=2.0
+
+[pydantic]
+pydantic>=2.0

capper-0.1.0/capper.egg-info/top_level.txt

@@ -0,0 +1 @@
+capper

capper-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "capper"
+version = "0.1.0"
+description = "Semantic, typed wrappers for Faker with automatic Polyfactory integration"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    { name = "Odos Matthews", email = "odosmatthews@gmail.com" },
+]
+dependencies = [
+    "Faker>=20.0",
+    "Polyfactory>=2.0",
+]
+
+[project.optional-dependencies]
+pydantic = [
+    "pydantic>=2.0",
+]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Documentation = "https://github.com/eddiethedean/capper#readme"
+Repository = "https://github.com/eddiethedean/capper"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["capper*"]
+
+[tool.pytest.ini_options]
+testpaths = ["capper/tests"]
+pythonpath = ["."]
+addopts = ["-v", "--tb=short"]

capper-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+