Polyfactory

3.3.0 · active · verified Thu Apr 09

Polyfactory is a versatile Python library for generating mock data, primarily used for testing and development. It supports various data models, including Pydantic, SQLAlchemy, and Dataclasses, offering a flexible API for customization. The current version is 3.3.0, and it maintains an active release cadence with regular updates and feature enhancements.

Warnings

breaking The generic `Factory` class was renamed to `PolyFactory`.
Fix: Update imports from `from polyfactory.factories.base import Factory` to `from polyfactory.factories import PolyFactory`.
breaking The `create()` method now explicitly requires a persistence strategy.
Fix: When using `create()`, you must now pass a persistence strategy (e.g., `SyncPersistenceStrategy`) as an argument. The `use_api_client` parameter was also removed in v3.0.0.
gotcha Confusion between `build()` and `create()` methods.
Fix: `build()` generates an in-memory instance without any persistence, useful for simple object creation. `create()` is designed to persist the generated data and requires a `PersistenceStrategy` to do so (e.g., saving to a database or calling an API).
gotcha Defining the target model for generic `PolyFactory` instances.
Fix: For generic factories, the `__model__` attribute should be defined as a class variable within the `PolyFactory` subclass itself, rather than being passed as an argument to `build()` or `create()` methods (which is now deprecated for this purpose).
gotcha Using the generic `PolyFactory` when a specific factory type is available.
Fix: For Pydantic models, use `ModelFactory`. For Dataclasses, use `DataclassFactory`. These specific factories offer tailored functionality and better integration than configuring `PolyFactory` with `__model__`.

Install

pip install polyfactory Core library
pip install 'polyfactory[pydantic]' With Pydantic support (common)

Imports

ModelFactory

from polyfactory.factories import ModelFactory

PolyFactory
```
from polyfactory.factories import PolyFactory
```
The generic 'Factory' class was renamed to 'PolyFactory' in v3.0.0.

SyncPersistenceStrategy

from polyfactory.persistence import SyncPersistenceStrategy

AsyncPersistenceStrategy

from polyfactory.persistence import AsyncPersistenceStrategy

Quickstart

This example demonstrates how to use `ModelFactory` to generate mock Pydantic model instances. `ModelFactory.build()` creates a single instance in memory, while `ModelFactory.batch()` creates a list of instances. For persistence, a `PersistenceStrategy` would be required with `ModelFactory.create()`.

from polyfactory.factories import ModelFactory
from pydantic import BaseModel
from datetime import date

class User(BaseModel):
    name: str
    email: str
    age: int
    is_active: bool = True
    joined_date: date

# Build a single instance (in-memory, no persistence)
user_instance = ModelFactory.build(User)
print(f"Generated User: {user_instance.model_dump_json(indent=2)}")

# Build multiple instances (in-memory list)
users_batch = ModelFactory.batch(User, size=3)
print(f"\nGenerated Users Batch (first item): {users_batch[0].model_dump_json(indent=2)}")

view raw JSON →