API Reference

Programmatic API for Capper: the main package, the shared Faker instance, and the base type.

Public API surface

Capper’s public API (stable pre-1.0) consists of:

  • Modules
  • capper — semantic types, Faker proxy, and helpers.
  • capper.strategies — Hypothesis integration (for_type and st.from_type(...) once imported).
  • Objects
  • Semantic types imported from capper (e.g. Name, Email, Address, Price, UUID, EAN13).
  • FakerType, faker, faker_field, seed, use_faker from capper.
  • for_type from capper.strategies.

Internal helpers and modules not listed here may change between releases.

Package: capper

Top-level exports: semantic types (Name, Email, etc.), FakerType, faker, faker_field, seed, and use_faker. Import with from capper import Name, Email, faker_field, seed.

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. With Hypothesis installed (pip install capper[hypothesis]), import capper.strategies and use st.from_type(Name) for property-based tests.

Address

Bases: FakerType

Street address. Uses Faker provider address.

City

Bases: FakerType

City name. Uses Faker provider city.

Company

Bases: FakerType

Company name. Uses Faker provider company.

Country

Bases: FakerType

Country name. Uses Faker provider country.

CountryCallingCode

Bases: FakerType

Country calling code. Uses Faker provider country_calling_code.

CreditCardExpiry

Bases: FakerType

Credit card expiry string. Uses Faker provider credit_card_expire.

CreditCardNumber

Bases: FakerType

Credit card number string. Uses Faker provider credit_card_number.

CreditCardProvider

Bases: FakerType

Credit card provider name. Uses Faker provider credit_card_provider.

Currency

Bases: FakerType

Currency code. Uses Faker provider currency_code.

Date

Bases: FakerType

Date string. Uses Faker provider date.

DateTime

Bases: FakerType

ISO 8601 datetime string. Uses Faker provider iso8601.

EAN13

Bases: FakerType

EAN-13 barcode. Uses Faker provider ean13.

EAN8

Bases: FakerType

EAN-8 barcode. Uses Faker provider ean8.

Email

Bases: FakerType

Email address. Uses Faker provider email.

FakerType

Bases: 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.

FakerType subclasses are nominal string types: they distinguish fields in models and factories but do not validate string format when values are supplied manually (e.g. via Pydantic model_validate).

FileExtension

Bases: FakerType

File extension. Uses Faker provider file_extension.

FileName

Bases: FakerType

File name with extension. Uses Faker provider file_name.

FilePath

Bases: FakerType

File path. Uses Faker provider file_path.

FirstName

Bases: FakerType

First/given name. Uses Faker provider first_name.

HexColor

Bases: FakerType

