In this tutorial, we walk through an advanced, end-to-end exploration of Polyfactory, focusing on how we can generate rich, realistic mock data directly from Python type hints. We start by setting up the environment and progressively build factories for data classes, Pydantic models, and attrs-based classes, while demonstrating customization, overrides, calculated fields, and the generation of nested objects. As we move through each snippet, we show how we can control randomness, enforce constraints, and model real-world structures, making this tutorial directly applicable to testing, prototyping, and data-driven development workflows. Check out the FULL CODES here.
import subprocess
import sys
def install_package(package):
subprocess.check_call([sys.executable, "-m", "pip", "install", "-q", package])
packages = [
"polyfactory",
"pydantic",
"email-validator",
"faker",
"msgspec",
"attrs"
]
for package in packages:
try:
install_package(package)
print(f"✓ Installed {package}")
except Exception as e:
print(f"✗ Failed to install {package}: {e}")
print("\n")
print("=" * 80)
print("SECTION 2: Basic Dataclass Factories")
print("=" * 80)
from dataclasses import dataclass
from typing import List, Optional
from datetime import datetime, date
from uuid import UUID
from polyfactory.factories import DataclassFactory
@dataclass
class Address:
street: str
city: str
country: str
zip_code: str
@dataclass
class Person:
id: UUID
name: str
email: str
age: int
birth_date: date
is_active: bool
address: Address
phone_numbers: List[str]
bio: Optional[str] = None
class PersonFactory(DataclassFactory[Person]):
pass
person = PersonFactory.build()
print(f"Generated Person:")
print(f" ID: {person.id}")
print(f" Name: {person.name}")
print(f" Email: {person.email}")
print(f" Age: {person.age}")
print(f" Address: {person.address.city}, {person.address.country}")
print(f" Phone Numbers: {person.phone_numbers[:2]}")
print()
people = PersonFactory.batch(5)
print(f"Generated {len(people)} people:")
for i, p in enumerate(people, 1):
print(f" {i}. {p.name} - {p.email}")
print("\n")We set up the environment and ensure all required dependencies are installed. We also introduce the core idea of using Polyfactory to generate mock data from type hints. By initializing the basic dataclass factories, we establish the foundation for all subsequent examples.
print("=" * 80)
print("SECTION 3: Customizing Factory Behavior")
print("=" * 80)
from faker import Faker
from polyfactory.fields import Use, Ignore
@dataclass
class Employee:
employee_id: str
full_name: str
department: str
salary: float
hire_date: date
is_manager: bool
email: str
internal_notes: Optional[str] = None
class EmployeeFactory(DataclassFactory[Employee]):
__faker__ = Faker(locale="en_US")
__random_seed__ = 42
@classmethod
def employee_id(cls) -> str:
return f"EMP-{cls.__random__.randint(10000, 99999)}"
@classmethod
def full_name(cls) -> str:
return cls.__faker__.name()
@classmethod
def department(cls) -> str:
departments = ["Engineering", "Marketing", "Sales", "HR", "Finance"]
return cls.__random__.choice(departments)
@classmethod
def salary(cls) -> float:
return round(cls.__random__.uniform(50000, 150000), 2)
@classmethod
def email(cls) -> str:
return cls.__faker__.company_email()
employees = EmployeeFactory.batch(3)
print("Generated Employees:")
for emp in employees:
print(f" {emp.employee_id}: {emp.full_name}")
print(f" Department: {emp.department}")
print(f" Salary: ${emp.salary:,.2f}")
print(f" Email: {emp.email}")
print()
print()
print("=" * 80)
print("SECTION 4: Field Constraints and Calculated Fields")
print("=" * 80)
@dataclass
class Product:
product_id: str
name: str
description: str
price: float
discount_percentage: float
stock_quantity: int
final_price: Optional[float] = None
sku: Optional[str] = None
class ProductFactory(DataclassFactory[Product]):
@classmethod
def product_id(cls) -> str:
return f"PROD-{cls.__random__.randint(1000, 9999)}"
@classmethod
def name(cls) -> str:
adjectives = ["Premium", "Deluxe", "Classic", "Modern", "Eco"]
nouns = ["Widget", "Gadget", "Device", "Tool", "Appliance"]
return f"{cls.__random__.choice(adjectives)} {cls.__random__.choice(nouns)}"
@classmethod
def price(cls) -> float:
return round(cls.__random__.uniform(10.0, 1000.0), 2)
@classmethod
def discount_percentage(cls) -> float:
return round(cls.__random__.uniform(0, 30), 2)
@classmethod
def stock_quantity(cls) -> int:
return cls.__random__.randint(0, 500)
@classmethod
def build(cls, **kwargs):
instance = super().build(**kwargs)
if instance.final_price is None:
instance.final_price = round(
instance.price * (1 - instance.discount_percentage / 100), 2
)
if instance.sku is None:
name_part = instance.name.replace(" ", "-").upper()[:10]
instance.sku = f"{instance.product_id}-{name_part}"
return instance
products = ProductFactory.batch(3)
print("Generated Products:")
for prod in products:
print(f" {prod.sku}")
print(f" Name: {prod.name}")
print(f" Price: ${prod.price:.2f}")
print(f" Discount: {prod.discount_percentage}%")
print(f" Final Price: ${prod.final_price:.2f}")
print(f" Stock: {prod.stock_quantity} units")
print()
print()We focus on generating simple but realistic mock data using dataclasses and default Polyfactory behavior. We show how to quickly create single instances and batches without writing any custom logic. It helps us validate how Polyfactory automatically interprets type hints to populate nested structures.
print("=" * 80)
print("SECTION 6: Complex Nested Structures")
print("=" * 80)
from enum import Enum
class OrderStatus(str, Enum):
PENDING = "pending"
PROCESSING = "processing"
SHIPPED = "shipped"
DELIVERED = "delivered"
CANCELLED = "cancelled"
@dataclass
class OrderItem:
product_name: str
quantity: int
unit_price: float
total_price: Optional[float] = None
@dataclass
class ShippingInfo:
carrier: str
tracking_number: str
estimated_delivery: date
@dataclass
class Order:
order_id: str
customer_name: str
customer_email: str
status: OrderStatus
items: List[OrderItem]
order_date: datetime
shipping_info: Optional[ShippingInfo] = None
total_amount: Optional[float] = None
notes: Optional[str] = None
class OrderItemFactory(DataclassFactory[OrderItem]):
@classmethod
def product_name(cls) -> str:
products = ["Laptop", "Mouse", "Keyboard", "Monitor", "Headphones",
"Webcam", "USB Cable", "Phone Case", "Charger", "Tablet"]
return cls.__random__.choice(products)
@classmethod
def quantity(cls) -> int:
return cls.__random__.randint(1, 5)
@classmethod
def unit_price(cls) -> float:
return round(cls.__random__.uniform(5.0, 500.0), 2)
@classmethod
def build(cls, **kwargs):
instance = super().build(**kwargs)
if instance.total_price is None:
instance.total_price = round(instance.quantity * instance.unit_price, 2)
return instance
class ShippingInfoFactory(DataclassFactory[ShippingInfo]):
@classmethod
def carrier(cls) -> str:
carriers = ["FedEx", "UPS", "DHL", "USPS"]
return cls.__random__.choice(carriers)
@classmethod
def tracking_number(cls) -> str:
return ''.join(cls.__random__.choices('0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ', k=12))
class OrderFactory(DataclassFactory[Order]):
@classmethod
def order_id(cls) -> str:
return f"ORD-{datetime.now().year}-{cls.__random__.randint(100000, 999999)}"
@classmethod
def items(cls) -> List[OrderItem]:
return OrderItemFactory.batch(cls.__random__.randint(1, 5))
@classmethod
def build(cls, **kwargs):
instance = super().build(**kwargs)
if instance.total_amount is None:
instance.total_amount = round(sum(item.total_price for item in instance.items), 2)
if instance.shipping_info is None and instance.status in [OrderStatus.SHIPPED, OrderStatus.DELIVERED]:
instance.shipping_info = ShippingInfoFactory.build()
return instance
orders = OrderFactory.batch(2)
print("Generated Orders:")
for order in orders:
print(f"\n Order {order.order_id}")
print(f" Customer: {order.customer_name} ({order.customer_email})")
print(f" Status: {order.status.value}")
print(f" Items ({len(order.items)}):")
for item in order.items:
print(f" - {item.quantity}x {item.product_name} @ ${item.unit_price:.2f} = ${item.total_price:.2f}")
print(f" Total: ${order.total_amount:.2f}")
if order.shipping_info:
print(f" Shipping: {order.shipping_info.carrier} - {order.shipping_info.tracking_number}")
print("\n")We build more complex domain logic by introducing calculated and dependent fields within factories. We show how we can derive values such as final prices, totals, and shipping details after object creation. This allows us to model realistic business rules directly inside our test data generators.
print("=" * 80)
print("SECTION 7: Attrs Integration")
print("=" * 80)
import attrs
from polyfactory.factories.attrs_factory import AttrsFactory
@attrs.define
class BlogPost:
title: str
author: str
content: str
views: int = 0
likes: int = 0
published: bool = False
published_at: Optional[datetime] = None
tags: List[str] = attrs.field(factory=list)
class BlogPostFactory(AttrsFactory[BlogPost]):
@classmethod
def title(cls) -> str:
templates = [
"10 Tips for {}",
"Understanding {}",
"The Complete Guide to {}",
"Why {} Matters",
"Getting Started with {}"
]
topics = ["Python", "Data Science", "Machine Learning", "Web Development", "DevOps"]
template = cls.__random__.choice(templates)
topic = cls.__random__.choice(topics)
return template.format(topic)
@classmethod
def content(cls) -> str:
return " ".join(Faker().sentences(nb=cls.__random__.randint(3, 8)))
@classmethod
def views(cls) -> int:
return cls.__random__.randint(0, 10000)
@classmethod
def likes(cls) -> int:
return cls.__random__.randint(0, 1000)
@classmethod
def tags(cls) -> List[str]:
all_tags = ["python", "tutorial", "beginner", "advanced", "guide",
"tips", "best-practices", "2024"]
return cls.__random__.sample(all_tags, k=cls.__random__.randint(2, 5))
posts = BlogPostFactory.batch(3)
print("Generated Blog Posts:")
for post in posts:
print(f"\n '{post.title}'")
print(f" Author: {post.author}")
print(f" Views: {post.views:,} | Likes: {post.likes:,}")
print(f" Published: {post.published}")
print(f" Tags: {', '.join(post.tags)}")
print(f" Preview: {post.content[:100]}...")
print("\n")
print("=" * 80)
print("SECTION 8: Building with Specific Overrides")
print("=" * 80)
custom_person = PersonFactory.build(
name="Alice Johnson",
age=30,
email="[email protected]"
)
print(f"Custom Person:")
print(f" Name: {custom_person.name}")
print(f" Age: {custom_person.age}")
print(f" Email: {custom_person.email}")
print(f" ID (auto-generated): {custom_person.id}")
print()
vip_customers = PersonFactory.batch(
3,
bio="VIP Customer"
)
print("VIP Customers:")
for customer in vip_customers:
print(f" {customer.name}: {customer.bio}")
print("\n")We extend Polyfactory usage to validated Pydantic models and attrs-based classes. We demonstrate how we can respect field constraints, validators, and default behaviors while still generating valid data at scale. It ensures our mock data remains compatible with real application schemas.
print("=" * 80)
print("SECTION 9: Field-Level Control with Use and Ignore")
print("=" * 80)
from polyfactory.fields import Use, Ignore
@dataclass
class Configuration:
app_name: str
version: str
debug: bool
created_at: datetime
api_key: str
secret_key: str
class ConfigFactory(DataclassFactory[Configuration]):
app_name = Use(lambda: "MyAwesomeApp")
version = Use(lambda: "1.0.0")
debug = Use(lambda: False)
@classmethod
def api_key(cls) -> str:
return f"api_key_{''.join(cls.__random__.choices('0123456789abcdef', k=32))}"
@classmethod
def secret_key(cls) -> str:
return f"secret_{''.join(cls.__random__.choices('0123456789abcdef', k=64))}"
configs = ConfigFactory.batch(2)
print("Generated Configurations:")
for config in configs:
print(f" App: {config.app_name} v{config.version}")
print(f" Debug: {config.debug}")
print(f" API Key: {config.api_key[:20]}...")
print(f" Created: {config.created_at}")
print()
print()
print("=" * 80)
print("SECTION 10: Model Coverage Testing")
print("=" * 80)
from pydantic import BaseModel, ConfigDict
from typing import Union
class PaymentMethod(BaseModel):
model_config = ConfigDict(use_enum_values=True)
type: str
card_number: Optional[str] = None
bank_name: Optional[str] = None
verified: bool = False
class PaymentMethodFactory(ModelFactory[PaymentMethod]):
__model__ = PaymentMethod
payment_methods = [
PaymentMethodFactory.build(type="card", card_number="4111111111111111"),
PaymentMethodFactory.build(type="bank", bank_name="Chase Bank"),
PaymentMethodFactory.build(verified=True),
]
print("Payment Method Coverage:")
for i, pm in enumerate(payment_methods, 1):
print(f" {i}. Type: {pm.type}")
if pm.card_number:
print(f" Card: {pm.card_number}")
if pm.bank_name:
print(f" Bank: {pm.bank_name}")
print(f" Verified: {pm.verified}")
print("\n")
print("=" * 80)
print("TUTORIAL SUMMARY")
print("=" * 80)
print("""
This tutorial covered:
1. ✓ Basic Dataclass Factories - Simple mock data generation
2. ✓ Custom Field Generators - Controlling individual field values
3. ✓ Field Constraints - Using PostGenerated for calculated fields
4. ✓ Pydantic Integration - Working with validated models
5. ✓ Complex Nested Structures - Building related objects
6. ✓ Attrs Support - Alternative to dataclasses
7. ✓ Build Overrides - Customizing specific instances
8. ✓ Use and Ignore - Explicit field control
9. ✓ Coverage Testing - Ensuring comprehensive test data
Key Takeaways:
- Polyfactory automatically generates mock data from type hints
- Customize generation with classmethods and decorators
- Supports multiple libraries: dataclasses, Pydantic, attrs, msgspec
- Use PostGenerated for calculated/dependent fields
- Override specific values while keeping others random
- Perfect for testing, development, and prototyping
For more information:
- Documentation: https://polyfactory.litestar.dev/
- GitHub: https://github.com/litestar-org/polyfactory
""")
print("=" * 80)We cover advanced usage patterns such as explicit overrides, constant field values, and coverage testing scenarios. We show how we can intentionally construct edge cases and variant instances for robust testing. This final step ties everything together by demonstrating how Polyfactory supports comprehensive and production-grade test data strategies.
In conclusion, we demonstrated how Polyfactory enables us to create comprehensive, flexible test data with minimal boilerplate while still retaining fine-grained control over every field. We showed how to handle simple entities, complex nested structures, and Pydantic model validation, as well as explicit field overrides, within a single, consistent factory-based approach. Overall, we found that Polyfactory enables us to move faster and test more confidently, as it reliably generates realistic datasets that closely mirror production-like scenarios without sacrificing clarity or maintainability.
Check out the FULL CODES here. Also, feel free to follow us on Twitter and don’t forget to join our 100k+ ML SubReddit and Subscribe to our Newsletter. Wait! are you on telegram? now you can join us on telegram as well.
