nutri_parser/README.md

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:

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:

pip3 install --upgrade requests

Test the installation:

python3 --version
python3 -c "import requests; print('requests version:', requests.__version__)"

Usage

Command-Line Interface

# 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:

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 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 file for details.