Skip to main content

FakerForge

FakerForge is a Python framework for synthetic data, built on top of Faker. It does not fork Faker. Custom providers are normal Faker providers, and every other Faker method stays available.

Requires Python 3.10 or newer.

Install

pip install fakerforge

NumPy and pandas are optional:

pip install "fakerforge[numpy]"
pip install "fakerforge[pandas]"

Quick start

from fakerforge import FakerForge

fake = FakerForge(seed=42)

fake.name()
fake.email()
fake.address()

FakerForge forwards unknown attributes to its faker.Faker instance. seed calls seed_instance, so the seed applies only to that object. Built-in providers are registered with Faker's add_provider and read the same random generator.

Finance

FinanceProvider is registered on every FakerForge instance.

from fakerforge import FakerForge

fake = FakerForge(seed=42)

fake.credit_score()          # int, 300 through 850
fake.transaction_amount()    # Decimal quantized to cents, 1.00 through 10000.00
fake.account_number()        # 12-digit string

fake.credit_score(min_score=700, max_score=750)
fake.transaction_amount(min_amount=10, max_amount=25)
fake.account_number(length=8)

The same seed reproduces the same sequence. min_score and max_score are inclusive. Amount bounds are inclusive after rounding to cents.

Distributions

number and categorical sample from a DistributionEngine created with the same seed as the FakerForge instance. That stream is separate from Faker provider calls, so a later schema generator can replay distribution draws without depending on how many names or emails were produced. seed_instance reseeds both streams.

NumPy is used when it is installed (pip install fakerforge[numpy]). Without NumPy, sampling uses the standard library. Each backend is deterministic for a given seed. They do not emit the same series.

from fakerforge import FakerForge

fake = FakerForge(seed=42)

fake.number(distribution="uniform", min=0, max=1)
fake.number(distribution="normal", mean=50, std=10, min=18, max=80)
fake.number(distribution="lognormal", mean=0, std=0.25, min=0.5, max=3)
fake.categorical(values=["A", "B", "C"])
fake.categorical(values=["A", "B", "C"], weights=[0.6, 0.3, 0.1])

min and max on normal and log-normal draws are inclusive. A sample outside that interval is discarded and another sample is drawn. Values are not clipped to the boundary. If 1000 draws in a row miss the interval, number raises DistributionError.

Log-normal mean and std describe the underlying normal distribution, matching NumPy's Generator.lognormal. Samples are greater than zero. Uniform draws use the half-open interval [min, max), except when min == max, which returns that value. Weights do not need to sum to 1.

Schemas

generate validates a declarative schema, then builds rows. The return value is a dataset result. rows is the list of records. frame is a pandas DataFrame when pandas is installed (pip install fakerforge[pandas]). validate() checks the rows against the schema.

from fakerforge import FakerForge

fake = FakerForge(seed=42)

schema = {
    "customer_id": {"type": "uuid", "unique": True},
    "name": {"provider": "person.name"},
    "age": {"type": "integer", "min": 18, "max": 80},
    "email": {"provider": "internet.email", "unique": True},
}

result = fake.generate(schema=schema, rows=1000)
report = result.validate()

Primitive types are string, integer, float, boolean, uuid, and date. Provider references use Faker's provider.method form, such as person.name. Integer bounds are inclusive. Float bounds use the half-open interval [min, max). Omitted numeric bounds default to 0..100 for integers and 0.0..1.0 for floats.

nullable fields are None with probability null_probability, which defaults to 0.1. Unique columns do not repeat non-null values. Nulls may repeat. If a unique value cannot be found, generation raises GenerationError instead of inserting a duplicate. Dates are drawn from 1990-01-01 through 2030-12-31 so a seed stays stable.

Invalid schemas raise SchemaError before any row is produced. errors lists every problem found in that pass.

Derived and dependent fields

derived_from computes a field from an earlier one. A date source produces completed years as of 2030-12-31, so the result does not change with the calendar day. depends_on generates the named fields first. A date that depends on a date is drawn on or after that date. Cycles are rejected.

schema = {
    "date_of_birth": {"provider": "date.date_of_birth"},
    "age": {"derived_from": "date_of_birth"},
    "start_date": {"type": "date"},
    "end_date": {"type": "date", "depends_on": "start_date"},
}

Foreign keys

A relational schema maps each table to fields and rows. references copies a value from a unique parent column. Child rows are generated after the parent, so a foreign key is never invented. A unique foreign key uses each parent value at most once. Many-to-many relationships are not supported.

schema = {
    "customers": {
        "rows": 10,
        "fields": {
            "customer_id": {"type": "uuid", "unique": True},
            "name": {"provider": "person.name"},
        },
    },
    "orders": {
        "rows": 40,
        "fields": {
            "order_id": {"type": "uuid", "unique": True},
            "customer_id": {"references": "customers.customer_id"},
        },
    },
}

