Faker Literature Provider
A custom Faker provider for generating realistic literature data: writers, books, genres, publishers and more.
Every record comes from a real catalogue of well-known works, so a generated book is always coherent: its title, writer, year, genres and publisher belong together. The provider supports two locales (fr_FR, en_US), and you can enlarge the catalogue by importing works from Wikidata or your own datasets.
📚 Bundled Catalogue
| Count | |
|---|---|
| Authors | 164 |
| Books | 425 |
| Genres | ~200 per locale |
| Nationalities | 22 |
| Years covered | 800 BC → 2024 |
Classics, crime fiction, science fiction, fantasy, horror, poetry, drama, essays and contemporary novels by French, American, British, Italian, Greek, Russian, Latin-American writers, and more.
🌍 Supported Locales
| Locale | Language | Example Writer | Example Title | Example Genre | Example Publisher |
|---|---|---|---|---|---|
en_US |
English (US) | "Dashiell Hammett" | "Brave New World" | "science fiction" | "Penguin Classics" |
fr_FR |
French (France) | "Daniel Pennac" | "Le Meilleur des mondes" | "science-fiction" | "Gallimard" |
Titles, genres, nationalities, publishers and page counts are localized: the same book is "Le Crime de l'Orient-Express" (Le Livre de poche, 256 pages) in fr_FR and "Murder on the Orient Express" (William Collins, Sons, 240 pages) in en_US.
Default locale:
en_US(if no locale is specified).Regional variants fall back on their language:
fr_CA,fr_BE,fr_CH→fr_FR;en_GB,en_AU,en_CA→en_US.Any other locale (e.g.
de_DE) raises aValueError, so unsupported data is never silently mixed into a dataset.
📦 Installation
pip install faker-literature
Or install from the repository:
git clone https://github.com/arribo44/faker-literature.git
cd faker-literature
pip install -e .
Requirements: Python 3.8+, faker>=20.0.0, tinydb>=4.0.0.
🚀 Usage
Basic Setup
from faker import Faker
from faker_literature import LiteratureProvider
# Use default locale (en_US)
fake = Faker()
fake.add_provider(LiteratureProvider)
# Or specify a locale
fake_fr = Faker("fr_FR")
fake_fr.add_provider(LiteratureProvider)
📖 Books
book() returns one coherent record: all its fields describe the same real work.
book = fake.book()
# {
# 'writer': 'Robert E. Howard',
# 'nationality': 'American',
# 'title': 'Skulls in the Stars',
# 'genre': ['horror', 'sword and sorcery'],
# 'year': 1928,
# 'pages': 176,
# 'publisher': 'Weird Tales'
# }
book_fr = fake_fr.book()
# {
# 'writer': 'Robert E. Howard',
# 'nationality': 'américain',
# 'title': 'Les Ombres de Kampala',
# 'genre': ['horreur', 'épée et sorcellerie'],
# 'year': 1928,
# 'pages': 192,
# 'publisher': 'Pocket'
# }
# Alias, convenient in dataset definitions
work = fake.literary_work() # same as fake.book()
| Key | Type | Description |
|---|---|---|
writer |
str |
Author name (co-authors are joined with , ) |
nationality |
str |
Author nationality, localized ("British" / "britannique") |
title |
str |
Title, localized (translated title in fr_FR, English title in en_US) |
genre |
list[str] |
One or more genres, localized |
year |
int |
Year of first publication (negative for BC: -800 for Homer) |
pages |
int or None |
Page count of a typical edition in that locale |
publisher |
str or None |
Publisher of a typical edition in that locale |
Each call returns a new dictionary: you can modify it freely without affecting the catalogue.
✍️ Writers
# Random writer — by default, a writer of the locale's nationality
writer = fake.writer() # "Dashiell Hammett" (en_US -> American writers)
writer = fake_fr.writer() # "Daniel Pennac" (fr_FR -> French writers)
# Writer of a given nationality (spelled in the current locale)
british = fake.writer(nationality="British") # "Arthur C. Clarke"
britannique = fake_fr.writer(nationality="britannique") # "William Shakespeare"
# Writer of a given genre (case-insensitive, in the current locale)
horror = fake.writer(genre="horror") # "Stephen King"
sf = fake_fr.writer(genre="science-fiction") # "Alain Damasio"
# Both filters at once
fake.writer(nationality="American", genre="horror") # "Stephen King", "H. P. Lovecraft"...
# Alias, accepts the same parameters
author = fake.author(nationality="British")
Writers are drawn in proportion to their number of books: prolific authors appear more often.
If no writer matches the filters, a ValueError is raised:
fake.writer(nationality="American", genre="nope")
# ValueError: No writer found for nationality='American', genre='nope'
🏷️ Titles
# Random title
title = fake.title() # "Brave New World" (en_US)
title = fake_fr.title() # "Le Meilleur des mondes" (fr_FR)
# Title of a given genre
fake.title(genre="science fiction") # "Downbelow Station"
fake_fr.title(genre="roman policier") # "Les Dieux de la guerre"
fake.title(genre="nope")
# ValueError: No title found for genre='nope'
🎭 Genres, Nationalities & Publishing Details
genre = fake.genre() # "utopia" (en_US), "poésie" (fr_FR)
nationality = fake.nationality() # "French" (en_US), "français" (fr_FR) — any nationality
year = fake.publication_year() # 1978
pages = fake.pages() # 112
publisher = fake.publisher() # "Penguin Classics" (en_US), "Gallimard" (fr_FR)
Each of these methods is an independent random draw from the catalogue. Use book() when the values must belong together.
🔎 Querying the Catalogue
The provider also exposes query methods that return every matching book (as a list of book()-like dictionaries) instead of a random one:
# All books by an author (name as spelled in the current locale)
fake.books_by_author("Victor Hugo")
# [{'title': 'The Hunchback of Notre-Dame', 'year': 1831, ...},
# {'title': 'The Rays and the Shadows', 'year': 1840, ...},
# {'title': 'Les Misérables', 'year': 1862, ...}, ...]
# All books of a genre (case-insensitive, current locale)
fake.books_by_genre("horror") # 26 books
fake_fr.books_by_genre("roman policier")
# All books published in a year, or within a range (inclusive)
fake.books_by_year(1862) # [{'writer': 'Victor Hugo', 'title': 'Les Misérables', ...}]
fake.books_by_year_range(1940, 1960) # 53 books
fake.books_by_year_range(-500, 0) # Ancient Greek works
Catalogue overview:
fake.all_authors() # ['Agatha Christie', 'Alain Damasio', ...] (164, sorted)
fake.all_genres() # ['absurd novel', 'absurdism', 'adolescence', ...] (sorted, localized)
fake.all_nationalities() # ['Algerian', 'American', 'Ancient Greek', 'Argentine', ...]
fake_fr.all_nationalities() # ['algérien', 'allemand', 'américain', 'argentin', ...]
Use these lists to pick valid values for the nationality and genre filters.
🔁 Reproducible Data
Like every Faker provider, results are deterministic once Faker is seeded:
Faker.seed(42)
first = fake.book()
Faker.seed(42)
assert fake.book() == first
🌐 Multiple Locales at Once
Faker's multi-locale mode does not proxy add_provider(), so add the provider to each locale:
fake = Faker(["fr_FR", "en_US"])
for locale in ("fr_FR", "en_US"):
fake[locale].add_provider(LiteratureProvider)
fake["fr_FR"].title() # "L'Appel de Cthulhu"
fake["en_US"].title() # "The Symposium"
🗂️ Generating a Dataset
import csv
from faker import Faker
from faker_literature import LiteratureProvider
fake = Faker("fr_FR")
fake.add_provider(LiteratureProvider)
Faker.seed(0)
with open("library.csv", "w", newline="", encoding="utf-8") as file:
writer = csv.DictWriter(file, fieldnames=["isbn", "title", "writer", "genre", "year", "pages", "publisher", "copies"])
writer.writeheader()
for _ in range(1000):
book = fake.book()
writer.writerow({
"isbn": fake.isbn13(), # Faker's built-in ISBN provider
"title": book["title"],
"writer": book["writer"],
"genre": " / ".join(book["genre"]),
"year": book["year"],
"pages": book["pages"],
"publisher": book["publisher"],
"copies": fake.random_int(min=1, max=12),
})
🗄️ Enlarging the Catalogue
By default the bundled catalogue is loaded in memory and nothing is written to disk. To generate more varied data, you can store an enlarged catalogue in a persistent database (a TinyDB JSON file).
Importing from Wikidata
Import well-known literary works from Wikidata (CC0 licence) into a database stored in your user cache directory:
python -m faker_literature import-wikidata --limit 500 --min-sitelinks 30
| Option | Default | Description |
|---|---|---|
--limit |
500 |
Maximum number of works to import (capped at 5000) |
--min-sitelinks |
30 |
Only works described by at least this many Wikipedia articles: higher means more famous |
--db PATH |
user cache | Database file (option placed before the command) |
# Import into a specific file
python -m faker_literature --db ./my_catalogue.json import-wikidata --limit 1000 --min-sitelinks 20
Default database location:
| OS | Path |
|---|---|
| Linux / macOS | $XDG_CACHE_HOME/faker-literature/literature_db.json (~/.cache/... by default) |
| Windows | %LOCALAPPDATA%\faker-literature\literature_db.json |
What the importer does:
- ranks works by number of Wikipedia articles and keeps those having a French and an English title, an author, a date, at least one genre and an author nationality;
- localizes author names (Evgueni Zamiatine / Yevgeny Zamyatin, Platon / Plato);
- skips works already present in the bundled catalogue (same title, year ± 2);
- validates every record before writing anything;
- replaces the previously imported Wikidata books when run again (no duplicates).
It needs network access to
query.wikidata.organd takes about 20 seconds for 200 works.
Using the Enlarged Catalogue
from faker import Faker
from faker_literature import LiteratureProvider, default_db_path
LiteratureProvider.use_database(default_db_path()) # or any path
fake = Faker("en_US")
fake.add_provider(LiteratureProvider)
fake.book() # now drawn from bundled + imported books
use_database() applies to every provider instance in the process. Call LiteratureProvider.use_database(None) to go back to the bundled in-memory catalogue.
When a new version of the package ships an updated bundled catalogue, the persistent database refreshes its bundled books automatically and keeps imported ones.
Injecting Your Own Dataset
Books are grouped by source. replace_source() replaces all the books of one source with a new list:
from faker_literature import LiteratureProvider, default_db_path
store = LiteratureProvider.use_database(default_db_path())
store.replace_source("my_dataset", [
{
"writer": {"fr_FR": "Murasaki Shikibu", "en_US": "Murasaki Shikibu"},
"nationality": {"fr_FR": "japonais", "en_US": "Japanese"},
"title": {"fr_FR": "Le Dit du Genji", "en_US": "The Tale of Genji"},
"genre": {"fr_FR": ["roman", "classique"], "en_US": ["novel", "classic"]},
"year": 1008,
"pages": None,
"publisher": None,
},
])
store.sources() # {'builtin': 425, 'wikidata': 142, 'my_dataset': 1}
Record schema:
| Field | Required | Format |
|---|---|---|
writer |
✅ | string, or {"fr_FR": str, "en_US": str} |
nationality |
✅ | {"fr_FR": str, "en_US": str} |
title |
✅ | {"fr_FR": str, "en_US": str} |
genre |
✅ | {"fr_FR": [str, ...], "en_US": [str, ...]} (1 to 20 genres) |
year |
✅ | integer between -3000 and 2100 |
pages |
❌ | None, or {"fr_FR": int, "en_US": int} (1 to 100000, each may be None) |
publisher |
❌ | None, or {"fr_FR": str, "en_US": str} (each may be None) |
Strings must be non-empty and at most 300 characters. Extra fields (e.g. isbn, wikidata_id) are stored as is. If any record is invalid, replace_source() raises a ValueError naming the record and the field, and the database is left unchanged.
The
builtinsource is managed by the package: do not replace it yourself.
Storage API
| Member | Description |
|---|---|
LiteratureProvider.use_database(path=None) |
Switch every provider to the database at path (created if needed), or back to the in-memory catalogue. Returns the BookStore. |
default_db_path() |
Per-user cache location for the persistent database. |
BookStore.replace_source(source, books) |
Validate then replace the books of source; returns the number stored. |
BookStore.sources() |
Number of books per source. |
BookStore.books |
The underlying TinyDB table, for custom queries. |
provider.store |
The shared BookStore. |
provider.books |
Every book, localized for the provider's locale. |
provider.books_flat |
A copy of every raw (non-localized) record. |
The provider.* properties are not exposed on the Faker object (Faker only proxies methods): use a provider instance, provider = LiteratureProvider(fake).
Custom TinyDB query:
from tinydb import Query
store = LiteratureProvider.use_database(default_db_path())
Book = Query()
store.books.search((Book.year < 1900) & (Book.source == "wikidata"))
TinyDB has no index and reads the whole file for each query: it is comfortable up to a few thousand books.
🎯 Demo
Run the built-in demo to see every feature:
python -m faker_literature
Or with an enlarged catalogue:
python -m faker_literature --db ~/.cache/faker-literature/literature_db.json demo
Quick tour of both locales:
python -c "
from faker import Faker
from faker_literature import LiteratureProvider
for locale in ['en_US', 'fr_FR']:
fake = Faker(locale)
fake.add_provider(LiteratureProvider)
print(f'\n=== {locale} ===')
print(f'Writer: {fake.writer()}')
print(f'Title: {fake.title()}')
print(f'Genre: {fake.genre()}')
print(f'Publisher: {fake.publisher()}')
print(f'Book: {fake.book()}')
"
🧪 Development
git clone https://github.com/arribo44/faker-literature.git
cd faker-literature
python -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"
pytest # run the test suite (no network needed)
pytest --cov=faker_literature
python -m build # build the distributions
Project layout:
faker_literature/
├── __init__.py # LiteratureProvider
├── __main__.py # CLI: demo and import-wikidata
├── store.py # BookStore: TinyDB storage, validation, localization
├── importers/
│ └── wikidata.py # Wikidata importer
└── DATAS/
└── literature.json # bundled catalogue
🤝 Contributing
Contributions are welcome! Open a PR or issue to add authors and books to literature.json, write importers for new datasets (Open Library, Project Gutenberg, data.bnf.fr...), add new locales, or fix bugs.
When adding books, please provide both fr_FR and en_US values for every field and run pytest before submitting.
📜 License
MIT License. See LICENSE for details. Imported Wikidata content is available under CC0.
Metadata
Release files for faker-literature 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| faker_literature-0.2.1.tar.gz | 53.7 kB | Without provenance | Details for faker_literature-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| faker_literature-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for faker_literature-0.2.1-py3-none-any.whl |
Total release size: 99.2 kB
Release files / faker_literature-0.2.1.tar.gz
| Download URL | faker_literature-0.2.1.tar.gz |
|---|---|
| Size | 53.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d1eeed2263c4030284e26111735a8806fe553573bf9f0355a99ecc794cb1b4eb
|
|
BLAKE2b-256 checksum How to use checksums |
70f409f7e99abd81b1c0751de7f75d797eda51cd2a5444560fcb244e53969b89
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / faker_literature-0.2.1-py3-none-any.whl
| Download URL | faker_literature-0.2.1-py3-none-any.whl |
|---|---|
| Size | 45.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
883f9db2d364c8ccd1a44f59667f92ce8ead71971a55c082763950b3e5917aa7
|
|
BLAKE2b-256 checksum How to use checksums |
c070fd700b6b10fc5a4fc3b8d64526cce5286fceadbbf6dd672b9173a22ebdef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for faker-literature 0.2.1
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.