Faker Grocery Store Provider
A custom Faker 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 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 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+.
cd faker_grocery
pip install -e .
🚀 Usage
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.
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
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
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.
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.
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
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
python -m faker_grocery
For a complete demo with more examples per feature and both locales, see 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 levelscountry_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/volumeorder_time_weights:[weekday][hour]order counts (weekday 0 = Monday) - drives realistic shopping days/hoursmeta: 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 statisticsorder_times.csvandproduct_popularity.csv) is not shipped in the installed package - onlygrocery_data.jsonis (seeMANIFEST.inand[tool.setuptools.package-data]inpyproject.toml), and using the library never touchesDATAS/. It is kept versioned in the repository, though:scripts/build_data.pyalways rebuilds the catalog from these CSVs (never fromgrocery_data.jsonitself), 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) andorder_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 runpython scripts/build_order_stats.py path/to/orders.csv path/to/order_products__prior.csvfollowed bypython scripts/build_data.py.
🌐 Adding a new language
The file is generated by 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):
- Create
scripts/translations/departments_it.jsonandaisles_it.json(21 and 134 hand-translated entries). - Create
scripts/translations/word_dict_it.json(a grocery vocabulary dictionary for word-substitution product name translation — seeword_dict_fr.jsonfor the format and scope). - Add
"it"toTRANSLATED_LANGUAGESinscripts/build_data.py. - Re-run:
python scripts/build_data.py
🧪 Tests
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 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 (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). The catalog data is covered by the section above.
Metadata
Release files for faker-grocery 0.5.0
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_grocery-0.5.0.tar.gz | 1.7 MB | Without provenance | Details for faker_grocery-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| faker_grocery-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for faker_grocery-0.5.0-py3-none-any.whl |
Total release size: 3.4 MB
Release files / faker_grocery-0.5.0.tar.gz
| Download URL | faker_grocery-0.5.0.tar.gz |
|---|---|
| Size | 1.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
401a837f1f7f4fb3913c47d6dc98cb7939a7a8688d0940141d386aa1371881e2
|
|
BLAKE2b-256 checksum How to use checksums |
b3dafcdc488336f83118f2427a8e9127eb854491f714739fedfbb6335f593cf2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / faker_grocery-0.5.0-py3-none-any.whl
| Download URL | faker_grocery-0.5.0-py3-none-any.whl |
|---|---|
| Size | 1.7 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4b6d023e780bd94557bd75e654421ac85dcba2784e1fd4e61b10f73698437e4a
|
|
BLAKE2b-256 checksum How to use checksums |
67bf756a29cb668d97433c8982db188289bcc1537e0cac55e5a78b3e0e7164a1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for faker-grocery 0.5.0
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.