tables = fake.generate(schema=schema)
report = tables.validate()

Validation

validate() checks the generated rows against the schema that produced them. The report has a passed or failed status, the row count, the violation count, and violations grouped by field. Each violation has a human-readable message. A failed report is returned; it is not raised.

Built-in checks cover type, min/max, nullable, uniqueness, known provider output, foreign keys, and row count. Subclass DatasetCheck and pass instances as extra to add further data-quality checks:

from fakerforge.validation import DatasetCheck, ValidationContext, Violation

class RejectPlaceholder(DatasetCheck):
    name = "placeholder"

    def run(self, context: ValidationContext) -> list[Violation]:
        return []

report = result.validate(extra=(RejectPlaceholder(),))

Custom providers

Subclass faker.providers.BaseProvider and pass the class to FakerForge or add_provider. ForgeProvider is a thin subclass of that base, re-exported for convenience. Provider methods use Faker helpers such as random_int and numerify, which read the instance generator.

from faker.providers import BaseProvider

from fakerforge import FakerForge
from fakerforge.generator import Generator
from fakerforge.schema import Field, Schema

class StatusProvider(BaseProvider):
    def status_code(self) -> str:
        return self.random_element(("new", "open", "closed"))

fake = FakerForge(seed=42, providers=[StatusProvider])
fake.status_code()

schema = Schema(
    fields=(
        Field("name", "name"),
        Field("email", "email"),
        Field("status", "status_code"),
    )
)
rows = Generator(fake).generate(schema, count=3)

The source distribution includes examples/quickstart.py and docs/architecture.md.

Project plan and batches

load reads a project document. plan checks providers and dependencies and reports generation order, row counts, and tables that can be generated together. It does not draw rows. estimated_bytes_per_row is a placeholder of 64 bytes per column, not a measured size.

iter_batches yields chunks. Concatenating them matches generate for the same seed and schema. generate still returns the full in-memory dataset. Execution stays single-threaded. The dependency graph names parallel groups for later releases.

JSON works with the base install. YAML needs pip install "fakerforge[yaml]". Documents are parsed as data and are not executed. Distribution draws stay reproducible for a given backend. NumPy and the standard library do not emit the same series, so reproducibility includes whether NumPy is installed.

from fakerforge import FakerForge

forge = FakerForge(seed=42)
project = forge.load("examples/projects/minimal/project.json")
plan = forge.plan(project)

for batch in forge.iter_batches(project.tables, batch_size=2):
    print(batch.table, len(batch))

ARCHITECTURE_AUDIT.md describes the current architecture and the roadmap.

This release

Piece What 0.1 provides
Providers Built-in FinanceProvider, plus add_provider for custom BaseProvider subclasses
Constraints Constraint base and Validator
Distributions Uniform, normal, log-normal, and weighted categorical sampling
Schema Declarative datasets via FakerForge.generate
Generation Seeded rows, with a DataFrame when pandas is installed
Validation Dataset checks on generated rows, plus per-field Validator
Reproducibility Instance seeding

Later releases can add more domain providers and many-to-many relationships.

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check src tests examples
ruff format --check src tests examples
mypy

Metadata

Release files for fakerforge 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fakerforge 0.2.0
File Size Uploaded Provenance Actions
fakerforge-0.2.0.tar.gz 53.5 kB With provenance Details for fakerforge-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fakerforge 0.2.0
File Interpreter ABI Platform Actions
fakerforge-0.2.0-py3-none-any.whl Python 3 none any Details for fakerforge-0.2.0-py3-none-any.whl

Total release size: 102.6 kB

Release files / fakerforge-0.2.0.tar.gz

Download URL fakerforge-0.2.0.tar.gz
Size 53.5 kB
Tags Source
SHA-256 checksum
How to use checksums
ee4046bc1c298240d69f8d294a01c9ab27a9b94ed3eb4c99d2bcb6a647490a74
BLAKE2b-256 checksum
How to use checksums
4d450ec8c21d24590ba976d4dfd0321337631593dcfc53ab5e9a823d0f469b56
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.

Transparency log

Release files / fakerforge-0.2.0-py3-none-any.whl

Download URL fakerforge-0.2.0-py3-none-any.whl
Size 49.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b3d3e4bf31df9a1aa00c57d1f9ddd8d354fac9678a8cc2a376cf5f9a4a63ad50
BLAKE2b-256 checksum
How to use checksums
ed79d7f5739deced5c476cb7dec461595bf1f695370e4b53797c9b9c00a811bf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.

Transparency log

Security for fakerforge 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for fakerforge-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page