Metadata-Version: 2.4
Name: faker-literature
Version: 0.2.1
Summary: A Faker provider for generating literature-related data
Author: arribo44
Author-email: pypi-jctranc@mailo.com
Project-URL: Homepage, https://github.com/arribo44/faker-literature
Project-URL: Documentation, https://github.com/arribo44/faker-literature#readme
Project-URL: Source, https://github.com/arribo44/faker-literature
Project-URL: Bug Tracker, https://github.com/arribo44/faker-literature/issues
Keywords: faker literature books authors test data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: faker>=20.0.0
Requires-Dist: tinydb>=4.0.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Faker Literature Provider

[![PyPI version](https://badge.fury.io/py/faker-literature.svg)](https://badge.fury.io/py/faker-literature)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)

**A custom [Faker](https://faker.readthedocs.io/) 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](https://www.wikidata.org/) 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 a `ValueError`, so unsupported data is never silently mixed into a dataset.

---

## 📦 Installation

```bash
pip install faker-literature
```

Or install from the repository:

```bash
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

```python
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.

```python
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

```python
# 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:

```python
fake.writer(nationality="American", genre="nope")
# ValueError: No writer found for nationality='American', genre='nope'
```

---

### 🏷️ Titles

```python
# 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

```python
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:

```python
# 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:

```python
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:

```python
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:

```python
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

```python
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:

```bash
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) |

```bash
# 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.org` and takes about 20 seconds for 200 works.

### Using the Enlarged Catalogue

```python
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:

```python
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 `builtin` source 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:

```python
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:

```bash
python -m faker_literature
```

Or with an enlarged catalogue:

```bash
python -m faker_literature --db ~/.cache/faker-literature/literature_db.json demo
```

Quick tour of both locales:

```bash
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

```bash
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](LICENSE) for details. Imported Wikidata content is available under [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
