faker-grocery 0.3.1__tar.gz

faker_grocery-0.3.1/CHANGELOG.md

@@ -0,0 +1,170 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.3.1] - 2026-09-20
+
+### Fixed
+- `python -m faker_grocery` demo: the "Aisles" / "Aisles in department X" sections could print the same aisle twice (e.g. small departments like `pets`, with only 2 aisles, or `snacks et confiseries` with 11, have a real chance of repeats across 5 independent draws - a birthday-paradox effect, not a bug in the random generation itself). The demo now samples distinct aisles/departments (`distinct_sample()` helper using `random_elements(..., unique=True)`, capped to the pool size so it can't crash on a 1-aisle department). `fake.aisle()`/`fake.department()` themselves are unchanged: independent draws that can repeat are the correct, intended behavior for actual data generation.
+
+---
+
+## [0.3.0] - 2026-09-20
+
+### Added
+- Closed test coverage gaps found in an audit of `GroceryStoreProvider`'s public API: `aisle_name()`, `aisle_id()` without filter, integer (not just numeric-string) `department=`/`aisle=` filters, `product(aisle=...)`, `grocery_item(aisle=..., department=...)`, `quantity(max_quantity=...)`, `shopping_datetime(date=<datetime.datetime>)`, unknown-aisle error handling, and cross-language name resolution (e.g. filtering with an English department name while the provider language is `fr`).
+- Added `departments`/`aisles` property shape checks (counts, expected keys) as regression tests for the catalog data itself.
+- **Internal consistency / data integrity tests**, not just plausibility checks in isolation: every product's `base_price` falls within its department's declared price range (full 49,688-row scan), every product's `department_id` agrees with its aisle's declared department, `product_record()`'s embedded aisle/department names agree with an independent catalog lookup, and a department-restricted `grocery_list()`'s items are fully coherent (department, unit and price all agree with the requested department, `quantity * unit_price == total_price`).
+- **`unit(department=...)`**: units are now tied to what's plausible for a department (e.g. `L`/bottle/can for beverages, `kg`/bunch for produce, tube for personal care) via a new `department_units` catalog table, instead of being picked from one global list independently of the product. Fixes incoherent combinations such as "9 bottle x Bread" or "10 jar x Trash Bags" that a purely random unit could previously produce.
+- Added `can` and `tube` as new unit keys.
+- 25 new test cases overall (35 -> 60).
+
+### Changed
+- `grocery_item()` now calls `unit(department=...)` with the product's own department, so its `unit` field is always coherent with the product instead of independently random.
+- Replaced the `units: {language: [unit, ...]}` data table with `unit_labels: {unit_key: {language: label}}` + `department_units: {department_id: [unit_key, ...]}`. **Breaking for direct data access**: code reading `provider._data["units"]` directly must switch to `unit_labels`/`department_units`; the public `unit()` method is backwards compatible (still returns a localized string, now with an optional `department` filter).
+- Bumped version from 0.2.0 to 0.3.0.
+
+### Fixed
+- Documented (via `test_locale_property`) that `fake.locale` on the `Faker` instance is shadowed by Faker's own built-in `locale` attribute; `GroceryStoreProvider.locale` is only reachable on the provider instance directly (`GroceryStoreProvider(fake).locale`), not through the `Faker`/`fake.*` proxy. Not a bug, but a naming collision worth knowing about.
+
+---
+
+## [0.2.0] - 2026-09-20
+
+### Added
+- **Probable product prices**: every product now has a stable `base_price` derived from its department's typical price range (seeded on the product id, so it stays stable across data rebuilds).
+  - `price(product=<id>)` returns that product's base price jittered by a random **±5%**.
+  - `product_record()` now also returns `base_price` (stable catalog reference) and `price` (this instance, jittered).
+  - `grocery_item()` prices its product the same way instead of drawing a fresh uniform-random price from the whole department range.
+- **Family-aware shopping baskets**: `grocery_list()` gained a `family_size` parameter (default `2`, a couple) that scales:
+  - the default item-count range, when `min_items`/`max_items` are not given explicitly;
+  - the plausible quantity per item (bigger households buy more of a given article), via `grocery_item(family_size=...)` and `quantity(max_quantity=...)`.
+  - The returned dict now includes a `family_size` field.
+- **Optional shopping date/time**: new `shopping_datetime(date=None, open_hour=8, close_hour=20)` method returning a plausible trip datetime (random day within the last year, or a given date, combined with a random time within store opening hours).
+  - `grocery_list(with_datetime=True)` (or passing `date=...`) adds a `shopping_datetime` field to the result.
+- 12 new test cases covering price jitter, family-size scaling and shopping date/time generation.
+
+### Changed
+- `products` rows in `faker_grocery/data/grocery_data.json` gained a `base_price` field: `[id, aisle_id, department_id, base_price, name_<lang0>, name_<lang1>, ...]`.
+- `scripts/build_data.py` now derives each product's `base_price` from its department's price range (triangular distribution skewed towards the cheaper end).
+- Bumped version from 0.1.0 to 0.2.0 in `setup.py` and `faker_grocery/__version__`.
+- Updated README.md and examples with the new pricing and basket features.
+
+---
+
+## [0.1.0] - 2026-09-20
+
+### Added
+- Initial release of `faker-grocery`.
+- `GroceryStoreProvider` built from the Instacart Market Basket Analysis open dataset: 21 departments, 134 aisles, ~49,700 products.
+- Support for 2 languages: `en` (source data) and `fr` (departments/aisles hand-translated, product names translated via a curated ~700-word word-substitution dictionary).
+- `department()`, `department_id()`, `department_name()`, `aisle()`, `aisle_id()`, `aisle_name()` with optional filtering by department (id or localized name).
+- `product()`, `product_record()`, `product_name()` with optional filtering by aisle and/or department.
+- `price()`, `quantity()`, `unit()` helpers.
+- `grocery_item()` and `grocery_list(min_items, max_items, department=None)` for randomized shopping list generation.
+- `scripts/build_data.py` to (re)build the single-JSON catalog from `DATAS/*.csv` and the translation files in `scripts/translations/`, designed for adding further languages (`it`, `es`, `pt`, `de` planned).
+- Test suite (`tests/test_grocery_store.py`), demo (`python -m faker_grocery`) and complete usage example (`examples/basic_usage.py`).
+
+---
+
+## Usage Guidelines
+
+### How to Use This Changelog
+
+1. **Before releasing a new version**:
+   - Move all changes from `[Unreleased]` section to the new version section
+   - Add the release date
+   - Update the version in `setup.py` and `faker_grocery/__init__.py` (`__version__`)
+   - If the catalog data changed (`DATAS/*.csv` or `scripts/translations/*.json`), re-run `python scripts/build_data.py` before releasing
+
+2. **When making changes**:
+   - Add entries to the `[Unreleased]` section under the appropriate category
+   - Use past tense for entries (e.g., "Added" not "Add")
+   - Group similar changes together
+
+3. **Categories**:
+   - `Added`: New features
+   - `Changed`: Changes to existing functionality
+   - `Fixed`: Bug fixes
+   - `Removed`: Features that were removed
+   - `Deprecated`: Features that will be removed in future versions
+   - `Security`: Security-related changes
+
+### Versioning Rules
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR version** (X.0.0): When you make incompatible API changes
+- **MINOR version** (0.X.0): When you add functionality in a backwards-compatible manner
+- **PATCH version** (0.0.X): When you make backwards-compatible bug fixes
+
+### Example Workflow
+
+```bash
+# 1. Make your changes
+# 2. Update CHANGELOG.md in [Unreleased] section
+# 3. Commit changes
+git add .
+git commit -m "Add new feature X"
+
+# 4. When ready to release:
+#    - Create new version section in CHANGELOG.md
+#    - Update version in setup.py and faker_grocery/__init__.py
+#    - Commit
+git add CHANGELOG.md setup.py faker_grocery/__init__.py
+git commit -m "Bump version to 0.3.0"
+
+# 5. Tag the release
+git tag -a v0.3.0 -m "Release v0.3.0"
+git push origin v0.3.0
+
+# 6. Publish to PyPI
+twine upload dist/*
+```
+
+### Changelog Entry Examples
+
+```markdown
+## [0.3.0] - YYYY-MM-DD
+
+### Added
+- Added support for Italian catalog data (`it`)
+- Added `nutriscore` field to product records
+
+### Changed
+- Widened the price range for the "alcohol" department
+
+### Fixed
+- Fixed `aisle(department=...)` raising for department ids passed as `int`
+```
+
+---
+
+## Template for New Entries
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- 
+
+### Changed
+- 
+
+### Fixed
+- 
+
+### Removed
+- 
+
+### Deprecated
+- 
+
+### Security
+- 
+```

faker_grocery-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jctranc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

faker_grocery-0.3.1/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include CHANGELOG.md
+include LICENSE
+recursive-include faker_grocery/data *.json

faker_grocery-0.3.1/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: faker-grocery
+Version: 0.3.1
+Summary: A custom Faker provider for simulating supermarket/hypermarket products, aisles and departments
+Author: jctranc
+License: MIT
+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.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.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: faker>=20.0.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 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
+
+```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)
+```
+
+### 🏬 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_record()
+# {
+#     'id': 12345,
+#     'name': 'Yaourt Grec Vanille',
+#     'aisle_id': 120,
+#     'aisle': 'yaourt',
+#     'department_id': 16,
+#     'department': 'produits laitiers et œufs',
+# }
+
+fake.product_name(12345)                # look up a specific product id
+```
+
+### 💰 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)
+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)
+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")
+```
+
+### 📝 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%
+#     'total_price': 6.45,
+# }
+
+# 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,
+# }
+
+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 (random within the last
+# year, during store opening hours by default 8:00-20:00):
+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)
+```
+
+---
+
+## 🎯 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, name_<lang0>, name_<lang1>, ...]`
+- `price_ranges`: `{department_id: [min_price, max_price]}`
+- `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")
+- `meta`: supported/default/planned languages, source, field layout
+
+> `DATAS/*.csv` (the raw Instacart source: `aisles.csv`, `departments.csv`, `products.csv`) is **not** shipped in the installed package - only `grocery_data.json` is (see `MANIFEST.in`/`package_data` in `setup.py`), 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).
+
+## 🌐 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 ".[test]"
+pytest
+```
+
+---
+
+## 📜 License
+
+MIT License.

faker_grocery-0.3.1/README.md

@@ -0,0 +1,199 @@
+# 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
+
+```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)
+```
+
+### 🏬 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_record()
+# {
+#     'id': 12345,
+#     'name': 'Yaourt Grec Vanille',
+#     'aisle_id': 120,
+#     'aisle': 'yaourt',
+#     'department_id': 16,
+#     'department': 'produits laitiers et œufs',
+# }
+
+fake.product_name(12345)                # look up a specific product id
+```
+
+### 💰 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)
+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)
+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")
+```
+
+### 📝 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%
+#     'total_price': 6.45,
+# }
+
+# 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,
+# }
+
+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 (random within the last
+# year, during store opening hours by default 8:00-20:00):
+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)
+```
+
+---
+
+## 🎯 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, name_<lang0>, name_<lang1>, ...]`
+- `price_ranges`: `{department_id: [min_price, max_price]}`
+- `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")
+- `meta`: supported/default/planned languages, source, field layout
+
+> `DATAS/*.csv` (the raw Instacart source: `aisles.csv`, `departments.csv`, `products.csv`) is **not** shipped in the installed package - only `grocery_data.json` is (see `MANIFEST.in`/`package_data` in `setup.py`), 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).
+
+## 🌐 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 ".[test]"
+pytest
+```
+
+---
+
+## 📜 License
+
+MIT License.