Hex color string (e.g. #ff5500). Uses Faker provider color with hex format.

IP

Bases: FakerType

IPv4 address. Uses Faker provider ipv4.

Job

Bases: FakerType

Job title. Uses Faker provider job.

LastName

Bases: FakerType

Last/family name. Uses Faker provider last_name.

Name

Bases: FakerType

Full name. Uses Faker provider name.

Paragraph

Bases: FakerType

Paragraph of text. Uses Faker provider paragraph.

PhoneNumber

Bases: FakerType

Phone number string. Uses Faker provider phone_number.

Price

Bases: FakerType

Price tag string. Uses Faker provider pricetag.

Product

Bases: FakerType

Product/catch phrase. Uses Faker provider catch_phrase.

Sentence

Bases: FakerType

Single sentence. Uses Faker provider sentence.

Time

Bases: FakerType

Time string. Uses Faker provider time.

URL

Bases: FakerType

URL. Uses Faker provider url.

UUID

Bases: FakerType

UUID v4 string. Uses Faker provider uuid4.

UserName

Bases: FakerType

Username. Uses Faker provider user_name.

faker_field(type_class, **kwargs)

Return a callable for use as a Polyfactory field override with Faker kwargs.

Assign the result to a factory attribute so that field is generated using the given FakerType's provider with the specified keyword arguments. Polyfactory invokes the callable at build time. Uses the shared per-thread Faker (same as seed() and use_faker()).

Example::

from pydantic import BaseModel
from polyfactory.factories.pydantic_factory import ModelFactory
from capper import Sentence, faker_field

class Post(BaseModel):
    summary: Sentence
    body: Sentence

class PostFactory(ModelFactory[Post]):
    summary = faker_field(Sentence, nb_words=5)
    body = faker_field(Sentence, nb_words=20)
Parameters:
  • type_class (type[T]) –

    A FakerType subclass (e.g. Sentence, Date).

  • **kwargs (Any, default: {} ) –

    Keyword arguments passed to the Faker provider (e.g. nb_words=5).
Returns:
  • Callable[[], T] –

    A no-argument callable that returns an instance of type_class.
Raises:
  • AttributeError –

    If type_class has no faker_provider or Faker has no such provider.

  • TypeError –

    If the Faker provider is not callable.

seed(seed_value)

Seed the current thread's Faker instance for reproducible data.

Parameters:
  • seed_value (int) –

    Integer seed; same value produces the same sequence of values.
Raises:
  • TypeError –

    If seed_value is not an int.

use_faker(instance)

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).

Parameters:
  • instance (Faker | None) –

    The Faker instance to use (e.g. Faker('de_DE')), or None to reset.
Raises:
  • TypeError –

    If instance is not None, not the capper faker proxy, and not a Faker.

Base: FakerType, faker, seed, use_faker

The base class and shared per-thread Faker instance. Use seed(n) for reproducibility; use use_faker(instance) to switch to a custom Faker (e.g. locale-specific) for the current thread.

Bases: 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.

FakerType subclasses are nominal string types: they distinguish fields in models and factories but do not validate string format when values are supplied manually (e.g. via Pydantic model_validate).

Seed the current thread's Faker instance for reproducible data.

Parameters:
  • seed_value (int) –

    Integer seed; same value produces the same sequence of values.
Raises:
  • TypeError –

    If seed_value is not an int.

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).

Parameters:
  • instance (Faker | None) –

    The Faker instance to use (e.g. Faker('de_DE')), or None to reset.
Raises:
  • TypeError –

    If instance is not None, not the capper faker proxy, and not a Faker.

Field helpers (Polyfactory-style)

Use faker_field(Type, **kwargs) on a factory class to generate a field with custom Faker provider arguments. Polyfactory invokes the returned callable at build time.

Return a callable for use as a Polyfactory field override with Faker kwargs.

Assign the result to a factory attribute so that field is generated using the given FakerType's provider with the specified keyword arguments. Polyfactory invokes the callable at build time. Uses the shared per-thread Faker (same as seed() and use_faker()).

Example::

from pydantic import BaseModel
from polyfactory.factories.pydantic_factory import ModelFactory
from capper import Sentence, faker_field

class Post(BaseModel):
    summary: Sentence
    body: Sentence

class PostFactory(ModelFactory[Post]):
    summary = faker_field(Sentence, nb_words=5)
    body = faker_field(Sentence, nb_words=20)
Parameters:
  • type_class (type[T]) –

    A FakerType subclass (e.g. Sentence, Date).

  • **kwargs (Any, default: {} ) –

    Keyword arguments passed to the Faker provider (e.g. nb_words=5).
Returns:
  • Callable[[], T] –

    A no-argument callable that returns an instance of type_class.
Raises:
  • AttributeError –

    If type_class has no faker_provider or Faker has no such provider.

  • TypeError –

    If the Faker provider is not callable.

Semantic types

All semantic types are subclasses of FakerType and are used as type annotations in your models. For the full list and the Faker provider used by each, see Faker providers.

Categories: 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), File (FilePath, FileName, FileExtension), Misc (UUID), Color (HexColor), Barcode (EAN13, EAN8).