capper 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capper
-Version: 0.3.0
+Version: 0.4.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
@@ -15,6 +15,7 @@ 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"
@@ -29,7 +30,7 @@ Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
 
 [![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)](https://github.com/eddiethedean/capper/actions/workflows/ci.yml)
+[![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)
 [![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/)
 
@@ -37,11 +38,21 @@ Semantic, typed wrappers for [Faker](https://faker.readthedocs.io/) with automat
 
 **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
@@ -151,6 +162,12 @@ Use `-n`/`--count` for the number of rows and `-s`/`--seed` for reproducible out
 
 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).
 
+## 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
 
 ```bash
@@ -160,7 +177,7 @@ 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`.
+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.):
 
@@ -191,7 +208,7 @@ Releases are built and published to PyPI via [GitHub Actions](https://github.com
 
 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.
+3. Create a GitHub release (tag e.g. `v0.4.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/*`.
 

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

@@ -2,7 +2,7 @@
 
 [![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)](https://github.com/eddiethedean/capper/actions/workflows/ci.yml)
+[![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)
 [![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/)
 
@@ -10,11 +10,21 @@ Semantic, typed wrappers for [Faker](https://faker.readthedocs.io/) with automat
 
 **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
@@ -124,6 +134,12 @@ Use `-n`/`--count` for the number of rows and `-s`/`--seed` for reproducible out
 
 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).
 
+## 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
 
 ```bash
@@ -133,7 +149,7 @@ 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`.
+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.):
 
@@ -164,7 +180,7 @@ Releases are built and published to PyPI via [GitHub Actions](https://github.com
 
 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.
+3. Create a GitHub release (tag e.g. `v0.4.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/*`.
 

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

@@ -11,7 +11,7 @@ try:
 
     __version__ = _version("capper")
 except Exception:  # Package not installed (e.g. dev tree) or metadata missing
-    __version__ = "0.3.0"
+    __version__ = "0.4.0"
 
 from .barcode import EAN8, EAN13
 from .base import FakerType, faker, seed, use_faker

capper-0.4.0/capper/base.py

@@ -0,0 +1,127 @@
+"""FakerType base class and per-thread Faker proxy with automatic Polyfactory registration.
+
+The module-level ``faker`` is a proxy to a per-thread Faker instance. Each thread has its own
+Faker; ``seed(n)`` and ``use_faker(instance)`` only affect the current thread. Polyfactory's
+BaseFactory.__faker__ is set to the same proxy, so one seed per thread controls both capper
+types and built-in types. Thread-safe for concurrent use from multiple threads.
+"""
+
+import threading
+from typing import Any, cast
+
+from faker import Faker
+from polyfactory.factories.base import BaseFactory
+
+_faker_local = threading.local()
+
+
+def _get_faker() -> Faker:
+    """Return the current thread's Faker instance, creating one if needed."""
+    try:
+        instance = _faker_local.current
+    except AttributeError:
+        instance = None
+    if instance is None:
+        instance = Faker()
+        _faker_local.current = instance
+    return cast(Faker, instance)
+
+
+class _FakerProxy:
+    """Proxy that forwards all attribute access to the current thread's Faker."""
+
+    __slots__ = ()
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(_get_faker(), name)
+
+
+# Single process-wide proxy; each thread gets its own Faker via _get_faker().
+faker: Faker = _FakerProxy()  # type: ignore[assignment]
+BaseFactory.__faker__ = faker
+
+
+def seed(seed_value: int) -> None:
+    """Seed the current thread's Faker instance for reproducible data.
+
+    Args:
+        seed_value: Integer seed; same value produces the same sequence of values.
+    """
+    _get_faker().seed_instance(seed_value)
+
+
+def use_faker(instance: Faker | None) -> None:
+    """Use a custom Faker instance for the current thread only.
+
+    Sets the Faker used by Capper and Polyfactory for this thread (e.g. a
+    locale-specific Faker). Other threads are unaffected. Call before building
+    any models in this thread. Pass None to reset this thread to a new default
+    Faker (e.g. after temporarily using a custom instance).
+
+    Args:
+        instance: The Faker instance to use (e.g. Faker('de_DE')), or None to reset.
+    """
+    if instance is None or instance is faker:
+        try:
+            del _faker_local.current
+        except AttributeError:
+            pass
+    else:
+        _faker_local.current = instance
+
+
+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  # pragma: no cover — pydantic not installed
+
+    def __get_pydantic_core_schema__(
+        cls, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> CoreSchema:
+        """Validate as str then coerce to the FakerType subclass."""
+        return core_schema.no_info_after_validator_function(cls, handler(str))
+
+    FakerType.__get_pydantic_core_schema__ = classmethod(__get_pydantic_core_schema__)  # type: ignore[attr-defined]
+
+
+class FakerType(str):
+    """Base class for semantic Faker types; subclasses auto-register 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``).
+    When Hypothesis is installed, use ``st.from_type(YourFakerType)`` for property-based tests.
+    """
+
+    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[FakerType], provider_name: str) -> None:
+    """Register a FakerType subclass with Polyfactory so factories can generate values."""
+    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)
+        return str(value)
+
+    BaseFactory.add_provider(cls, _provide)

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

@@ -2,29 +2,17 @@
 
 import argparse
 import sys
-from typing import Type
+from typing import Mapping, Sequence, Type
 
 import capper
 
 from .base import FakerType, faker, seed
+from .registry import build_type_registry
 
 
-def _type_registry() -> dict[str, Type[FakerType]]:
+def _type_registry() -> Mapping[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", "use_faker"):
-            continue
-        obj = getattr(capper, name, None)
-        provider = getattr(obj, "faker_provider", None)
-        if (
-            isinstance(obj, type)
-            and issubclass(obj, FakerType)
-            and isinstance(provider, str)
-            and len(provider) > 0
-        ):
-            registry[name] = obj
-    return registry
+    return build_type_registry(capper)
 
 
 def _generate_one(typ: Type[FakerType]) -> str:
@@ -35,6 +23,15 @@ def _generate_one(typ: Type[FakerType]) -> str:
     return str(value)
 
 
+def _generate_rows(types: Sequence[Type[FakerType]], count: int) -> list[str]:
+    """Generate tab-separated rows for the given types."""
+    rows: list[str] = []
+    for _ in range(max(0, count)):
+        row = [_generate_one(t) for t in types]
+        rows.append("\t".join(row))
+    return rows
+
+
 def cmd_generate(args: argparse.Namespace) -> int:
     """Run generate subcommand."""
     registry = _type_registry()
@@ -49,10 +46,8 @@ def cmd_generate(args: argparse.Namespace) -> int:
     if args.seed is not None:
         seed(args.seed)
 
-    count = max(0, args.count)
-    for _ in range(count):
-        row = [_generate_one(t) for t in types]
-        print("\t".join(row))
+    for line in _generate_rows(types, args.count):
+        print(line)
     return 0
 
 

capper-0.4.0/capper/registry.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from types import ModuleType
+from typing import Dict, Type
+
+from .base import FakerType
+
+
+def build_type_registry(module: ModuleType) -> dict[str, Type[FakerType]]:
+    """Return a mapping of public name -> FakerType subclass for the given module.
+
+    Only names exported via ``module.__all__`` and backed by FakerType subclasses
+    with a non-empty ``faker_provider`` are included.
+    """
+    registry: Dict[str, Type[FakerType]] = {}
+    for name in getattr(module, "__all__", []):
+        obj = getattr(module, name, None)
+        provider = getattr(obj, "faker_provider", None)
+        if (
+            isinstance(obj, type)
+            and issubclass(obj, FakerType)
+            and isinstance(provider, str)
+            and len(provider) > 0
+        ):
+            registry[name] = obj
+    return registry

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

@@ -10,57 +10,15 @@ from typing import Type, TypeVar, cast
 
 from hypothesis import strategies as st
 
-from .barcode import EAN8, EAN13
+import capper
+
 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
+from .registry import build_type_registry
 
 T = TypeVar("T", bound=FakerType)
 
-# All built-in FakerType subclasses for registration
-_BUILTIN_TYPES: tuple[type[FakerType], ...] = (
-    Address,
-    City,
-    Company,
-    Country,
-    CountryCallingCode,
-    CreditCardExpiry,
-    CreditCardNumber,
-    CreditCardProvider,
-    Currency,
-    Date,
-    DateTime,
-    EAN13,
-    EAN8,
-    Email,
-    FileExtension,
-    FileName,
-    FilePath,
-    FirstName,
-    HexColor,
-    IP,
-    Job,
-    LastName,
-    Name,
-    Paragraph,
-    PhoneNumber,
-    Price,
-    Product,
-    Sentence,
-    Time,
-    URL,
-    UUID,
-    UserName,
-)
+# All built-in FakerType subclasses for registration, discovered from the public API.
+_BUILTIN_TYPES: tuple[type[FakerType], ...] = tuple(build_type_registry(capper).values())
 
 
 def for_type(cls: Type[T]) -> st.SearchStrategy[T]:

capper-0.4.0/capper/tests/benchmark_core.py

@@ -0,0 +1,56 @@
+"""Performance benchmarks for core flows (ModelFactory, DataclassFactory, Hypothesis strategy).
+
+Run with: pytest capper/tests/benchmark_core.py -v --benchmark-only
+Exclude from default test run: pytest -m 'not benchmark'
+"""
+
+from dataclasses import dataclass
+
+import pytest
+
+from capper import Email, Name
+
+
+@pytest.mark.benchmark
+def test_bench_model_factory_build(benchmark: object) -> None:
+    """Benchmark ModelFactory.build() with 2 Capper types (Name, Email)."""
+    from polyfactory.factories.pydantic_factory import ModelFactory
+    from pydantic import BaseModel
+
+    class User(BaseModel):
+        name: Name
+        email: Email
+
+    class UserFactory(ModelFactory[User]):
+        pass
+
+    benchmark(UserFactory.build)
+
+
+@pytest.mark.benchmark
+def test_bench_dataclass_factory_build(benchmark: object) -> None:
+    """Benchmark DataclassFactory.build() with 2 Capper types (Name, Email)."""
+    from polyfactory.factories import DataclassFactory
+
+    @dataclass
+    class Person:
+        name: Name
+        email: Email
+
+    class PersonFactory(DataclassFactory[Person]):
+        pass
+
+    benchmark(PersonFactory.build)
+
+
+@pytest.mark.benchmark
+def test_bench_hypothesis_strategy_example(benchmark: object) -> None:
+    """Benchmark drawing one value from st.from_type(Name) via strategy.example()."""
+    from capper import strategies
+
+    strategy = strategies.for_type(Name)
+
+    def draw_one() -> None:
+        strategy.example()
+
+    benchmark(draw_one)

capper-0.4.0/capper/tests/test_cli.py

@@ -0,0 +1,78 @@
+"""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
+
+
+@pytest.mark.skipif(sys.version_info < (3, 10), reason="capper CLI uses Python 3.10+ syntax")
+def test_type_registry_includes_known_type() -> None:
+    """Internal type registry used by CLI contains a known FakerType."""
+    assert hasattr(cli, "_type_registry")
+    registry = cli._type_registry()
+    assert "Name" in registry
+    name_type = registry["Name"]
+    assert getattr(name_type, "faker_provider", "") == "name"
+
+
+@pytest.mark.skipif(sys.version_info < (3, 10), reason="capper CLI uses Python 3.10+ syntax")
+def test_cli_unknown_type_exits_nonzero_and_stderr(capsys: pytest.CaptureFixture[str]) -> None:
+    """Passing an unknown type name prints to stderr and returns 1."""
+    orig_argv = sys.argv
+    try:
+        sys.argv = ["capper", "generate", "NonExistentType", "--count", "1"]
+        exit_code = cli.main()
+        assert exit_code == 1
+        err = capsys.readouterr().err
+        assert "Unknown type" in err
+        assert "NonExistentType" in err
+    finally:
+        sys.argv = orig_argv
+
+
+@pytest.mark.skipif(sys.version_info < (3, 10), reason="capper CLI uses Python 3.10+ syntax")
+def test_cli_seed_used() -> None:
+    """Generate with --seed runs and uses seed (deterministic output)."""
+    orig_argv = sys.argv
+    try:
+        sys.argv = ["capper", "generate", "Name", "--count", "2", "--seed", "42"]
+        exit_code = cli.main()
+        assert exit_code == 0
+    finally:
+        sys.argv = orig_argv

capper-0.4.0/capper/tests/test_edge_cases.py

@@ -0,0 +1,141 @@
+"""Edge-case tests: version fallback, use_faker/thread, registration and strategy errors."""
+
+import sys
+from unittest.mock import patch
+
+import pytest
+
+from capper import use_faker
+from capper.base import FakerType
+
+
+def test_version_fallback_when_metadata_missing() -> None:
+    """When importlib.metadata.version raises, __version__ falls back to 0.4.0."""
+    with patch("importlib.metadata.version", side_effect=Exception("no metadata")):
+        if "capper" in sys.modules:
+            del sys.modules["capper"]
+        import capper as capper_mod
+
+        assert capper_mod.__version__ == "0.4.0"
+    # Reimport so later tests see the real version
+    if "capper" in sys.modules:
+        del sys.modules["capper"]
+    import capper  # noqa: F401
+
+
+def test_use_faker_none_in_fresh_thread_covers_attribute_error() -> None:
+    """use_faker(None) in a thread that never set faker hits the except AttributeError path."""
+    result: list[Exception | None] = []
+
+    def run_in_thread() -> None:
+        try:
+            use_faker(None)
+            result.append(None)
+        except Exception as e:
+            result.append(e)
+
+    import threading
+
+    t = threading.Thread(target=run_in_thread)
+    t.start()
+    t.join()
+    assert result == [None]
+
+
+def test_register_invalid_provider_raises_attribute_error() -> None:
+    """Defining a FakerType subclass with nonexistent faker_provider raises AttributeError."""
+    with pytest.raises(AttributeError, match="Faker has no provider .nonexistent_xyz."):
+
+        class BadType(FakerType):
+            faker_provider = "nonexistent_xyz"
+
+
+def test_register_non_callable_provider_raises_type_error() -> None:
+    """When Faker has the provider name but it is not callable, _register raises TypeError."""
+    from faker import Faker
+
+    my_faker = Faker()
+    with patch.object(my_faker, "name", "not_callable"):
+        use_faker(my_faker)
+        try:
+            with pytest.raises(TypeError, match="is not callable"):
+
+                class BadCallableType(FakerType):
+                    faker_provider = "name"
+
+        finally:
+            use_faker(None)
+
+
+def test_strategies_for_type_no_provider_raises_value_error() -> None:
+    """strategies.for_type() on a class with no faker_provider raises ValueError."""
+    from capper import strategies
+
+    class NoProvider(FakerType):
+        faker_provider = ""
+
+    with pytest.raises(ValueError, match="has no faker_provider"):
+        strategies.for_type(NoProvider)
+
+
+def test_strategies_for_type_invalid_provider_raises_attribute_error() -> None:
+    """strategies.for_type() when current Faker has no such provider raises AttributeError."""
+    from capper import Name, strategies
+
+    class FakeFakerWithoutName:
+        """Minimal Faker-like object missing the 'name' provider."""
+
+        pass
+
+    use_faker(FakeFakerWithoutName())
+    try:
+        with pytest.raises(AttributeError, match="Faker has no provider"):
+            strategies.for_type(Name)
+    finally:
+        use_faker(None)
+
+
+def test_use_faker_locale_german() -> None:
+    """use_faker(Faker('de_DE')) produces locale-appropriate data; reset with use_faker(None)."""
+    from faker import Faker
+    from polyfactory.factories.pydantic_factory import ModelFactory
+    from pydantic import BaseModel
+
+    from capper import Address, Name
+
+    class User(BaseModel):
+        name: Name
+        address: Address
+
+    class UserFactory(ModelFactory[User]):
+        pass
+
+    try:
+        use_faker(Faker("de_DE"))
+        user = UserFactory.build()
+        assert len(str(user.name)) > 0
+        assert len(str(user.address)) > 0
+        # German locale often yields umlauts or typical patterns; at least non-ASCII is possible
+        combined = str(user.name) + str(user.address)
+        assert combined.isascii() or any(c in "äöüßÄÖÜ" for c in combined)
+    finally:
+        use_faker(None)
+
+
+def test_strategies_for_type_non_callable_provider_raises_type_error() -> None:
+    """strategies.for_type() when Faker's provider is not callable raises TypeError."""
+    from faker import Faker
+
+    from capper import strategies
+
+    class NotCallableProvider(FakerType):
+        faker_provider = "name"
+
+    my_faker = Faker()
+    with patch.object(my_faker, "name", "not_callable"):
+        use_faker(my_faker)
+        try:
+            with pytest.raises(TypeError, match="is not callable"):
+                strategies.for_type(NotCallableProvider)
+        finally:
+            use_faker(None)

capper-0.4.0/capper/tests/test_thread_safety.py

@@ -0,0 +1,102 @@
+"""Tests for thread-safe per-thread Faker: use_faker() and seed() are isolated per thread."""
+
+import threading
+
+from capper import Name, seed, use_faker
+from capper.base import _get_faker
+
+
+def test_use_faker_per_thread_isolation() -> None:
+    """Two threads each set use_faker() to a different locale; builds use that thread's Faker."""
+    from faker import Faker
+    from polyfactory.factories.pydantic_factory import ModelFactory
+    from pydantic import BaseModel
+
+    results: dict[str, str] = {}
+
+    def thread_de() -> None:
+        use_faker(Faker("de_DE"))
+        assert _get_faker() is not None
+
+        # Build a model; German locale often produces umlauts in names
+        class User(BaseModel):
+            name: Name
+
+        class UserFactory(ModelFactory[User]):
+            pass
+
+        user = UserFactory.build()
+        results["de"] = user.name
+
+    def thread_en() -> None:
+        use_faker(Faker("en_US"))
+        assert _get_faker() is not None
+
+        class User(BaseModel):
+            name: Name
+
+        class UserFactory(ModelFactory[User]):
+            pass
+
+        user = UserFactory.build()
+        results["en"] = user.name
+
+    t1 = threading.Thread(target=thread_de)
+    t2 = threading.Thread(target=thread_en)
+    t1.start()
+    t2.start()
+    t1.join()
+    t2.join()
+
+    assert "de" in results and "en" in results
+    assert len(results["de"]) > 0 and len(results["en"]) > 0
+
+
+def test_seed_per_thread_isolation() -> None:
+    """seed(n) in one thread does not affect another thread's sequence."""
+    from polyfactory.factories.pydantic_factory import ModelFactory
+    from pydantic import BaseModel
+
+    results: dict[str, str] = {}
+
+    def thread_seed_42() -> None:
+        seed(42)
+
+        class User(BaseModel):
+            name: Name
+
+        class UserFactory(ModelFactory[User]):
+            pass
+
+        results["42"] = UserFactory.build().name
+
+    def thread_seed_99() -> None:
+        seed(99)
+
+        class User(BaseModel):
+            name: Name
+
+        class UserFactory(ModelFactory[User]):
+            pass
+
+        results["99"] = UserFactory.build().name
+
+    t1 = threading.Thread(target=thread_seed_42)
+    t2 = threading.Thread(target=thread_seed_99)
+    t1.start()
+    t2.start()
+    t1.join()
+    t2.join()
+
+    assert "42" in results and "99" in results
+    # Same seed in same thread gives same result when run again
+    seed(42)
+
+    class User(BaseModel):
+        name: Name
+
+    class UserFactory(ModelFactory[User]):
+        pass
+
+    again = UserFactory.build().name
+    assert again == results["42"]

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

@@ -178,23 +178,17 @@ def test_seed_reproducibility(seeded_faker: None) -> None:
 
 
 def test_use_faker_switches_global_faker() -> None:
-    """use_faker() switches the global Faker; next factory build uses that instance (e.g. seed)."""
+    """use_faker() sets this thread's 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
@@ -209,4 +203,25 @@ def test_use_faker_switches_global_faker() -> None:
         user2 = UserFactory.build()
         assert user1.name == user2.name
     finally:
-        use_faker(default_faker)
+        use_faker(None)
+
+
+def test_performance_1000_builds_under_threshold() -> None:
+    """Lightweight performance gate: 1000 ModelFactory.build() calls complete in under 30s."""
+    import time
+
+    from polyfactory.factories.pydantic_factory import ModelFactory
+    from pydantic import BaseModel
+
+    class User(BaseModel):
+        name: Name
+        email: Email
+
+    class UserFactory(ModelFactory[User]):
+        pass
+
+    start = time.perf_counter()
+    for _ in range(1000):
+        UserFactory.build()
+    elapsed = time.perf_counter() - start
+    assert elapsed < 30.0, f"1000 builds took {elapsed:.1f}s (threshold 30s)"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capper
-Version: 0.3.0
+Version: 0.4.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
@@ -15,6 +15,7 @@ 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"
@@ -29,7 +30,7 @@ Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
 
 [![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)](https://github.com/eddiethedean/capper/actions/workflows/ci.yml)
+[![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)
 [![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/)
 
@@ -37,11 +38,21 @@ Semantic, typed wrappers for [Faker](https://faker.readthedocs.io/) with automat
 
 **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
@@ -151,6 +162,12 @@ Use `-n`/`--count` for the number of rows and `-s`/`--seed` for reproducible out
 
 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).
 
+## 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
 
 ```bash
@@ -160,7 +177,7 @@ 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`.
+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.):
 
@@ -191,7 +208,7 @@ Releases are built and published to PyPI via [GitHub Actions](https://github.com
 
 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.
+3. Create a GitHub release (tag e.g. `v0.4.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/*`.
 

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

@@ -14,6 +14,7 @@ capper/internet.py
 capper/misc.py
 capper/person.py
 capper/phone.py
+capper/registry.py
 capper/strategies.py
 capper/text.py
 capper.egg-info/PKG-INFO
@@ -24,9 +25,12 @@ capper.egg-info/requires.txt
 capper.egg-info/top_level.txt
 capper/examples/user_factory.py
 capper/tests/__init__.py
+capper/tests/benchmark_core.py
 capper/tests/conftest.py
 capper/tests/test_cli.py
 capper/tests/test_docs_examples.py
+capper/tests/test_edge_cases.py
 capper/tests/test_hypothesis_strategies.py
 capper/tests/test_polyfactory_integration.py
+capper/tests/test_thread_safety.py
 capper/tests/test_types.py

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

@@ -3,6 +3,7 @@ Polyfactory>=2.0
 
 [dev]
 pytest>=7.0
+pytest-benchmark>=4.0
 pytest-cov>=4.0
 pytest-xdist>=3.0
 pydantic>=2.0

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "capper"
-version = "0.3.0"
+version = "0.4.0"
 description = "Semantic, typed wrappers for Faker with automatic Polyfactory integration"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -25,6 +25,7 @@ hypothesis = [
 ]
 dev = [
     "pytest>=7.0",
+    "pytest-benchmark>=4.0",
     "pytest-cov>=4.0",
     "pytest-xdist>=3.0",
     "pydantic>=2.0",
@@ -52,6 +53,14 @@ include = ["capper*"]
 testpaths = ["capper/tests"]
 pythonpath = ["."]
 addopts = ["-v", "--tb=short"]
+markers = ["benchmark: performance benchmarks (deselect with -m 'not benchmark')"]
+
+[tool.coverage.run]
+source = ["capper"]
+omit = ["capper/tests/*"]
+
+[tool.coverage.report]
+exclude_lines = ["pragma: no cover"]
 
 [tool.ruff]
 line-length = 100

capper-0.3.0/capper/base.py

@@ -1,100 +0,0 @@
-"""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.
-
-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
-
-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 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:
-        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 auto-register 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``).
-    When Hypothesis is installed, use ``st.from_type(YourFakerType)`` for property-based tests.
-    """
-
-    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."""
-    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)
-        return str(value)
-
-    BaseFactory.add_provider(cls, _provide)

capper-0.3.0/capper/tests/test_cli.py

@@ -1,41 +0,0 @@
-"""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