Fakeverse

Fakeverse generates fake data themed by works of fiction. Think Faker, but the people, addresses and organizations come from a fictional world, and they are consistent with each other: a hobbit lives in a town of the Shire, the town is in the right region, and the email is built from the name.

For instance, lotr.one("person", people="hobbit", seed=7) gives:

{
  "first_name": "Gilly",
  "last_name": "Took",
  "full_name": "Gilly Took",
  "gender": "feminine",
  "people": "Hobbit",
  "address": {
    "street_address": "7 Smithy Street",
    "postal_code": "SH-594",
    "locality": "Oatbarton",
    "subdivision": "The Shire",
    "area": "Eriador",
    "formatted": "7 Smithy Street\nOatbarton SH-594\nThe Shire, Eriador"
  },
  "email": "gilly.took@post.example",
  "username": "gilly972",
  "phone": "+35 872 9950"
}

• Coherent: generated values respect the relations between peoples, places and names.
• Multilingual: every universe is translated, following a reference translation, and fallbacks to another language are reported.
• Reproducible: the same seed and the same data version always give the same result.
• Easy to contribute: one YAML file per universe, validated automatically.
• Everywhere: Python package, Faker provider, command line and HTTP API.

Universes

New universes are welcome: see Contributing.

Installation

pip install fakeverse            # package and command line
pip install "fakeverse[faker]"   # with the Faker provider
pip install "fakeverse[api]"     # with the HTTP API

Fakeverse needs Python 3.12 or later.

Python package

from fakeverse import Fakeverse

fv = Fakeverse()
lotr = fv.universe("lotr")

result = lotr.generate("first_name", count=3, seed=42)
result.items  # ['Andwise', 'Orodreth', 'Dáin']
result.meta.seed  # 42

lotr.one("full_name", seed=1, gender="feminine")  # 'Dís'
lotr.generate("person", count=5, people="hobbit")  # five hobbits, no duplicates
lotr.generate("weapon", count=2, seed=3).items  # a type specific to the universe
# [{'name': 'Glamdring', 'kind': 'Sword'}, {'name': 'Aeglos', 'kind': 'Spear'}]

fv.universe("lotr", locale="fr").generate("full_name", count=3, seed=42).items
# ['Flói', 'Hugo Goold', 'Fréaláf']

Templates combine several types in one row. Leaves that reference the same instance describe the same entity, and colocate puts instances in the same locality:

lotr.template(
    {
        "name": "person.full_name",
        "employer": "organization.name",
        "town": "person.address.locality",
    },
    count=2,
    seed=7,
    colocate=[["person", "organization"]],
).items
# [{'name': 'Théodred', 'employer': 'The Wild Boar', 'town': 'Aldburg'},
#  {'name': 'Náli', 'employer': 'The Old Mill', 'town': 'Erebor'}]

Types: the composites person, address and organization, their projections (first_name, last_name, full_name, email, username, phone, street_address, postal_code, locality, subdivision, area, organization_name), and the types specific to each universe. Options include unique (on by default, as far as the pool allows) and explain, which tells for each value whether it comes from the works (canon) or was made up (generated).

How generation works describes types, seeds, locales, uniqueness and templates in detail.

Faker provider

from faker import Faker
from fakeverse.faker import FakeverseProvider

fake = Faker("fr_FR")
fake.add_provider(FakeverseProvider)

fake.fakeverse("lotr").person()
fake.fakeverse("lotr").first_name(gender="feminine")
fake.fakeverse("lotr").generate("weapon")
fake.fakeverse("lotr").template({"name": "person.full_name"})
fake.fakeverse("lotr").unique.first_name()  # never twice the same value

Faker.seed() makes sequences reproducible. The locale of Faker is used when the universe supports its language, and the default locale of the universe otherwise; fake.fakeverse("lotr", strict_locale=True) raises an error instead.

Command line

fakeverse generate lotr person -n 3 --seed 42 --locale fr
fakeverse generate lotr full_name -n 100 --format csv > names.csv
echo '{"name": "person.full_name", "employer": "organization.name"}' \
  | fakeverse template lotr - -n 10 --format ndjson --colocate person,organization
fakeverse info

fakeverse --help lists every command. Contributors also use fakeverse validate, fakeverse coverage and fakeverse check-coherence.

HTTP API

pip install "fakeverse[api]"
uvicorn fakeverse.api.app:app --no-access-log

curl "http://localhost:8000/v1/universes/lotr/generate/person?count=3&seed=42&locale=fr"
curl "http://localhost:8000/v1/universes/starwars/generate/starship?count=10&format=csv"
curl -X POST "http://localhost:8000/v1/universes/lotr/generate" \
  -H "Content-Type: application/json" \
  -d '{"template": {"name": "person.full_name", "town": "person.address.locality"}, "count": 10}'

The API supports JSON, NDJSON and CSV, reports errors in the RFC 9457 format, applies rate limiting, and sets HTTP cache headers on requests with a seed. The interactive documentation is served at /docs. See the API reference and the deployment guide, which covers the Docker image.

Stability

Fakeverse is young: until 1.0.0, a minor release (0.2.0, 0.3.0...) may change the API, the universe file format or the generated output, and the changelog always says so. A patch release (0.1.1) never changes any output. Whatever the version, a given version of the package, or a given data_version of the API, always gives the same output for the same request and seed. Pin the version when you rely on generated values, in tests or fixtures.

Documentation

• How generation works: types, seeds, locales, uniqueness, templates.
• API reference and API problems.
• Deployment guide.
• Universe guide, to write or extend a universe, and architecture, to change the code.
• Changelog and security policy.

Contributing

New universes, names, translations and fixes are welcome. Read the contributing guide and the universe guide.

License

• Code: MIT.
• Universe files (universes/): CC0-1.0.

These licenses cover only the contributions of the Fakeverse project (data structure, patterns, generated vocabulary and original content), not the names and trademarks of the original works. See NOTICE. Rights holders can follow the takedown procedure.

Disclaimer

Fakeverse is an independent, non-commercial open source project. It is not affiliated with, endorsed by, or sponsored by any rights holder of the works it draws inspiration from. All names, characters, places and trademarks belong to their respective owners. Universe files contain only short names and labels; no text, quotes or images from the original works.

Code of conduct

This project follows the Contributor Covenant 2.1.