Deterministic fixtures, pytest modules, datasets, and JSON from Pydantic v2 models and stdlib dataclasses/TypedDicts, all inside a sandboxed CLI with Pluggy providers.
Generate deterministic structured data, pytest fixtures, and JSON quickly with a safe, task-focused CLI built for modern testing workflows. Fixturegen still speaks Pydantic natively and now understands dataclasses and TypedDicts without extra adapters. Official support targets Python 3.10–3.14 and Pydantic v2.
📘 Read the full docs and examples at pydantic-fixturegen.kitgrid.dev.
pip install pydantic-fixturegen
# Extras: orjson, regex, hypothesis, watch
pip install 'pydantic-fixturegen[all]'Other flows → docs/install.md
Copy/paste the snippet below into a shell. It drops a tiny User model into models.py, lists it, generates JSON samples, and writes pytest fixtures—all with deterministic seeds.
# 1) Create a minimal model file
cat > models.py <<'PY'
from pydantic import BaseModel, EmailStr
class User(BaseModel):
id: int
email: EmailStr
tags: list[str]
PY
# 2) Discover models
pfg list models.py
# 3) Emit JSON samples (2 records) to ./out/User.json
pfg gen json models.py \
--include models.User \
--n 2 --indent 2 \
--seed 7 --freeze-seeds \
--out out/{model}.json
# 4) Emit pytest fixtures with 3 deterministic cases
pfg gen fixtures models.py \
--include models.User \
--cases 3 \
--seed 7 --freeze-seeds \
--out tests/fixtures/{model}_fixtures.pyExpected results:
pfg listprintsmodels.Userso you know discovery works.out/User.jsoncontains two pretty-printed user records seeded with--seed 7.tests/fixtures/User_fixtures.pyexposes three pytest fixtures (user_case_1, etc.) you can import immediately.
Once those commands work, swap in your actual module path and tweak shared flags like --include, --seed, --watch, or --cases as needed.
- Command reference: https://pydantic-fixturegen.kitgrid.dev/commands/ — step-by-step explanations for every
pfgsubcommand (JSON, dataset, fixtures, schema, diff, lock/verify, etc.) with copy-paste scripts and sample output. - Concept guides: https://pydantic-fixturegen.kitgrid.dev/concepts/ — seeds, presets, overrides, relation wiring, sandboxing, and provider heuristics in one place.
- Recipes & troubleshooting: https://pydantic-fixturegen.kitgrid.dev/examples/ — runnable demos for SQLModel/Beanie seeding, snapshot verification, large dataset export, and Polyfactory delegation.
If you ever get stuck, run pfg <command> --help to see the available flags plus the docs permalink for that command.
- You keep tests reproducible with cascaded seeds across
random, Faker, and optional NumPy. - You run untrusted models inside a safe-import sandbox with network, filesystem, and memory guards.
- You drive JSON, pytest fixtures, schemas, and explanations from the CLI or Python helpers.
- You dial collection sizes up or down (globally or per field) with deterministic min/max/distribution knobs when you need denser samples.
- You extend generation with Pluggy providers and preset bundles without forking core code.
You also stay observant while you work: every command can emit structured logs, diff artifacts against disk, and surface sandbox warnings so you catch regressions before they land.
- Create a small model file (Pydantic v2,
@dataclass, orTypedDict). - List models:
pfg list ./models.py - Generate JSON:
pfg gen json ./models.py --include models.User --n 2 --indent 2 --out ./out/User - Generate fixtures:
pfg gen fixtures ./models.py --out tests/fixtures/test_user.py --cases 3Full steps → docs/quickstart.md
JSON, fixtures, and schema commands all share flags like --include, --exclude, --seed, --preset, and --watch, so once you learn one flow you can handle the rest without re-reading the help pages.
# examples/models.py
from dataclasses import dataclass
from typing import TypedDict
from pydantic import BaseModel, EmailStr
class AuditTrail(TypedDict):
actor: str
event: str
ip: str
@dataclass
class ShippingWindow:
earliest: str
latest: str
class Order(BaseModel):
id: int
email: EmailStr
items: list[str]
shipping: ShippingWindow
audit: AuditTrail
class Address(BaseModel):
street: str
city: str# JSON + datasets
pfg gen json examples/models.py --include examples.Order --n 5 --jsonl \
--seed 11 --freeze-seeds \
--out artifacts/{model}.jsonl
pfg gen dataset examples/models.py --include examples.Order --format parquet --n 10000 \
--seed 11 --freeze-seeds \
--out warehouse/{model}.parquet
# Pytest fixtures + persistence
pfg gen fixtures examples/models.py --include examples.Order --cases 3 \
--seed 11 --freeze-seeds \
--out tests/fixtures/{model}_fixtures.py
pfg persist examples/models.py --handler http-post --handler-config '{"url": "https://api.example.com/orders"}' \
--include examples.Order --n 25 --seed 11 --freeze-seedsPrefer Python APIs?
from pathlib import Path
from pydantic_fixturegen.api import generate_json
from pydantic_fixturegen.core.path_template import OutputTemplate
result = generate_json(
target=Path("examples/models.py"),
output_template=OutputTemplate("artifacts/{model}.json"),
count=10,
jsonl=True,
include=["examples.Order"],
field_hints="defaults",
collection_min_items=1,
collection_max_items=3,
)
for path in result.paths:
print("wrote", path)See docs/examples.md for more end-to-end snippets that cover datasets, fixtures, persistence handlers, and Python helpers.
- ✅ Pydantic BaseModel / RootModel (v2) — full support with validators, constraints, provider defaults, and Polyfactory delegation.
- ✅ Stdlib
@dataclass— fixturegen inspects field metadata/annotations, respects defaults/examples, and serializes back to dataclass instances. - ✅
typing.TypedDict(total or partial) — treated as schema-driven dicts, including nested dataclasses or other TypedDicts. - 🚧 attrs/msgspec — not yet wired into the adapters; vote on issue #53 if you need them next.
The same include/exclude filters, overrides, presets, and field hints apply no matter which model family you point the CLI at.
pfg list <path>
pfg gen json <target> [--n --jsonl --indent --out]
pfg gen fixtures <target> [--style --scope --cases --out]
pfg gen schema <target> --out <file>
pfg doctor <target>pfg listdiscovers models with AST or safe-import; add--astwhen you must avoid imports.pfg gen jsonemits JSON or JSONL; scale with--n,--jsonl,--shard-size, and--freeze-seeds.pfg gen fixtureswrites pytest modules; tune--style,--scope,--cases, and--return-type.pfg gen schemadumps JSON Schema atomically; point--outat a file or directory template.pfg doctoraudits coverage and sandbox warnings; fail builds with--fail-on-gaps.
All commands → docs/cli.md
| key | type | default | purpose |
|---|---|---|---|
| seed | int \ str \ null | null | Global seed |
| locale | str | en_US | Faker locale |
| union_policy | enum | first | Union branch |
| enum_policy | enum | first | Enum choice |
| json.indent | int | 2 | Pretty JSON |
| json.orjson | bool | false | Fast JSON |
| emitters.pytest.style | enum | functions | Fixture style |
| emitters.pytest.scope | enum | function | Fixture scope |
[tool.pydantic_fixturegen]
seed = 42
[tool.pydantic_fixturegen.json]
indent = 2Need denser lists/sets? Add a [tool.pydantic_fixturegen.collections] block (or pass --collection-* flags) to clamp global min/max items and choose uniform, min-heavy, or max-heavy distributions before per-field constraints kick in.
Full matrix and precedence → docs/configuration.md
- Freeze seeds for CI determinism → docs/seeds.md
- Use watch mode → docs/quickstart.md#watch-mode
- Templated output paths → docs/output-paths.md
- Provider customization → docs/providers.md
- Capture explain trees or JSON diagnostics for review → docs/explain.md
Index · Quickstart · Examples · Cookbook · Configuration · CLI · Concepts · Features · Security · Architecture · Troubleshooting · Alternatives
Open issues for bugs or ideas, start Discussions for design questions, and follow the security policy when you disclose sandbox bypasses.
MIT. See LICENSE.