Faker Grocery Store Provider
A custom Faker provider for generating realistic fake data for supermarkets and hypermarkets: departments, aisles, products (with package sizes, EAN-13 barcodes and labels such as organic or gluten free), prices, seasonal and coherent shopping lists, customers with or without a diet, till receipts with VAT and promotions, and daily sales time series - as Python dicts, CSV, JSON, Parquet or pandas DataFrames.
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, fr_CA, fr_BE... |
Hand-translated | Natural translation for the 2,000 most ordered products (~2/3 of generated products); approximate automatic translation for the rest |
it |
it_IT |
Hand-translated | Same as French |
es |
es_ES, es_MX... |
Hand-translated | Same as French |
pt |
pt_PT, pt_BR |
Hand-translated (European Portuguese) | Same as French (European Portuguese) |
de |
de_DE, de_AT, de_CH |
Hand-translated | Same as French (automatic part keeps the English word order, see below) |
Default language:
en(used for any locale not listed above, e.g. as a fallback).
Unit labels are translated in every language ("bouteille", "bottiglia",
"botella", "garrafa", "Flasche"). Only the product names of the language(s)
you actually use are loaded (one names_<lang>.json.gz file per language).
Translated product names come from two sources:
- The 2,000 most ordered products have a natural, checked translation in
every language (
scripts/translations/product_names_<lang>.json), in shelf-label style, brands kept as is: "Organic Raspberries" -> "Framboises bio", "Lamponi bio", "Frambuesas ecológicas", "Framboesas biológicas", "Bio-Himbeeren". Since products are picked by popularity, they make up about two thirds of generated products. - All other products are translated automatically: common expressions
first ("gluten free" -> "sans gluten",
phrases_<lang>.json), then the word order of fully known segments is reversed for the Romance languages (they put the noun first; segments are split at punctuation and linking words such as "with" or "and"), then word-by-word substitution with a ~1,200-word grocery dictionary (word_dict_<lang>.json), with function words in lower case inside the name ("Rigatoni avec Sauce"). Brand names stay untranslated. This is approximate, "faker-grade" output ("Tomates en dés Bio avec Herbes Italien"), fine for tests and demos but not a professional localization. German keeps the English word order, since it also puts the noun last ("Glutenfrei Schokoladenstückchen Kekse").
Overall, 1.4% (es) to 2.9% (it) of generated product names stay identical to the English name, mostly brand names ("Cheerios Honey Nut", "Smartwater").
📦 Installation
Requires Python 3.11+ and Faker 20+.
pip install faker-grocery
# With pandas DataFrames and Parquet export (pandas, pyarrow):
pip install "faker-grocery[data]"
🚀 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"].grocery_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.grocery_department() # "produits laitiers et œufs"
fake.department_id() # 16
fake.grocery_department(weighted=False) # uniform pick (default: popular departments more often)
fake.grocery_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(weighted=False) # uniform pick (default: popular aisles more often)
fake.aisle_name(120) # "yaourt"
Why
grocery_department()? Faker's own address providers already usedepartment()/department_name()for administrative departments (fr_FR:("18", "Cher"),"Sarthe";es_CO:"Cesar"). The store methods are therefore namedgrocery_department()/grocery_department_name(), and addingGroceryStoreProviderleaves Faker's methods untouched:fake = Faker("fr_FR") fake.add_provider(GroceryStoreProvider) fake.department() # ("18", "Cher") - Faker's, unchanged fake.grocery_department() # "produits laitiers et œufs"The former names
department()/department_name()still work as deprecated aliases (with aDeprecationWarning) in locales where they don't clash, e.g.en_US, and will be removed in 1.0.
🛒 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',
# 'unit': 'pot', # the product's own, fixed unit
# 'price_per': 'pot', # what the prices are for: one article, or one kg/L
# 'ean': '2000000123455', # stable, valid EAN-13 (in-store prefix 20)
# 'size': '500 g', # package size: '6 x 330 mL', '12 pièce(s)', or None
# 'reference_price': 4.08, # price per kg or L ("prix au kilo"), None if unknown
# 'reference_unit': 'kg',
# }
fake.product_ean(12345) # "2000000123455", always the same for this product
fake.product(aisle=24, month=6) # seasonal pick: strawberries in June, clementines in December
fake.product_name(12345) # look up a specific product id
Package sizes come from the product name when it states one ("12 oz" -> 340 g, "16 fl oz" -> 475 mL, "6 ct" -> 6 pieces), otherwise from sizes typical of the aisle and unit (a jar of spices 30-80 g, a pack of beer 6 to 24 x 330 mL, a box of eggs 6 to 12...). The dearer a product is within its price range, the bigger its package, so prices per kg stay plausible. Products sold by weight or volume have no size (the quantity bought is).
Seasonality: with a month (1-12), or in a grocery_list() with a date,
fresh fruits and vegetables in season come up about twice as often and
out-of-season ones less (strawberries, asparagus, clementines, squash...),
with seasons shifted by six months in the southern hemisphere (AU, NZ, AR,
CL, ZA, BR...).
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.
🏷️ Labels and diets
fake.product_record()["labels"] # ['organic', 'gluten_free'], often []
fake.product_labels(13176) # ['organic'] ("Bag of Organic Bananas")
fake.product(labels="organic") # only organic products
fake.product(labels=["vegan", "gluten_free"]) # products carrying both labels
fake.grocery_label_name("gluten_free") # "sans gluten" (localized)
fake.grocery_labels() # ['organic', 'gluten_free', 'vegan', 'lactose_free', 'sugar_free',
# 'low_fat', 'whole_grain', 'kosher', 'non_gmo']
fake.product(diet="vegan") # products a vegan customer may buy
fake.grocery_list(diet="gluten_free") # a whole basket fitting the diet
fake.product_fits_diet(24852, "vegetarian") # True (bananas)
fake.grocery_diets() # ['vegetarian', 'vegan', 'gluten_free', 'lactose_free']
fake.grocery_diet_name("vegetarian") # "végétarien"
Labels are what a product's name claims ("Organic", "Gluten Free", "Low Fat", "Whole Wheat"...) plus a few implied ones (vegan products and plant-based milks are lactose free): 5,004 organic products, ~980 low fat, ~850 lactose free, ~810 gluten free, ~500 whole grain, ~340 sugar free, 191 vegan, 65 kosher, 22 non-GMO. A product that doesn't say it is gluten free isn't labelled so, even when it naturally is (bananas).
Diets say what a customer following one may buy: meat and fish aisles are excluded for vegetarians, as are names mentioning chicken, bacon, anchovies... wherever they are shelved (soups, frozen meals); vegans also skip eggs, dairy, honey and names mentioning cheese, butter, milk... unless plant-based; gluten free excludes bread, pasta, cereal, beer and names mentioning wheat, noodles, breaded... unless labelled gluten free; lactose free excludes dairy unless labelled. They keep 73% (vegan) to 94% (vegetarian) of what is bought. Rules on names and aisles, approximate: fake data, never real dietary or allergy information (a "Hawaiian pizza" whose name doesn't say "ham" passes as vegetarian).
💰 Prices, quantities, units
Every product has a stable catalog base_price (its "probable price"),
organic and premium products ("Organic", "Premium", "Artisan", "Grass-Fed"...)
costing 25% more than their plain equivalent,
generated once from its department's typical range (or a finer per-aisle
and per-unit range where one is needed: a can of beer is not priced like a
bottle of spirits) - or, for products sold
by weight or volume, as a price per kg or per L from its aisle's own
range (fresh fruit 1.50-8 EUR/kg, seafood counter 12-45 EUR/kg, milk
0.90-2.50 EUR/L...). 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.
Every product also has one fixed unit, chosen among the units plausible for its aisle: milk is sold by the litre or the bottle, spices in jars, canned beans in food cans, meat at the counter by the kg or g... A given product is always sold the same way.
fake.price() # 4.77 (random department's typical range)
fake.price(department=16) # price within the dairy/eggs range (skewed towards cheap, like the catalog)
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(aisle=104) # "pot" - units plausible for that aisle (spices)
fake.unit(department=7) # units plausible for that department
# (e.g. "L"/"bouteille"/"canette" for beverages)
💱 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, es_AR → ARS,
ko_KR → KRW, zh_CN → CNY, tr_TR → TRY, etc.: 56 currencies, covering
the country of every Faker locale except Iran (fa_IR, no stable rate) and
the generic ar_AA. Eurozone countries (Bulgaria included since 2026), 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. Within the eurozone the level is per country too
(Portugal cheaper, Ireland dearer). Average default basket: ~85 EUR in
France, ~69 EUR in Portugal, ~93 EUR in Ireland, ~107 USD in the US,
~128 CHF in Switzerland. Prices are rounded to the currency's minor unit
(whole numbers for JPY, HUF, KRW, CLP, VND...; 3 decimals for BHD/JOD). 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(). When
you override the currency, prices follow that currency's main country
(a pt_PT faker set to USD gets US prices).
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,
# 'ean': '2000000123455',
# 'aisle': 'yaourt',
# 'department': 'produits laitiers et œufs',
# 'size': '4 x 125 g',
# 'quantity': 3,
# 'unit': 'pot', # the product's own unit (always the same for it)
# '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': 'Non traité Lent Cuit Jambon', 'quantity': 100, 'unit': 'g',
# 'unit_price': 17.53, 'price_per': 'kg', 'total_price': 1.75, ...}
# kg: 0.2 kg upwards in 0.05 kg steps; g: 100 g upwards in 50 g steps;
# L: 0.5 L steps - the upper bound grows with family_size. Only fresh
# produce, counters (meat, seafood, cheese, deli), bulk goods and drinks
# are sold this way; everything else is counted.
# The number of items follows the distribution of the ~3.2M Instacart baskets
# (many small baskets, a few very big ones, ~10 items on average), scaled by
# family_size (default 2, a couple: x0.8 for one person, +20% per extra
# person), which also scales the plausible quantity of each item.
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) # uniform item count in that range
fake.grocery_list(max_items=5) # measured count, capped at 5
fake.grocery_list(department="fruits et légumes") # restrict the whole list to one department
fake.grocery_list(coherent=False) # no complementary products (see below)
# Baskets are coherent by default: an item sometimes brings a complementary
# one (pasta -> pasta sauce, burger buns -> sausages, granola -> yogurt,
# chips -> dip...), within the item count. The 263 pairings and their
# probabilities are measured on the ~3.2M Instacart baskets: aisles bought
# together at least twice as often as by chance.
# Optionally attach a plausible shopping date/time (within the last year,
# during the country's store opening hours, see grocery_opening_hours()).
# Days and hours follow the locale's weekly shopping pattern (see below;
# weighted=False for a uniform pick), and fresh produce follows the season:
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.grocery_opening_hours() # (8, 21) in France, (7, 23) in the US, (8, 20) by default
fake.shopping_datetime() # random date (last year) + time within those hours
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
👤 Recurring customers
customer = fake.customer_profile() # or customer_profile(family_size=4)
# {'customer_id': 106053, 'name': 'Théophile Gosselin', 'family_size': 3,
# 'favorite_product_ids': [10246, 49044, ...], # 8 + 4 per person, often re-ordered products
# 'shopping_interval_days': 7, # 1 to 30, weekly and monthly most often
# 'reorder_rate': 0.54, # share of items re-ordered from favorites
# 'diet': None}
fake.customer_profile(diet="vegan") # favorites and baskets fit the diet
fake.customer_profile(diet="random") # ~5% vegetarian, 2% vegan, 2% gluten free, 4% lactose free
history = fake.customer_history(customer, trips=12) # 12 baskets, oldest first
history = fake.customer_history(trips=12, end_date=datetime.date(2026, 6, 30))
# Each basket is a grocery_list() dict with 'shopping_datetime' and
# 'customer_id'; trips are spaced by the shopping interval (give or take a
# third) and each item is a re-order of a favorite with probability reorder_rate.
Measured on the ~206,000 Instacart customers: the shopping interval follows the distribution of their median days between orders, the re-order rate the distribution of their share of re-ordered items (~45% on average), and favorites are picked in proportion to how often products are re-ordered (milk, bananas, eggs rather than one-off purchases).
🧾 Receipts
receipt = fake.receipt() # for a new grocery_list(with_datetime=True)
receipt = fake.receipt(basket) # for a given basket (grocery_list / customer_history)
receipt = fake.receipt(promotion_rate=0.3, payment_method="cash")
# {
# 'store': {'store_id': 5830, 'name': 'Épicerie Joubert', 'address': '42, avenue Renaud, ...'},
# 'receipt_number': '5830-14-783226', 'register': 14,
# 'datetime': datetime.datetime(2026, 8, 21, 9, 25, 30),
# 'lines': [{'product': ..., 'ean': ..., 'quantity': 3, 'unit_price': 4.29, 'total_price': 12.87,
# 'promotion': '2 achetés + 1 offert', 'discount': 4.29, 'vat_rate': 0.055}, ...],
# 'item_count': 9, 'subtotal': 86.62, 'discount_total': 5.95,
# 'taxes': [{'rate': 0.055, 'base': 76.46, 'amount': 4.21}], 'tax_total': 4.21,
# 'taxes_included': True, 'total': 80.67,
# 'payment_method': 'cash', 'amount_tendered': 100.0, 'change': 19.33, 'currency': 'EUR',
# }
fake.grocery_store() # a fictional store: id, localized name, address
- Promotions: each line has a
promotion_ratechance (default 15%) of a percentage off (10-50%), 3-for-2 or 2nd at half price (counted items bought in sufficient numbers), with localized labels. - VAT: approximate rates of ~27 countries, a reduced rate for food and the standard rate for alcohol, household, personal care, pet and baby care products (France 5.5% / 20%, Germany 7% / 19%...). Prices include it, except in the US and Canada where a sales tax is added at the till (groceries mostly exempt). Other countries get no tax breakdown.
- Payment: card, cash or mobile; paying cash hands over the next banknote or round amount, and gets change.
🕒 Shopping patterns
The weekly pattern of shopping days and hours depends on the locale's country:
| Pattern | Countries | Shape |
|---|---|---|
instacart_us (default) |
all others (US, GB, ...) | measured on ~3.4M US online orders: Sunday/Monday busiest, quiet at opening time |
sunday_morning |
FR, BE, LU, ES, IT, PT | Saturday busiest, lunchtime and after-work peaks, Sunday morning only |
sunday_closed |
DE, AT, CH, PL, NO | Saturday busiest, shops closed on Sunday |
fake.grocery_shopping_pattern() # "sunday_morning" for fr_FR
fake.set_grocery_shopping_pattern("instacart_us") # override
fake.set_grocery_shopping_pattern(None) # back to the locale's default
Days a pattern has shops closed never come up, unless you force one with
date= (its time is then uniform within opening hours). The two European
patterns are hand-made heuristics, not measured data. Instacart's
day-of-week encoding is undocumented and read as 0 = Sunday.
📈 Sales time series
import datetime
provider = GroceryStoreProvider(fake) # or fake.sales_series(...)
rows = provider.sales_series(datetime.date(2026, 1, 1), datetime.date(2026, 12, 31))
# one row per day and department:
# {'date': datetime.date(2026, 1, 1), 'baskets': 1185, 'department_id': 4,
# 'department': 'fruits et légumes', 'items': 3470, 'revenue': 15240.61, 'currency': 'EUR'}
provider.sales_series(start, end, by="aisle") # per day and aisle (134 rows a day)
provider.sales_series(start, end, by="total") # per day, whole store
provider.sales_series(baskets_per_day=3000) # a hypermarket (default 1000); last 30 days
provider.sales_series(start, end, noise=0) # smooth series (default 0.1)
Built from the same measured data as the baskets, without simulating each basket (a year of a store takes well under a second):
- traffic follows the locale's weekly shopping pattern around
baskets_per_day: busy Fridays and Saturdays, nothing on days shops are closed (Sundays in Germany), with day-to-day variation (noise); - items per basket follow the Instacart basket sizes (~10 on average);
- the mix of aisles follows product popularity, with fresh produce in and out of season month by month (hemisphere-aware);
- revenue uses the catalog prices, in the locale's currency.
baskets is the store's number of baskets that day, repeated on each row.
There is no trend, holiday or promotion effect: add them on top if your
demo needs one.
🔤 Type hints
The package is fully typed (it ships a py.typed marker), and the dicts it
returns are described by TypedDicts: ProductRecord, GroceryItem,
GroceryList, CustomerProfile, GroceryStore, Receipt, ReceiptLine
and TaxLine. Editors then autocomplete their keys, and mypy/pyright flag
typos and type errors:
error: TypedDict "GroceryItem" has no key "totl_price"
note: Did you mean "total_price"?
Faker attaches provider methods to fake at runtime, so type checkers
can't see the signature of fake.grocery_item() & co. by themselves. Two
ways to get typed results:
from faker_grocery import GroceryItem, GroceryStoreProvider
# 1. Annotate the result of a call on the Faker instance
item: GroceryItem = fake.grocery_item()
# 2. Or call the provider directly: everything is then typed automatically
grocery = GroceryStoreProvider(fake)
basket = grocery.grocery_list() # GroceryList
basket["items"][0]["unit_price"] # float
Prices are typed float; they are ints for currencies without minor units
(JPY, HUF), which type checkers accept wherever a float is expected.
🎯 Command line: demo and bulk export
The package installs a faker-grocery command (also python -m faker_grocery):
faker-grocery # demo, en_US and fr_FR
faker-grocery demo --locale de_DE # demo for one locale
faker-grocery --locale fr_FR # same, without "demo" (also -l fr_FR)
# Bulk export: baskets, receipts, customers (with their shopping history) or products
faker-grocery export baskets -n 10000 --locale fr_FR --format csv -o baskets.csv
faker-grocery export receipts -n 500 --format jsonl --seed 42 > receipts.jsonl
faker-grocery export customers -n 200 --trips 12 --format json -o customers.json
faker-grocery export products -n 5000 --locale it_IT --format csv -o products.csv
# Diets, sales, Parquet
faker-grocery export customers -n 1000 --diet random --format parquet -o customers.parquet
faker-grocery export baskets -n 500 --diet vegan -o vegan_baskets.csv
faker-grocery export sales -n 365 --start 2026-01-01 --by aisle --locale de_DE -o sales.csv
- Formats:
csvandparquethave one row per basket item (baskets,customers), per receipt line (receipts), per product or per day and department / aisle (sales), with the basket / receipt / customer fields repeated on each row - ready for a spreadsheet, pandas or a database import.jsonl(one record per line) andjsonkeep the nested structure. Dates are ISO 8601 in text formats, native dates and timestamps in Parquet; labels areorganic|gluten_freein CSV, lists in Parquet. Parquet needspip install "faker-grocery[data]"and-o. sales:-nis a number of days from--start(default: January 1st of this year), grouped--by total|department|aisle, around--baskets-per-day(default 1000).--dietkeeps baskets, receipts, customers or products to one diet;--diet randomgives a few customers one (see Recurring customers).--seedmakes the output reproducible;--localesets the language, currency, VAT, shopping hours and seasons (an unknown locale is rejected with the close matches); without-othe output goes to standard output.- With
-o, the file is only replaced once the export is complete: an interrupted or failed export never leaves a half-written file. Records are written as they are generated, so memory use stays flat even for largejsonexports. --csv-safeprefixes text cells starting with=,+,-or@with a', so that a spreadsheet opening the file can't run them as formulas (CSV injection). Off by default because it also changes legitimate values, such as promotion labels (-30 %->'-30 %).
🐼 pandas and Parquet from Python
from faker_grocery.export import to_dataframe, export_parquet
df = to_dataframe("baskets", 1000, locale="fr_FR", seed=42) # one row per basket item
df.groupby("department")["total_price"].sum()
sales = to_dataframe("sales", 365, locale="de_DE", by="aisle", start=datetime.date(2026, 1, 1))
customers = to_dataframe("customers", 200, diet="random", trips=12)
receipts = to_dataframe("receipts", 50, flat=False) # one row per receipt, nested lines
export_parquet("receipts", 10000, "en_US", "receipts.parquet", seed=1)
Same kinds, rows and options as the command line (diet, start, by,
baskets_per_day, trips); date and time columns are pandas datetimes.
For a complete demo with more examples per feature and both locales, see examples/basic_usage.py.
🧱 Data layout
Internal format. The data files described below are an implementation detail of the package, not a public API: their layout can change in any version. Use the provider's methods (
product_record(),aisle_name()...) rather than reading the files.
A single gzip-compressed JSON file, faker_grocery/data/grocery_data.json.gz, 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, unit, size, season, reorder_count, labels, diets, name_en](order_count: popularity, see below;unit: the product's fixed unit key;base_priceis per kg/L for measured units;size:[count, amount, "g"|"ml"|null]or null;season: 12-bit mask of the months a fresh product is in season, 0 for none;labels/diets: bit masks overlabel_keys/diet_keys, built byscripts/label_tables.py)- translated product names live in separate files,
faker_grocery/data/names_<lang>.json.gz(a list parallel toproducts, listed inmeta.name_files), loaded on first use of that language 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)country_price_levels:{country_code: level}- grocery price level relative to France, used when prices are in the country's own currencyunit_labels:{unit_key: {language: label}}(e.g."bottle": {"en": "bottle", "fr": "bouteille"})aisle_units:{aisle_id: [unit_key, ...]}- units plausible for each aisle; each product's fixed unit is one of themdepartment_units:{department_id: [unit_key, ...]}- union of the department's aisle units (used byunit(department=...))measured_units:{unit_key: {min, base, per_person, step, price_per, factor}}- quantity ranges and pricing basis of units sold by weight/volumemeasured_price_ranges:{aisle_id: [min, max]}- EUR per kg/L for aisles with measured unitsshopping_patterns:{name: [weekday][hour] weights}(weekday 0 = Monday) andcountry_shopping_patterns:{country_code: name}- realistic shopping days/hoursaisle_unit_price_ranges:{aisle_id: {unit_key: [min, max]}}- finer per-article EUR ranges (beer, fruit, vegetables, eggs)premium_surcharge,seasonal_factors,southern_hemisphere_countries- organic/premium price factor and seasonality settingsdefault_opening_hours,country_opening_hours:{country_code: [open, close]}country_vat:{country_code: [food_rate, standard_rate, included]}andaisle_tax_class:{aisle_id: "food"|"standard"}aisle_complements:[[aisle_id, complementary_aisle_id, probability], ...]- coherent baskets, from the Instacart co-purchase statisticsbasket_sizes,customer_intervals,customer_reorder_rates:[[value, count], ...]- Instacart distributions of items per order, customers' median days between orders and re-order share (%)store_name_templates,promotion_labels:{language: ...}- receiptsmeta: supported/default languages, name files, base currency, source, field layout
The store tables (sizes, seasons, VAT, opening hours, store names, promotions) are hand-made, in
scripts/store_tables.py.
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 - only thefaker_grocery/data/*.json.gzfiles are (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.json.gzitself), so they're the only way to regenerate the data at all - including to add a new language later (see below).
The statistics files (
order_times.csv,product_popularity.csv,basket_sizes.csv,aisle_orders.csv,aisle_pairs.csv,customer_intervals.csv,customer_reorder_rates.csv) are themselves aggregated from the much larger Instacartorders.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; the anonymous Kaggle download no longer works, but the Hugging Face mirror attik/Instacart-Market-Basket-Analysis has the same files and reproduces the versioned statistics exactly), then runpython scripts/build_order_stats.py path/to/orders.csv path/to/order_products__prior.csvfollowed bypython scripts/build_data.py. The script first checks the raw files' SHA-256 against the copy the statistics were built from, since the mirror is a third party (--no-verifyskips the check on purpose).
🌐 Adding a new language
The files are 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. nl):
- Create
scripts/translations/departments_nl.jsonandaisles_nl.json(21 and 134 hand-translated entries). - Create
scripts/translations/word_dict_nl.jsonandphrases_nl.json, with the same keys asword_dict_fr.json/phrases_fr.json(a ~1,200-word grocery vocabulary and ~90 multi-word expressions translated as a whole). - Optionally, create
scripts/translations/product_names_nl.json({product_id: name}) with natural translations of the most ordered products - they take precedence over the automatic translation. Seeproduct_names_fr.json. - Add
"nl"toTRANSLATED_LANGUAGES, and a"nl"label to every entry ofUNIT_LABELS, inscripts/build_data.py. If the language puts the noun first (like French, Italian, Spanish, Portuguese), also add it toNOUN_FIRST_LANGUAGESso word order is reversed. - Re-run:
python scripts/build_data.py
🧪 Tests
pip install -e ".[dev]"
pytest
ruff check .
mypy faker_grocery tests/test_typing.py
CI (.github/workflows/ci.yml) runs the linter, the type checker, the test
suite on Python 3.11-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, who could not relicense Instacart's data: the original Instacart terms still apply to the department, aisle and product names (including real brand names) and to the order statistics derived from them.
- Derived data: translated names, prices, units and price ranges are
generated by this project (
scripts/build_data.py,scripts/translations/). The translated names of the 2,000 most ordered products were translated with Claude (Anthropic) and spot-checked.
The MIT License below covers the code only, not the catalog data. If you plan to use or redistribute the catalog data in a commercial context, check the original Instacart terms yourself.
🔒 Stability and versioning
The project follows Semantic Versioning; while in 0.x:
- Public API: the provider's methods, their arguments and the fields of
the dicts they return (the
TypedDicts), and the command line. Removals and incompatible changes come in a minor version (0.x -> 0.(x+1)), after a deprecation warning when possible. - Same seed, same data within a minor version: 0.12.0 and 0.12.3 give the same values for the same seed and arguments. A new minor version may change generated values (new data, better distributions), as stated in the CHANGELOG.
- Not public: the data files (
faker_grocery/data/), the scripts and anything whose name starts with_. - Deprecated aliases
department()/department_name()will be removed in 1.0.
📜 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.13.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.13.0.tar.gz | 4.7 MB | Without provenance | Details for faker_grocery-0.13.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| faker_grocery-0.13.0-py3-none-any.whl | Python 3 | none | any | Details for faker_grocery-0.13.0-py3-none-any.whl |
Total release size: 9.3 MB
Release files / faker_grocery-0.13.0.tar.gz
| Download URL | faker_grocery-0.13.0.tar.gz |
|---|---|
| Size | 4.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
02d4184c83c21ad75e8a7a5b421ec8247cd41529d0daa1c1c36d59a9ea3852e1
|
|
BLAKE2b-256 checksum How to use checksums |
3d4253479e21f4a5b478934e9e120d3dcdf133307b4754966f7a7654df288a88
|
| 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.13.0-py3-none-any.whl
| Download URL | faker_grocery-0.13.0-py3-none-any.whl |
|---|---|
| Size | 4.6 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0f27350cff866fbcce335ba62f356f43916303b7c20379e44d681cea70d3e32b
|
|
BLAKE2b-256 checksum How to use checksums |
3b44ade74388eb357a91d8211bb7248555bc7e1aa282b6fbff13f5ac6b526ed2
|
| 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.13.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.