105 lines
2.8 KiB
Markdown
105 lines
2.8 KiB
Markdown
# Nutritional Recipe Parser
|
|
|
|
A Python application that parses recipes and looks up nutritional information for ingredients using the OpenFoodFacts API.
|
|
|
|
## Python Version
|
|
|
|
- **Required:** Python 3.8 or higher
|
|
- **Tested on:** Python 3.12.13
|
|
|
|
## Dependencies
|
|
|
|
### Python Libraries
|
|
|
|
The following Python packages are required:
|
|
|
|
| Package | Purpose | Install Method |
|
|
|---------|---------|----------------|
|
|
| `requests` | HTTP client for OpenFoodFacts API | `pip install requests` |
|
|
| `json` | Built-in | Python 3.x (no install needed) |
|
|
| `tkinter` | GUI toolkit (optional) | Usually bundled with Python |
|
|
|
|
### System Packages (apt)
|
|
|
|
For a fresh TrueNAS/Ubuntu/Debian environment, install the following:
|
|
|
|
```bash
|
|
sudo apt update
|
|
sudo apt install -y python3 python3-pip python3-tk
|
|
```
|
|
|
|
**Explanation:**
|
|
- `python3` - The Python interpreter (version 3.12.13 is available on this system)
|
|
- `python3-pip` - Pip package manager to install `requests` and other PyPI packages
|
|
- `python3-tk` - Tkinter support for the optional GUI mode
|
|
|
|
### Verifying Installation
|
|
|
|
After installing, verify the core dependency:
|
|
|
|
```bash
|
|
pip3 install --upgrade requests
|
|
```
|
|
|
|
Test the installation:
|
|
|
|
```bash
|
|
python3 --version
|
|
python3 -c "import requests; print('requests version:', requests.__version__)"
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Command-Line Interface
|
|
|
|
```bash
|
|
# Parse a recipe file and show summary
|
|
python3 main.py recipe.md
|
|
|
|
# Parse and output JSON to a file
|
|
python3 main.py recipe.md -o output.json
|
|
|
|
# Parse with verbose nutrition output
|
|
python3 main.py recipe.md -v
|
|
|
|
# List cached ingredients
|
|
python3 main.py --list-foods
|
|
```
|
|
|
|
### GUI Mode
|
|
|
|
Launch without arguments for a graphical interface:
|
|
|
|
```bash
|
|
python3 main.py
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
nutri_parser/
|
|
├── nutri_parser.py # Core parsing and API logic
|
|
├── recipe_parser.py # Recipe parsing utilities
|
|
├── main.py # Entry point (CLI + GUI)
|
|
├── README.md # This file
|
|
└── LICENSE # Project license
|
|
```
|
|
|
|
## API Integration
|
|
|
|
This project uses the [OpenFoodFacts](https://world.openfoodfacts.org/) open database API to look up nutritional values for ingredients. The API:
|
|
|
|
- **Does not require** an API key for basic use
|
|
- **Requires** a descriptive `User-Agent` header (set to `"RecipeParser/1.0"` in this project)
|
|
- **Recommends** rate limiting (1 request/second minimum) to avoid being blocked
|
|
- **Includes** automatic retry with exponential backoff (5 attempts with delays [2, 5, 10, 20, 30] seconds)
|
|
|
|
## Rate Limiting & Caching
|
|
|
|
- **Rate limiter:** Enforces 1 request per second minimum between API calls
|
|
- **SQLite cache:** Ingredient nutrition data is cached locally to avoid redundant API calls
|
|
- **Cache management:** Use `--list-foods` to view cached ingredients, or clear the cache file to refresh
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. |