capper 0.2.0__tar.gz → 0.3.0__tar.gz

{capper-0.2.0 → capper-0.3.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: capper
-Version: 0.2.0
+Version: 0.3.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
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: Faker>=20.0
 Requires-Dist: Polyfactory>=2.0
@@ -21,11 +21,14 @@ 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"
 
 # Capper
 
 [![PyPI](https://img.shields.io/pypi/v/capper.svg)](https://pypi.org/project/capper/)
-[![Python](https://img.shields.io/badge/python-3.9+-blue.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)](https://github.com/eddiethedean/capper/actions/workflows/ci.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/)
@@ -47,7 +50,7 @@ Semantic, typed wrappers for [Faker](https://faker.readthedocs.io/) with automat
 pip install capper
 ```
 
-Requires **Python 3.9+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. Optional extras:
+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]`
@@ -121,6 +124,10 @@ Works automatically. No extra steps. IDE autocompletion.
 - **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](https://github.com/eddiethedean/capper/blob/main/docs/FAKER_PROVIDERS.md) for the Faker provider used by each type.
@@ -142,7 +149,7 @@ Use `-n`/`--count` for the number of rows and `-s`/`--seed` for reproducible out
 
 ## 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.
+Capper targets **Python 3.10+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. For version ranges, upgrade guidance, and the deprecation policy, see [Compatibility](docs/compatibility.md).
 
 ## Development
 
@@ -176,20 +183,23 @@ 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.
+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](docs/user_guides/reproducible_data.md#locales-and-custom-faker).
 
 ## 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.2.0`). The workflow runs tests, builds the package, and uploads to PyPI.
+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.3.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/*`.
 
 ## 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

{capper-0.2.0 → capper-0.3.0}/README.md

@@ -1,7 +1,7 @@
 # Capper
 
 [![PyPI](https://img.shields.io/pypi/v/capper.svg)](https://pypi.org/project/capper/)
-[![Python](https://img.shields.io/badge/python-3.9+-blue.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)](https://github.com/eddiethedean/capper/actions/workflows/ci.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/)
@@ -23,7 +23,7 @@ Semantic, typed wrappers for [Faker](https://faker.readthedocs.io/) with automat
 pip install capper
 ```
 
-Requires **Python 3.9+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. Optional extras:
+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]`
@@ -97,6 +97,10 @@ Works automatically. No extra steps. IDE autocompletion.
 - **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](https://github.com/eddiethedean/capper/blob/main/docs/FAKER_PROVIDERS.md) for the Faker provider used by each type.
@@ -118,7 +122,7 @@ Use `-n`/`--count` for the number of rows and `-s`/`--seed` for reproducible out
 
 ## 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.
+Capper targets **Python 3.10+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. For version ranges, upgrade guidance, and the deprecation policy, see [Compatibility](docs/compatibility.md).
 
 ## Development
 
@@ -152,20 +156,23 @@ 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.
+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](docs/user_guides/reproducible_data.md#locales-and-custom-faker).
 
 ## 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.2.0`). The workflow runs tests, builds the package, and uploads to PyPI.
+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.3.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/*`.
 
 ## 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

{capper-0.2.0 → capper-0.3.0}/capper/__init__.py

@@ -6,12 +6,23 @@ With Hypothesis installed (pip install capper[hypothesis]), import capper.strate
 and use st.from_type(Name) for property-based tests.
 """
 
-from .base import FakerType, faker, seed
+try:
+    from importlib.metadata import version as _version
+
+    __version__ = _version("capper")
+except Exception:  # Package not installed (e.g. dev tree) or metadata missing
+    __version__ = "0.3.0"
+
+from .barcode import EAN8, EAN13
+from .base import FakerType, faker, seed, use_faker
+from .color import HexColor
 from .commerce import Company, Currency, Price, Product
 from .date_time import Date, DateTime, Time
+from .file import FileExtension, FileName, FilePath
 from .finance import CreditCardExpiry, CreditCardNumber, CreditCardProvider
 from .geo import Address, City, Country
 from .internet import IP, URL, Email, UserName
+from .misc import UUID
 from .person import FirstName, Job, LastName, Name
 from .phone import CountryCallingCode, PhoneNumber
 from .text import Paragraph, Sentence
@@ -28,9 +39,15 @@ __all__ = [
     "Currency",
     "Date",
     "DateTime",
+    "EAN13",
+    "EAN8",
     "Email",
     "FakerType",
+    "FileExtension",
+    "FileName",
+    "FilePath",
     "FirstName",
+    "HexColor",
     "IP",
     "Job",
     "LastName",
@@ -42,7 +59,9 @@ __all__ = [
     "Sentence",
     "Time",
     "URL",
+    "UUID",
     "UserName",
     "faker",
     "seed",
+    "use_faker",
 ]

capper-0.3.0/capper/barcode.py

@@ -0,0 +1,15 @@
+"""Barcode-related semantic Faker types."""
+
+from .base import FakerType
+
+
+class EAN13(FakerType):
+    """EAN-13 barcode. Uses Faker provider ``ean13``."""
+
+    faker_provider = "ean13"
+
+
+class EAN8(FakerType):
+    """EAN-8 barcode. Uses Faker provider ``ean8``."""
+
+    faker_provider = "ean8"

{capper-0.2.0 → capper-0.3.0}/capper/base.py

@@ -2,6 +2,9 @@
 
 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.
+
+Note: The shared ``faker`` and ``use_faker()`` are not thread-safe; do not switch
+the global Faker from multiple threads while building models.
 """
 
 from typing import Any
@@ -24,6 +27,24 @@ def seed(seed_value: int) -> None:
     faker.seed_instance(seed_value)
 
 
+def use_faker(instance: Faker) -> None:
+    """Use a custom Faker instance for both Capper and Polyfactory.
+
+    Replaces the module-level faker and Polyfactory's BaseFactory.__faker__
+    so that one instance (e.g. a locale-specific Faker) is used everywhere.
+    Call before building any models.
+
+    Note: The shared faker is not thread-safe. Do not call use_faker() from
+    multiple threads while other threads are building models.
+
+    Args:
+        instance: The Faker instance to use (e.g. Faker('de_DE')).
+    """
+    global faker
+    faker = instance
+    BaseFactory.__faker__ = instance
+
+
 def _install_pydantic_schema() -> None:
     """If Pydantic is available, attach __get_pydantic_core_schema__ to FakerType."""
     try:
@@ -62,7 +83,15 @@ _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 {}
+    if not hasattr(faker, provider_name):
+        raise AttributeError(
+            f"Faker has no provider {provider_name!r} (used by {cls.__name__}). "
+            "Check faker_provider on the type."
+        )
+    provider_fn = getattr(faker, provider_name)
+    if not callable(provider_fn):
+        raise TypeError(f"Faker.{provider_name} is not callable (used by {cls.__name__}).")
+    provider_kwargs = dict(getattr(cls, "faker_kwargs", None) or {})
 
     def _provide() -> str:
         value = getattr(faker, provider_name)(**provider_kwargs)

{capper-0.2.0 → capper-0.3.0}/capper/cli.py

@@ -13,7 +13,7 @@ def _type_registry() -> dict[str, Type[FakerType]]:
     """Map type name -> FakerType subclass (only types with faker_provider)."""
     registry: dict[str, Type[FakerType]] = {}
     for name in getattr(capper, "__all__", []):
-        if name in ("FakerType", "faker", "seed"):
+        if name in ("FakerType", "faker", "seed", "use_faker"):
             continue
         obj = getattr(capper, name, None)
         provider = getattr(obj, "faker_provider", None)

capper-0.3.0/capper/color.py

@@ -0,0 +1,10 @@
+"""Color-related semantic Faker types."""
+
+from .base import FakerType
+
+
+class HexColor(FakerType):
+    """Hex color string (e.g. #ff5500). Uses Faker provider ``color`` with hex format."""
+
+    faker_provider = "color"
+    faker_kwargs = {"color_format": "hex"}

capper-0.3.0/capper/file.py

@@ -0,0 +1,21 @@
+"""File-related semantic Faker types (path, name, extension)."""
+
+from .base import FakerType
+
+
+class FilePath(FakerType):
+    """File path. Uses Faker provider ``file_path``."""
+
+    faker_provider = "file_path"
+
+
+class FileName(FakerType):
+    """File name with extension. Uses Faker provider ``file_name``."""
+
+    faker_provider = "file_name"
+
+
+class FileExtension(FakerType):
+    """File extension. Uses Faker provider ``file_extension``."""
+
+    faker_provider = "file_extension"

capper-0.3.0/capper/misc.py

@@ -0,0 +1,9 @@
+"""Miscellaneous semantic Faker types (e.g. UUID)."""
+
+from .base import FakerType
+
+
+class UUID(FakerType):
+    """UUID v4 string. Uses Faker provider ``uuid4``."""
+
+    faker_provider = "uuid4"

{capper-0.2.0 → capper-0.3.0}/capper/strategies.py

@@ -4,16 +4,22 @@ Use ``st.from_type(Name)`` after importing capper and capper.strategies, or call
 ``strategies.for_type(Name)`` to get a strategy that generates instances of that type.
 """
 
-from typing import Type, TypeVar
+from __future__ import annotations
+
+from typing import Type, TypeVar, cast
 
 from hypothesis import strategies as st
 
+from .barcode import EAN8, EAN13
 from .base import FakerType, faker
+from .color import HexColor
 from .commerce import Company, Currency, Price, Product
 from .date_time import Date, DateTime, Time
+from .file import FileExtension, FileName, FilePath
 from .finance import CreditCardExpiry, CreditCardNumber, CreditCardProvider
 from .geo import Address, City, Country
 from .internet import IP, URL, Email, UserName
+from .misc import UUID
 from .person import FirstName, Job, LastName, Name
 from .phone import CountryCallingCode, PhoneNumber
 from .text import Paragraph, Sentence
@@ -33,8 +39,14 @@ _BUILTIN_TYPES: tuple[type[FakerType], ...] = (
     Currency,
     Date,
     DateTime,
+    EAN13,
+    EAN8,
     Email,
+    FileExtension,
+    FileName,
+    FilePath,
     FirstName,
+    HexColor,
     IP,
     Job,
     LastName,
@@ -46,6 +58,7 @@ _BUILTIN_TYPES: tuple[type[FakerType], ...] = (
     Sentence,
     Time,
     URL,
+    UUID,
     UserName,
 )
 
@@ -55,6 +68,13 @@ def for_type(cls: Type[T]) -> st.SearchStrategy[T]:
     provider = getattr(cls, "faker_provider", None)
     if not provider:
         raise ValueError(f"{cls.__name__} has no faker_provider")
+    if not hasattr(faker, provider):
+        raise AttributeError(
+            f"Faker has no provider {provider!r} (used by {cls.__name__}). "
+            "Check faker_provider on the type."
+        )
+    if not callable(getattr(faker, provider)):
+        raise TypeError(f"Faker.{provider} is not callable (used by {cls.__name__}).")
     kwargs = getattr(cls, "faker_kwargs", None) or {}
 
     @st.composite
@@ -64,7 +84,7 @@ def for_type(cls: Type[T]) -> st.SearchStrategy[T]:
         value = getattr(faker, provider)(**kwargs)
         return cls(str(value))
 
-    return _draw()
+    return cast(st.SearchStrategy[T], _draw())
 
 
 def _register_strategies() -> None:

capper-0.3.0/capper/tests/test_cli.py

@@ -0,0 +1,41 @@
+"""Tests for the capper CLI (generate subcommand)."""
+
+import sys
+
+import pytest
+
+if sys.version_info >= (3, 10):
+    from capper import cli
+else:
+    cli = None  # type: ignore[assignment]
+
+
+@pytest.mark.skipif(sys.version_info < (3, 10), reason="capper CLI uses Python 3.10+ syntax")
+def test_cli_generate_exit_zero_and_non_empty_output() -> None:
+    """Invoke generate subcommand; assert exit 0 and non-empty output for a known type."""
+    orig_argv = sys.argv
+    try:
+        sys.argv = ["capper", "generate", "Name", "--count", "1"]
+        exit_code = cli.main()
+        assert exit_code == 0
+    finally:
+        sys.argv = orig_argv
+
+
+@pytest.mark.skipif(sys.version_info < (3, 10), reason="capper CLI uses Python 3.10+ syntax")
+def test_cli_generate_produces_output(capsys: pytest.CaptureFixture[str]) -> None:
+    """Generate subcommand prints one tab-separated value per row."""
+    orig_argv = sys.argv
+    try:
+        sys.argv = ["capper", "generate", "Name", "Email", "--count", "2"]
+        exit_code = cli.main()
+        assert exit_code == 0
+        out = capsys.readouterr().out
+        lines = [line for line in out.strip().splitlines() if line.strip()]
+        assert len(lines) == 2
+        for line in lines:
+            parts = line.split("\t")
+            assert len(parts) == 2
+            assert len(parts[0]) > 0 and len(parts[1]) > 0
+    finally:
+        sys.argv = orig_argv

{capper-0.2.0 → capper-0.3.0}/capper/tests/test_types.py

@@ -3,8 +3,11 @@
 import pytest
 
 from capper import (
+    EAN8,
+    EAN13,
     IP,
     URL,
+    UUID,
     Address,
     City,
     Company,
@@ -17,7 +20,11 @@ from capper import (
     Date,
     DateTime,
     Email,
+    FileExtension,
+    FileName,
+    FilePath,
     FirstName,
+    HexColor,
     Job,
     LastName,
     Name,
@@ -59,6 +66,13 @@ from capper import (
         CreditCardNumber,
         CreditCardExpiry,
         CreditCardProvider,
+        FilePath,
+        FileName,
+        FileExtension,
+        UUID,
+        HexColor,
+        EAN13,
+        EAN8,
     ],
 )
 def test_type_generates_non_empty_string(type_class: type) -> None:
@@ -67,14 +81,27 @@ def test_type_generates_non_empty_string(type_class: type) -> None:
 
     faker = Faker()
     provider_name = getattr(type_class, "faker_provider")
-    value = getattr(faker, provider_name)()
+    kwargs = getattr(type_class, "faker_kwargs", None) or {}
+    value = getattr(faker, provider_name)(**kwargs)
     assert isinstance(value, (str, type_class))
     assert len(str(value)) > 0
 
 
 @pytest.mark.parametrize(
     "type_class",
-    [Name, Email, PhoneNumber, FirstName, Address, Sentence, CreditCardNumber],
+    [
+        Name,
+        Email,
+        PhoneNumber,
+        FirstName,
+        Address,
+        Sentence,
+        CreditCardNumber,
+        FilePath,
+        UUID,
+        HexColor,
+        EAN13,
+    ],
 )
 def test_model_factory_builds_capper_type(type_class: type) -> None:
     """Pydantic model with one capper type via ModelFactory; asserts non-empty and type."""
@@ -121,6 +148,15 @@ def test_faker_kwargs_support() -> None:
     assert isinstance(instance.text, (str, ShortSentence)) and len(instance.text) > 0
 
 
+def test_hex_color_format() -> None:
+    """HexColor yields a string starting with #."""
+    from faker import Faker
+
+    faker = Faker()
+    value = faker.color(color_format="hex")
+    assert isinstance(value, str) and value.startswith("#") and len(value) == 7
+
+
 def test_seed_reproducibility(seeded_faker: None) -> None:
     """Builds twice after seeding with same value; asserts identical generated name."""
     from polyfactory.factories.pydantic_factory import ModelFactory
@@ -139,3 +175,38 @@ def test_seed_reproducibility(seeded_faker: None) -> None:
     seed(42)
     user2 = UserFactory.build()
     assert user1.name == user2.name
+
+
+def test_use_faker_switches_global_faker() -> None:
+    """use_faker() switches the global Faker; next factory build uses that instance (e.g. seed)."""
+    from faker import Faker
+    from polyfactory.factories.base import BaseFactory
+    from polyfactory.factories.pydantic_factory import ModelFactory
+    from pydantic import BaseModel
+
+    from capper import Name, use_faker
+    from capper import faker as default_faker
+
+    try:
+        custom = Faker()
+        custom.seed_instance(123)
+        use_faker(custom)
+        from capper.base import faker as module_faker
+
+        assert module_faker is custom
+        assert BaseFactory.__faker__ is custom
+
+        class User(BaseModel):
+            name: Name
+
+        class UserFactory(ModelFactory[User]):
+            pass
+
+        seed_val = 999
+        custom.seed_instance(seed_val)
+        user1 = UserFactory.build()
+        custom.seed_instance(seed_val)
+        user2 = UserFactory.build()
+        assert user1.name == user2.name
+    finally:
+        use_faker(default_faker)

{capper-0.2.0 → capper-0.3.0}/capper.egg-info/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: capper
-Version: 0.2.0
+Version: 0.3.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
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: Faker>=20.0
 Requires-Dist: Polyfactory>=2.0
@@ -21,11 +21,14 @@ 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"
 
 # Capper
 
 [![PyPI](https://img.shields.io/pypi/v/capper.svg)](https://pypi.org/project/capper/)
-[![Python](https://img.shields.io/badge/python-3.9+-blue.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)](https://github.com/eddiethedean/capper/actions/workflows/ci.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/)
@@ -47,7 +50,7 @@ Semantic, typed wrappers for [Faker](https://faker.readthedocs.io/) with automat
 pip install capper
 ```
 
-Requires **Python 3.9+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. Optional extras:
+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]`
@@ -121,6 +124,10 @@ Works automatically. No extra steps. IDE autocompletion.
 - **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](https://github.com/eddiethedean/capper/blob/main/docs/FAKER_PROVIDERS.md) for the Faker provider used by each type.
@@ -142,7 +149,7 @@ Use `-n`/`--count` for the number of rows and `-s`/`--seed` for reproducible out
 
 ## 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.
+Capper targets **Python 3.10+**, **Faker >= 20.0**, and **Polyfactory >= 2.0**. For version ranges, upgrade guidance, and the deprecation policy, see [Compatibility](docs/compatibility.md).
 
 ## Development
 
@@ -176,20 +183,23 @@ 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.
+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](docs/user_guides/reproducible_data.md#locales-and-custom-faker).
 
 ## 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.2.0`). The workflow runs tests, builds the package, and uploads to PyPI.
+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.3.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/*`.
 
 ## 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

{capper-0.2.0 → capper-0.3.0}/capper.egg-info/SOURCES.txt

@@ -1,13 +1,17 @@
 README.md
 pyproject.toml
 capper/__init__.py
+capper/barcode.py
 capper/base.py
 capper/cli.py
+capper/color.py
 capper/commerce.py
 capper/date_time.py
+capper/file.py
 capper/finance.py
 capper/geo.py
 capper/internet.py
+capper/misc.py
 capper/person.py
 capper/phone.py
 capper/strategies.py
@@ -21,6 +25,7 @@ capper.egg-info/top_level.txt
 capper/examples/user_factory.py
 capper/tests/__init__.py
 capper/tests/conftest.py
+capper/tests/test_cli.py
 capper/tests/test_docs_examples.py
 capper/tests/test_hypothesis_strategies.py
 capper/tests/test_polyfactory_integration.py

{capper-0.2.0 → capper-0.3.0}/capper.egg-info/requires.txt

@@ -10,6 +10,10 @@ ruff>=0.4
 mypy>=1.0
 hypothesis>=6.0
 
+[docs]
+mkdocs>=1.5
+mkdocstrings[python]>=0.24
+
 [hypothesis]
 hypothesis>=6.0
 

{capper-0.2.0 → capper-0.3.0}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "capper"
-version = "0.2.0"
+version = "0.3.0"
 description = "Semantic, typed wrappers for Faker with automatic Polyfactory integration"
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 authors = [
     { name = "Odos Matthews", email = "odosmatthews@gmail.com" },
 ]
@@ -32,6 +32,10 @@ dev = [
     "mypy>=1.0",
     "hypothesis>=6.0",
 ]
+docs = [
+    "mkdocs>=1.5",
+    "mkdocstrings[python]>=0.24",
+]
 
 [project.urls]
 Documentation = "https://github.com/eddiethedean/capper#readme"
@@ -51,14 +55,15 @@ addopts = ["-v", "--tb=short"]
 
 [tool.ruff]
 line-length = 100
-target-version = "py39"
+target-version = "py310"
 exclude = ["docs/notebooks"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I"]
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.10"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = false
+exclude = ["capper/tests"]