Metadata-Version: 2.4
Name: faker-grocery
Version: 0.5.0
Summary: A custom Faker provider for simulating supermarket/hypermarket products, aisles and departments
Author: jctranc
License-Expression: MIT
Project-URL: Homepage, https://github.com/arribo44/faker-grocery
Project-URL: Changelog, https://github.com/arribo44/faker-grocery/blob/main/CHANGELOG.md
Keywords: faker,grocery,supermarket,hypermarket,test data
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: faker>=20.0.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

# Faker Grocery Store Provider

**A custom [Faker](https://faker.readthedocs.io/) provider for generating realistic fake data for supermarkets and hypermarkets: departments, aisles, products, prices and randomized shopping lists.**

The catalog is built from the [Instacart Market Basket Analysis](https://www.kaggle.com/c/instacart-market-basket-analysis) open dataset: **21 departments**, **134 aisles** and **~49,700 real products**.

---

## 🌍 Supported languages

| Language | Locale examples | Departments / Aisles | Product names |
|----------|------------------|-----------------------|----------------|
| `en` | `en_US` | Original English names | Original English names |
| `fr` | `fr_FR` | Hand-translated | Approximate word-substitution translation |

> **Default language**: `en` (used for any locale not listed above, e.g. as a fallback).

Planned extensions (data not built yet): `it`, `es`, `pt`, `de`. See [Adding a new language](#-adding-a-new-language) below.

Product names in `fr` are translated word-by-word from the source English names using a curated ~700-word grocery vocabulary dictionary (see `scripts/translations/word_dict_fr.json`). Words missing from the dictionary (mostly brand names) are left untranslated, and grammar/word order is not reordered. This is approximate, "faker-grade" data meant for tests and demos, not a professional localization.

---

## 📦 Installation

Requires Python 3.10+ and Faker 20+.

```bash
cd faker_grocery
pip install -e .
```

---

## 🚀 Usage

```python
from faker import Faker
from faker_grocery import GroceryStoreProvider

fake = Faker("fr_FR")          # or "en_US"
fake.add_provider(GroceryStoreProvider)
```

With a multi-locale `Faker([...])`, Faker's proxy does not support
`add_provider()`: add the provider to each locale's generator instead.

```python
fake = Faker(["fr_FR", "en_US"])
for locale in ("fr_FR", "en_US"):
    fake[locale].add_provider(GroceryStoreProvider)

fake["fr_FR"].department()              # "produits laitiers et œufs"
```

Unknown ids/names and invalid arguments (e.g. `min_items > max_items`,
`family_size < 1`, `open_hour >= close_hour`, only one of
`min_price`/`max_price`) raise `ValueError`.

### 🏬 Departments & aisles

```python
fake.department()                       # "produits laitiers et œufs"
fake.department_id()                    # 16
fake.department_name(16)                # "produits laitiers et œufs"

fake.aisle()                            # "yaourt"
fake.aisle(department="produits laitiers et œufs")   # restricted to that department
fake.aisle(department=16)               # same, by id
fake.aisle_id(department=16)            # 120
fake.aisle_name(120)                    # "yaourt"
```

### 🛒 Products

```python
fake.product()                          # "Yaourt Grec Vanille"
fake.product(aisle="yaourt")            # restricted to an aisle (name or id)
fake.product(department=16)             # restricted to a department (name or id)
fake.product(weighted=False)            # uniform pick instead of popularity-weighted (see below)

fake.product_record()
# {
#     'id': 12345,
#     'name': 'Yaourt Grec Vanille',
#     'aisle_id': 120,
#     'aisle': 'yaourt',
#     'department_id': 16,
#     'department': 'produits laitiers et œufs',
#     'base_price': 2.10,
#     'price': 2.04,
#     'currency': 'EUR',
# }

fake.product_name(12345)                # look up a specific product id
```

Products are picked **in proportion to their popularity**: how many times
each one was ordered in the ~32M order lines of the Instacart data. Bananas,
strawberries, milk or avocados come up far more often than niche items, as
in a real basket. Pass `weighted=False` to `product()`, `product_record()`,
`grocery_item()` or `grocery_list()` for a uniform pick across the catalog.

### 💰 Prices, quantities, units

Every product has a stable catalog **`base_price`** (its "probable price"),
generated once from its department's typical range. Any time you actually
price a product — via `price(product=...)`, `product_record()` or
`grocery_item()` — you get that base price jittered by a random **±5%**, the
way real shelf prices drift a little from one day/store to the next.

```python
fake.price()                            # 4.77  (random department's typical range)
fake.price(department=16)               # price within the dairy/eggs range
fake.price(min_price=10.0, max_price=20.0)   # both bounds are required
fake.price(product=12345)               # that product's base_price, jittered +/-5%

record = fake.product_record()
record["base_price"]                    # 2.10  (stable catalog reference)
record["price"]                         # 2.04  (this instance, +/-5% jitter)

fake.quantity()                         # 3   (1 to 10, a count of articles)
fake.quantity(max_quantity=5)           # 1 to 5

fake.unit()                             # "pièce(s)", "kg", "bouteille", ... (any unit)
fake.unit(department=7)                 # restricted to units plausible for that department
                                         # (e.g. "L"/"bouteille"/"canette" for beverages,
                                         # "kg"/"botte" for produce - not "9 bottle x Bread")
```

### 💱 Currency

Prices are generated in the currency of the locale's country: `en_US` → USD,
`en_GB` → GBP, `fr_CA` → CAD, `fr_CH` → CHF, `ja_JP` → JPY, etc. Eurozone
countries, and any country not in the list, use EUR (the catalog's base
currency). Prices are converted from EUR with **fixed approximate rates**
(not live exchange rates), then adjusted to the country's approximate
**grocery price level**: a plain conversion would make a basket cost the
same everywhere, whereas groceries are much dearer in Switzerland and much
cheaper in India (average basket: ~78 EUR in France, ~99 USD in the US,
~119 CHF in Switzerland). Prices are rounded to the currency's minor unit
(whole numbers for JPY/HUF). Every priced dict carries a `currency` field.

```python
fake = Faker("en_US")
fake.add_provider(GroceryStoreProvider)

fake.grocery_currency()                 # "USD"
fake.grocery_currency(symbol=True)      # "$"
fake.product_record()["currency"]       # "USD"

fake.set_grocery_currency("GBP")        # override the locale's currency
fake.set_grocery_currency(None)         # back to the locale's default
```

`price(min_price=..., max_price=...)` takes its bounds as already in the
current currency. The method is named `grocery_currency()` rather than
`currency_code()` so it doesn't shadow Faker's own `currency_code()`.
Supported currencies: EUR, USD, GBP, CHF, CAD, AUD, NZD, SEK, NOK, DKK, PLN,
CZK, HUF, JPY, INR, BRL, MXN.

### 📝 Grocery items & shopping lists

```python
fake.grocery_item()
# {
#     'product': 'Yaourt Grec Vanille',
#     'product_id': 12345,
#     'aisle': 'yaourt',
#     'department': 'produits laitiers et œufs',
#     'quantity': 3,
#     'unit': 'pot',                # always plausible for the product's department
#     'unit_price': 2.15,           # base_price jittered +/-5%
#     'price_per': 'pot',           # what unit_price is for (here: one article)
#     'total_price': 6.45,
#     'currency': 'EUR',
# }

# Items sold by weight or volume get a realistic measured quantity and are
# priced per kg or per L (no more "7 kg of basil"):
# {'product': 'Bio Bartlett Poire', 'quantity': 450, 'unit': 'g',
#  'unit_price': 3.86, 'price_per': 'kg', 'total_price': 1.74, ...}
# kg: 0.2 kg upwards in 0.05 kg steps; g: 100 g upwards in 50 g steps;
# L: 0.5 L steps; mL: 250 mL steps - the upper bound grows with family_size.

# family_size defaults to 2 (a couple). It scales the default item-count
# range and the plausible quantity of each item (bigger households buy more).
shopping_list = fake.grocery_list()
# {
#     'items': [ ... grocery_item dicts ... ],
#     'item_count': 9,
#     'family_size': 2,
#     'total': 42.31,
#     'currency': 'EUR',
# }

fake.grocery_list(family_size=5)                       # bigger default basket
fake.grocery_list(min_items=3, max_items=8)             # override the item-count range explicitly
fake.grocery_list(department="fruits et légumes")       # restrict the whole list to one department

# Optionally attach a plausible shopping date/time (within the last year,
# during store opening hours, by default 8:00-20:00). Days and hours follow
# the weekly pattern of the ~3.4M Instacart orders: busiest days get about
# 1.5x the trips of the quietest, and opening/closing hours are quieter than
# mid-day (weighted=False for a uniform pick):
shopping_list = fake.grocery_list(with_datetime=True)
shopping_list["shopping_datetime"]      # datetime.datetime(2026, 3, 12, 17, 42, 8)

# Or pin it to a specific date (random time on that day):
import datetime
fake.grocery_list(date=datetime.date(2025, 12, 24))

# Standalone helper used internally by grocery_list():
fake.shopping_datetime()                                # random date (last year) + time (8h-20h)
fake.shopping_datetime(date=datetime.date(2025, 12, 24))
fake.shopping_datetime(open_hour=9, close_hour=19)
fake.shopping_datetime(weighted=False)                  # uniform day and hour
```

> The time pattern comes from online orders placed in the US (Instacart). Its
> day-of-week encoding is undocumented and read as 0 = Sunday, making Sunday
> and Monday the busiest days - closer to US habits than to, say, France,
> where many supermarkets are closed on Sunday afternoon.

---

## 🎯 Demo

```bash
python -m faker_grocery
```

For a complete demo with more examples per feature and both locales, see [`examples/basic_usage.py`](examples/basic_usage.py).

---

## 🧱 Data layout

A single JSON file, `faker_grocery/data/grocery_data.json`, holds the whole catalog:

- `departments`: `{department_id: {language: name}}`
- `aisles`: `{aisle_id: {language: name, department_id: int}}` (each aisle belongs to exactly one department)
- `products`: compact rows `[id, aisle_id, department_id, base_price, order_count, name_<lang0>, name_<lang1>, ...]` (`order_count`: popularity, see below)
- `price_ranges`: `{department_id: [min_price, max_price]}` (in the base currency, EUR)
- `currencies`: `{code: {symbol, rate, price_level, decimals}}` - fixed approximate EUR -> currency rates and grocery price levels
- `country_currencies`: `{country_code: currency_code}` - default currency per locale country (unlisted countries use EUR)
- `unit_labels`: `{unit_key: {language: label}}` (e.g. `"bottle": {"en": "bottle", "fr": "bouteille"}`)
- `department_units`: `{department_id: [unit_key, ...]}` - which units are plausible for each department, so a generated item's unit always matches what the product actually is (no "9 bottle x Bread")
- `measured_units`: `{unit_key: {min, base, per_person, step, price_per, factor}}` - quantity ranges and pricing basis of units sold by weight/volume
- `order_time_weights`: `[weekday][hour]` order counts (weekday 0 = Monday) - drives realistic shopping days/hours
- `meta`: supported/default/planned languages, base currency, source, field layout

> `DATAS/*.csv` (the raw Instacart source: `aisles.csv`, `departments.csv`, `products.csv`, plus the aggregated order statistics `order_times.csv` and `product_popularity.csv`) is **not** shipped in the installed package - only `grocery_data.json` is (see `MANIFEST.in` and `[tool.setuptools.package-data]` in `pyproject.toml`), and using the library never touches `DATAS/`. It **is** kept versioned in the repository, though: `scripts/build_data.py` always rebuilds the catalog from these CSVs (never from `grocery_data.json` itself), so they're the only way to regenerate the data at all - including to add a new language later (see below).

> The two statistics files are themselves aggregated from the much larger
> Instacart `orders.csv` (~109 MB) and `order_products__prior.csv` (~578 MB),
> which are **not** versioned. They only need regenerating if the source data
> changes: download them from the Kaggle dataset (see below), then run
> `python scripts/build_order_stats.py path/to/orders.csv path/to/order_products__prior.csv`
> followed by `python scripts/build_data.py`.

## 🌐 Adding a new language

The file is generated by [`scripts/build_data.py`](scripts/build_data.py) from the raw CSVs in `DATAS/` (`aisles.csv`, `departments.csv`, `products.csv`) plus the translation files in `scripts/translations/`. To add a language (e.g. `it`):

1. Create `scripts/translations/departments_it.json` and `aisles_it.json` (21 and 134 hand-translated entries).
2. Create `scripts/translations/word_dict_it.json` (a grocery vocabulary dictionary for word-substitution product name translation — see `word_dict_fr.json` for the format and scope).
3. Add `"it"` to `TRANSLATED_LANGUAGES` in `scripts/build_data.py`.
4. Re-run:
   ```bash
   python scripts/build_data.py
   ```

---

## 🧪 Tests

```bash
pip install -e ".[dev]"
pytest
ruff check .
```

CI (`.github/workflows/ci.yml`) runs the linter, the test suite on Python
3.10-3.14 (plus the oldest supported Faker, 20.0.0) and a package build.

---

## 📊 Data source & license

The product catalog (`DATAS/*.csv`, and the `grocery_data.json` built from
it) contains the `departments`, `aisles` and `products` tables (names and
categories) plus anonymous aggregate counts derived from the order tables:
number of orders per weekday/hour slot and number of orders per product. No
individual order, customer or transaction data is included.

- **Original source**: the [Instacart Market Basket Analysis](https://www.kaggle.com/c/instacart-market-basket-analysis/data)
  Kaggle competition (2017), released by Instacart as
  *"3 Million Instacart Orders, Open Sourced"*. The original data is subject
  to the terms set by Instacart and the competition rules.
- **Copy used here**: the Kaggle re-upload
  [InstaCart Online Grocery Basket Analysis Dataset](https://www.kaggle.com/datasets/yasserh/instacart-online-grocery-basket-analysis-dataset)
  (by M Yasser H), published under **CC0: Public Domain**. That license is
  the one declared by the re-uploader.
- **Derived data**: French names, prices, units and price ranges are
  generated by this project (`scripts/build_data.py`, `scripts/translations/`).

If you plan to redistribute the catalog data in a commercial context, check
the original Instacart terms yourself.

## 📜 License

The **code** of this project is released under the MIT License (see
[`LICENSE`](LICENSE)). The catalog data is covered by the section above.
