Metadata-Version: 2.4
Name: fakeforge
Version: 0.2.1
Summary: Offline, deterministic fake-data generation for Python.
Author: Navaidh Innovations
License-Expression: LicenseRef-FakeForge-Proprietary
Project-URL: Homepage, https://github.com/NavaidhInnovations/FakeForge
Project-URL: Repository, https://github.com/NavaidhInnovations/FakeForge
Keywords: fake-data,mock-data,test-data,faker,data-generator,seeded-data,synthetic-data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

﻿# FakeForge


**Offline, deterministic fake-data generation for Python.**


FakeForge is a lightweight fake-data generation library for development, testing, prototyping, demonstrations, fixtures, and reproducible synthetic datasets.


It runs locally and does not require a cloud service, API key, or network connection.


## Features


- Deterministic seeded data generation
- Country-aware fake data
- Person names
- Job titles
- Email addresses
- Usernames
- Phone numbers
- Addresses
- Companies
- Internet data
- UUID generation
- ULID generation
- NanoID generation
- Dates
- Date/time values
- Unix timestamps
- Random integers
- Random floating-point values
- Booleans
- Locale-aware generation
- Reproducible records
- Fully offline operation


## Requirements


- Python 3.12 or newer


## Installation


Install FakeForge with pip:


```bash
pip install fakeforge
Basic Usage
from fakeforge import FakeForgeClient, FakeForgeOptions


fake = FakeForgeClient.create(
    FakeForgeOptions(
        seed=12345,
    )
)


record = fake.record()


print(record.name.full_name())
print(record.internet.email())
print(record.phone.number())
print(record.address.city())
print(record.company.name())
Configuration

FakeForge instances are configured using FakeForgeOptions.

from fakeforge import FakeForgeClient, FakeForgeOptions


fake = FakeForgeClient.create(
    FakeForgeOptions(
        country="IN",
        seed=12345,
    )
)

Available options:

OptionDefaultDescription
country"WORLD"Country/locale used for generated data
seed0Seed used by the deterministic random generator
Deterministic Generation

FakeForge uses a seeded pseudo-random generator.

Providing the same seed and making the same sequence of generator calls produces the same results.

from fakeforge import FakeForgeClient, FakeForgeOptions


first = FakeForgeClient.create(
    FakeForgeOptions(
        country="IN",
        seed=12345,
    )
)


second = FakeForgeClient.create(
    FakeForgeOptions(
        country="IN",
        seed=12345,
    )
)


first_record = first.record()
second_record = second.record()


print(first_record.name.full_name())
print(second_record.name.full_name())

For deterministic behavior, keep the following consistent:

Seed
Country/locale configuration
Generator call order
Generator arguments

Deterministic generation is useful for:

Unit tests
Integration tests
Test fixtures
CI/CD pipelines
Database seed data
Reproducible bug reports
Development
Prototyping
Demonstrations
Synthetic datasets
Locale / Country Generation

FakeForge supports locale-aware fake-data generation.

from fakeforge import FakeForgeClient, FakeForgeOptions


fake = FakeForgeClient.create(
    FakeForgeOptions(
        country="IN",
        seed=12345,
    )
)


record = fake.record()


print(record.resolved_country)
print(record.name.full_name())
print(record.phone.number())
print(record.address.city())
print(record.address.state())
print(record.address.postal_code())
resolved_country

record.resolved_country returns the concrete country code associated with the record.

For an explicit country:

record.resolved_country == "IN"

For WORLD, FakeForge resolves a concrete implemented locale.

fake = FakeForgeClient.create(
    FakeForgeOptions(
        country="WORLD",
        seed=12345,
    )
)


record = fake.record()


print(record.resolved_country)

WORLD is therefore not returned as the concrete country of the generated record.

Implemented Locales

FakeForge currently provides locale datasets for:

CodeCountry
USUnited States
INIndia
GBUnited Kingdom
CACanada
AUAustralia
DEGermany
FRFrance
JPJapan
SGSingapore
AEUnited Arab Emirates

WORLD can resolve to one of the implemented locales.

Person

Generate locale-aware person data:

record.name.first_name()
record.name.last_name()
record.name.full_name()
record.name.job_title()
Internet

Generate internet-related data:

record.internet.email()
record.internet.username()
record.internet.url()
record.internet.ipv4()
record.internet.mac_address()
Phone

Generate a locale-aware phone number:

record.phone.number()
Address

Generate locale-aware address data:

record.address.street()
record.address.city()
record.address.state()
record.address.postal_code()
record.address.country()
record.address.full_address()
Company

Generate a company name:

record.company.name()
Identifiers

FakeForge provides deterministic identifiers:

record.string.uuid()
record.string.ulid()
record.string.nano_id()
NanoID Size

The default NanoID size is 21 characters.

record.string.nano_id()

A custom size can be provided:

record.string.nano_id(32)
Dates

Generate deterministic date and timestamp values:

record.date.date()
record.date.date_time()
record.date.unix_timestamp()
Numbers

Generate deterministic numbers:

record.number.integer(1, 100)
record.number.float(0, 100)
Boolean

Generate a deterministic boolean:

record.boolean()
API Overview

A typical FakeForge workflow is:

FakeForgeClient.create()
        |
        v
FakeForgeInstance
        |
        v
    fake.record()
        |
        +-- name
        +-- internet
        +-- phone
        +-- address
        +-- company
        +-- number
        +-- string
        +-- date
        +-- boolean

Example:

from fakeforge import FakeForgeClient, FakeForgeOptions


fake = FakeForgeClient.create(
    FakeForgeOptions(
        country="IN",
        seed=12345,
    )
)


record = fake.record()


user = {
    "name": record.name.full_name(),
    "email": record.internet.email(),
    "phone": record.phone.number(),
    "city": record.address.city(),
    "state": record.address.state(),
    "company": record.company.name(),
}
Public API

The package root currently exposes:

from fakeforge import (
    FakeForgeClient,
    FakeForgeInstance,
    FakeForgeOptions,
    FakeForgeRecord,
)
FakeForgeClient

Entry point for creating configured FakeForge instances.

fake = FakeForgeClient.create(
    FakeForgeOptions(
        country="IN",
        seed=12345,
    )
)
FakeForgeOptions

Configuration object:

FakeForgeOptions(
    country="WORLD",
    seed=0,
)
FakeForgeInstance

A configured FakeForge data-generation engine.

fake.record()

Each call creates a record using the instance's deterministic random generator and resolved locale.

FakeForgeRecord

Provides access to the individual generator groups:

record.name
record.internet
record.phone
record.address
record.company
record.number
record.string
record.date
record.boolean
Offline Operation

FakeForge performs fake-data generation locally.

Generated values do not require a remote API.

No cloud service or API key is required.

This makes FakeForge suitable for:

Unit tests
Integration tests
CI/CD pipelines
Local development
Test fixtures
Database seeding
API testing
Prototyping
Demonstrations
Synthetic datasets
Reproducible test data
Synthetic Data

FakeForge generates synthetic data for development and testing purposes.

Generated values should not be assumed to represent real people, organizations, addresses, or other factual records.

Do not use generated data as a substitute for verified real-world information.

Deterministic Random Generation

FakeForge's random generator is seeded and deterministic.

The same seed produces the same random sequence when the same sequence of operations is performed.

For example:

from fakeforge import FakeForgeClient, FakeForgeOptions


first = FakeForgeClient.create(
    FakeForgeOptions(seed=12345)
)


second = FakeForgeClient.create(
    FakeForgeOptions(seed=12345)
)


a = first.record()
b = second.record()


print(a.string.uuid())
print(b.string.uuid())

The generated values are reproducible when the configuration and generator call sequence are the same.

Package Information
PropertyValue
Packagefakeforge
Version0.2.0
LanguagePython
Minimum Python3.12
Data generationLocal
Network requiredNo
API key requiredNo
License

FakeForge is distributed under the FakeForge Proprietary Free-Use License.

Commercial applications using FakeForge are permitted under the license.

Standalone redistribution, repackaging, modification, or distribution of FakeForge itself is restricted by the license.

See LICENSE for the complete license terms.

Repository

https://github.com/NavaidhInnovations/FakeForge
