# 🥑 Avocavo Python SDK
> Nutrition analysis made simple. Get accurate USDA nutrition data with secure authentication.
## 🚀 Quick Start
```python
import avocavo
# Login to your account (OAuth flow)
avocavo.login()
# Analyze a single ingredient
result = avocavo.analyze("1 cup brown rice")
print(f"Calories: {result.nutrition.calories}")
# Analyze a recipe
recipe = avocavo.analyze_recipe([
"2 large eggs",
"1 cup all-purpose flour",
"1/2 cup milk"
])
print(f"Total calories: {recipe.total_nutrition.calories}")
```
## 📦 Installation
```bash
pip install avocavo
```
**Requirements:**
- Python >= 3.8
- Internet connection for API access
## 🔐 Authentication
1. **Sign up** at [nutrition.avocavo.app](https://nutrition.avocavo.app)
2. **Login** via Python:
```python
import avocavo
avocavo.login() # Opens browser for secure OAuth
```
3. Your credentials are stored securely in your system keyring
## 📖 Basic Usage
### Single Ingredient Analysis
```python
import avocavo
# Simple ingredient analysis
result = avocavo.analyze("1 cup quinoa, cooked")
print(f"Calories: {result.nutrition.calories}")
print(f"Protein: {result.nutrition.protein}g")
print(f"Fiber: {result.nutrition.fiber}g")
# Access USDA match information
print(f"USDA Food: {result.usda_match.description}")
print(f"Confidence: {result.usda_match.confidence_score}")
```
### Recipe Analysis
```python
# Analyze a complete recipe
ingredients = [
"2 cups rolled oats",
"1 banana, mashed",
"1/2 cup blueberries",
"1 cup almond milk"
]
recipe = avocavo.analyze_recipe(ingredients)
# Get totals
print(f"Total Calories: {recipe.total_nutrition.calories}")
print(f"Total Protein: {recipe.total_nutrition.protein}g")
# Get per-serving (if servings specified)
print(f"Per Serving: {recipe.per_serving_nutrition.calories} calories")
# Individual ingredient breakdown
for ingredient in recipe.ingredients:
print(f"{ingredient.original_input}: {ingredient.nutrition.calories} cal")
```
### Batch Analysis
```python
# Analyze multiple ingredients efficiently
ingredients = [
"1 cup rice",
"100g chicken breast",
"1 medium apple",
"2 tbsp olive oil"
]
results = avocavo.analyze_batch(ingredients)
for result in results:
print(f"{result.original_input}: {result.nutrition.calories} calories")
```
## 🔧 Advanced Usage
### Using the Client Class
```python
from avocavo import NutritionAPI
# Initialize client (uses stored credentials)
client = NutritionAPI()
# Analyze with additional options
result = client.analyze_ingredient(
"1 cup rice",
include_sub_nutrients=True,
portion_precision="high"
)
# Get detailed nutrition breakdown
nutrients = result.nutrition.detailed_nutrients
for nutrient in nutrients:
print(f"{nutrient.name}: {nutrient.amount}{nutrient.unit}")
```
### Account Management
```python
import avocavo
# Check your usage
usage = avocavo.get_account_usage()
print(f"Requests used: {usage.requests_used}/{usage.requests_limit}")
# Get current user info
user = avocavo.get_current_user()
print(f"Logged in as: {user.email}")
# Manage API keys
api_keys = avocavo.list_api_keys()
for key in api_keys:
print(f"Key: {key.name} (Created: {key.created_at})")
```
## 🔒 Security Features
- **🔐 Secure Authentication**: OAuth flow with system keyring storage
- **🛡️ SSL Verification**: All API calls use verified HTTPS connections
- **🔑 No Hardcoded Secrets**: Credentials stored securely, never in code
- **🚫 Input Sanitization**: All inputs properly validated and sanitized
## 📊 Data Models
### Nutrition Object
```python
nutrition = result.nutrition
# Macronutrients
print(nutrition.calories) # kcal
print(nutrition.protein) # grams
print(nutrition.carbs) # grams
print(nutrition.fat) # grams
print(nutrition.fiber) # grams
# Micronutrients
print(nutrition.sodium) # mg
print(nutrition.calcium) # mg
print(nutrition.iron) # mg
print(nutrition.vitamin_c) # mg
```
### USDA Match Information
```python
match = result.usda_match
print(match.fdc_id) # USDA FDC ID
print(match.description) # Food description
print(match.confidence_score) # Match confidence (0-1)
print(match.data_type) # SR Legacy, Foundation, etc.
```
## 🚨 Error Handling
```python
from avocavo import ApiError
try:
result = avocavo.analyze("invalid ingredient")
except ApiError as e:
print(f"API Error: {e.message}")
print(f"Status Code: {e.status_code}")
if e.status_code == 401:
print("Authentication required - run avocavo.login()")
elif e.status_code == 429:
print("Rate limit exceeded - upgrade your plan")
```
## 📚 Examples
### Meal Planning
```python
import avocavo
# Plan a day of meals
breakfast = avocavo.analyze_recipe([
"2 eggs, scrambled",
"1 slice whole wheat toast",
"1/2 avocado"
])
lunch = avocavo.analyze_recipe([
"4 oz grilled chicken",
"1 cup quinoa",
"1 cup steamed broccoli"
])
dinner = avocavo.analyze_recipe([
"6 oz salmon fillet",
"1 cup brown rice",
"1 cup roasted vegetables"
])
# Calculate daily totals
daily_calories = (breakfast.total_nutrition.calories +
lunch.total_nutrition.calories +
dinner.total_nutrition.calories)
print(f"Daily Total: {daily_calories} calories")
```
### Recipe Scaling
```python
# Original recipe for 4 servings
original = avocavo.analyze_recipe([
"2 cups flour",
"4 eggs",
"1 cup milk"
], servings=4)
# Scale to 8 servings (double)
scale_factor = 8 / 4
scaled_ingredients = []
for ingredient in original.ingredients:
# Extract amount and scale (simplified example)
scaled_amount = ingredient.parsed_amount * scale_factor
scaled_ingredients.append(f"{scaled_amount} {ingredient.parsed_unit} {ingredient.parsed_food}")
scaled_recipe = avocavo.analyze_recipe(scaled_ingredients, servings=8)
```
## 🆘 Support
- **Documentation**: [nutrition.avocavo.app/docs/python](https://nutrition.avocavo.app/docs/python)
- **API Dashboard**: [nutrition.avocavo.app](https://nutrition.avocavo.app)
- **Issues**: [GitHub Issues](https://github.com/avocavo/avocavo-python/issues)
- **Email**: api-support@avocavo.com
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
---
## 🔄 Migrating from avocavo-nutrition?
The old package has been deprecated due to security vulnerabilities. Migration is straightforward:
```bash
# Remove old package
pip uninstall avocavo-nutrition
# Install new secure package
pip install avocavo
```
**Code changes:**
```python
# OLD (deprecated)
import avocavo_nutrition as av
av.login()
# NEW (secure)
import avocavo
avocavo.login()
```
All functionality remains the same - only the import and security have been improved!
Raw data
{
"_id": null,
"home_page": "https://github.com/avocavo/avocavo-python",
"name": "avocavo",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "nutrition, api, usda, food, recipe, health, fitness, calories, macros, nutrients, fooddata, fdc, cooking, meal-planning, diet, wellness, avocavo, secure",
"author": "Avocavo",
"author_email": "api-support@avocavo.com",
"download_url": "https://files.pythonhosted.org/packages/3e/7e/a47bb32d2cbc1673ab3e3d0944dbe648acf1638353d01efd1b4366d716a7/avocavo-1.0.1.tar.gz",
"platform": "any",
"description": "# \ud83e\udd51 Avocavo Python SDK\n\n> Nutrition analysis made simple. Get accurate USDA nutrition data with secure authentication.\n\n## \ud83d\ude80 Quick Start\n\n```python\nimport avocavo\n\n# Login to your account (OAuth flow)\navocavo.login()\n\n# Analyze a single ingredient\nresult = avocavo.analyze(\"1 cup brown rice\")\nprint(f\"Calories: {result.nutrition.calories}\")\n\n# Analyze a recipe\nrecipe = avocavo.analyze_recipe([\n \"2 large eggs\",\n \"1 cup all-purpose flour\", \n \"1/2 cup milk\"\n])\nprint(f\"Total calories: {recipe.total_nutrition.calories}\")\n```\n\n## \ud83d\udce6 Installation\n\n```bash\npip install avocavo\n```\n\n**Requirements:**\n- Python >= 3.8\n- Internet connection for API access\n\n## \ud83d\udd10 Authentication\n\n1. **Sign up** at [nutrition.avocavo.app](https://nutrition.avocavo.app)\n2. **Login** via Python:\n ```python\n import avocavo\n avocavo.login() # Opens browser for secure OAuth\n ```\n3. Your credentials are stored securely in your system keyring\n\n## \ud83d\udcd6 Basic Usage\n\n### Single Ingredient Analysis\n```python\nimport avocavo\n\n# Simple ingredient analysis\nresult = avocavo.analyze(\"1 cup quinoa, cooked\")\n\nprint(f\"Calories: {result.nutrition.calories}\")\nprint(f\"Protein: {result.nutrition.protein}g\")\nprint(f\"Fiber: {result.nutrition.fiber}g\")\n\n# Access USDA match information\nprint(f\"USDA Food: {result.usda_match.description}\")\nprint(f\"Confidence: {result.usda_match.confidence_score}\")\n```\n\n### Recipe Analysis\n```python\n# Analyze a complete recipe\ningredients = [\n \"2 cups rolled oats\",\n \"1 banana, mashed\", \n \"1/2 cup blueberries\",\n \"1 cup almond milk\"\n]\n\nrecipe = avocavo.analyze_recipe(ingredients)\n\n# Get totals\nprint(f\"Total Calories: {recipe.total_nutrition.calories}\")\nprint(f\"Total Protein: {recipe.total_nutrition.protein}g\")\n\n# Get per-serving (if servings specified)\nprint(f\"Per Serving: {recipe.per_serving_nutrition.calories} calories\")\n\n# Individual ingredient breakdown\nfor ingredient in recipe.ingredients:\n print(f\"{ingredient.original_input}: {ingredient.nutrition.calories} cal\")\n```\n\n### Batch Analysis\n```python\n# Analyze multiple ingredients efficiently\ningredients = [\n \"1 cup rice\",\n \"100g chicken breast\",\n \"1 medium apple\",\n \"2 tbsp olive oil\"\n]\n\nresults = avocavo.analyze_batch(ingredients)\n\nfor result in results:\n print(f\"{result.original_input}: {result.nutrition.calories} calories\")\n```\n\n## \ud83d\udd27 Advanced Usage\n\n### Using the Client Class\n```python\nfrom avocavo import NutritionAPI\n\n# Initialize client (uses stored credentials)\nclient = NutritionAPI()\n\n# Analyze with additional options\nresult = client.analyze_ingredient(\n \"1 cup rice\", \n include_sub_nutrients=True,\n portion_precision=\"high\"\n)\n\n# Get detailed nutrition breakdown\nnutrients = result.nutrition.detailed_nutrients\nfor nutrient in nutrients:\n print(f\"{nutrient.name}: {nutrient.amount}{nutrient.unit}\")\n```\n\n### Account Management\n```python\nimport avocavo\n\n# Check your usage\nusage = avocavo.get_account_usage()\nprint(f\"Requests used: {usage.requests_used}/{usage.requests_limit}\")\n\n# Get current user info\nuser = avocavo.get_current_user()\nprint(f\"Logged in as: {user.email}\")\n\n# Manage API keys\napi_keys = avocavo.list_api_keys()\nfor key in api_keys:\n print(f\"Key: {key.name} (Created: {key.created_at})\")\n```\n\n## \ud83d\udd12 Security Features\n\n- **\ud83d\udd10 Secure Authentication**: OAuth flow with system keyring storage\n- **\ud83d\udee1\ufe0f SSL Verification**: All API calls use verified HTTPS connections \n- **\ud83d\udd11 No Hardcoded Secrets**: Credentials stored securely, never in code\n- **\ud83d\udeab Input Sanitization**: All inputs properly validated and sanitized\n\n## \ud83d\udcca Data Models\n\n### Nutrition Object\n```python\nnutrition = result.nutrition\n\n# Macronutrients\nprint(nutrition.calories) # kcal\nprint(nutrition.protein) # grams\nprint(nutrition.carbs) # grams \nprint(nutrition.fat) # grams\nprint(nutrition.fiber) # grams\n\n# Micronutrients\nprint(nutrition.sodium) # mg\nprint(nutrition.calcium) # mg\nprint(nutrition.iron) # mg\nprint(nutrition.vitamin_c) # mg\n```\n\n### USDA Match Information\n```python\nmatch = result.usda_match\n\nprint(match.fdc_id) # USDA FDC ID\nprint(match.description) # Food description\nprint(match.confidence_score) # Match confidence (0-1)\nprint(match.data_type) # SR Legacy, Foundation, etc.\n```\n\n## \ud83d\udea8 Error Handling\n\n```python\nfrom avocavo import ApiError\n\ntry:\n result = avocavo.analyze(\"invalid ingredient\")\nexcept ApiError as e:\n print(f\"API Error: {e.message}\")\n print(f\"Status Code: {e.status_code}\")\n \n if e.status_code == 401:\n print(\"Authentication required - run avocavo.login()\")\n elif e.status_code == 429:\n print(\"Rate limit exceeded - upgrade your plan\")\n```\n\n## \ud83d\udcda Examples\n\n### Meal Planning\n```python\nimport avocavo\n\n# Plan a day of meals\nbreakfast = avocavo.analyze_recipe([\n \"2 eggs, scrambled\",\n \"1 slice whole wheat toast\",\n \"1/2 avocado\"\n])\n\nlunch = avocavo.analyze_recipe([\n \"4 oz grilled chicken\",\n \"1 cup quinoa\",\n \"1 cup steamed broccoli\"\n])\n\ndinner = avocavo.analyze_recipe([\n \"6 oz salmon fillet\",\n \"1 cup brown rice\", \n \"1 cup roasted vegetables\"\n])\n\n# Calculate daily totals\ndaily_calories = (breakfast.total_nutrition.calories + \n lunch.total_nutrition.calories + \n dinner.total_nutrition.calories)\n\nprint(f\"Daily Total: {daily_calories} calories\")\n```\n\n### Recipe Scaling\n```python\n# Original recipe for 4 servings\noriginal = avocavo.analyze_recipe([\n \"2 cups flour\",\n \"4 eggs\",\n \"1 cup milk\"\n], servings=4)\n\n# Scale to 8 servings (double)\nscale_factor = 8 / 4\n\nscaled_ingredients = []\nfor ingredient in original.ingredients:\n # Extract amount and scale (simplified example)\n scaled_amount = ingredient.parsed_amount * scale_factor\n scaled_ingredients.append(f\"{scaled_amount} {ingredient.parsed_unit} {ingredient.parsed_food}\")\n\nscaled_recipe = avocavo.analyze_recipe(scaled_ingredients, servings=8)\n```\n\n## \ud83c\udd98 Support\n\n- **Documentation**: [nutrition.avocavo.app/docs/python](https://nutrition.avocavo.app/docs/python)\n- **API Dashboard**: [nutrition.avocavo.app](https://nutrition.avocavo.app)\n- **Issues**: [GitHub Issues](https://github.com/avocavo/avocavo-python/issues)\n- **Email**: api-support@avocavo.com\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n## \ud83d\udd04 Migrating from avocavo-nutrition?\n\nThe old package has been deprecated due to security vulnerabilities. Migration is straightforward:\n\n```bash\n# Remove old package\npip uninstall avocavo-nutrition\n\n# Install new secure package\npip install avocavo\n```\n\n**Code changes:**\n```python\n# OLD (deprecated)\nimport avocavo_nutrition as av\nav.login()\n\n# NEW (secure)\nimport avocavo\navocavo.login()\n```\n\nAll functionality remains the same - only the import and security have been improved!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Avocavo Python SDK - Nutrition analysis made simple with secure USDA data access",
"version": "1.0.1",
"project_urls": {
"API Dashboard": "https://nutrition.avocavo.app",
"Bug Tracker": "https://github.com/avocavo/avocavo-python/issues",
"Changelog": "https://github.com/avocavo/avocavo-python/blob/main/CHANGELOG.md",
"Documentation": "https://nutrition.avocavo.app/docs/python",
"Download": "https://pypi.org/project/avocavo/",
"Homepage": "https://avocavo.app",
"Support": "https://nutrition.avocavo.app/support"
},
"split_keywords": [
"nutrition",
" api",
" usda",
" food",
" recipe",
" health",
" fitness",
" calories",
" macros",
" nutrients",
" fooddata",
" fdc",
" cooking",
" meal-planning",
" diet",
" wellness",
" avocavo",
" secure"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4e380abbfaeaf8a1af77a015bcec58025cdc681966af7413f6065b388dde42d9",
"md5": "429715ab014d37c1b555089a03ea0e20",
"sha256": "1d3f4cc069b6eb8fe80d50ca1116ee9f1fec916d50f7885210609162eef22373"
},
"downloads": -1,
"filename": "avocavo-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "429715ab014d37c1b555089a03ea0e20",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 27915,
"upload_time": "2025-08-01T00:51:36",
"upload_time_iso_8601": "2025-08-01T00:51:36.573900Z",
"url": "https://files.pythonhosted.org/packages/4e/38/0abbfaeaf8a1af77a015bcec58025cdc681966af7413f6065b388dde42d9/avocavo-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3e7ea47bb32d2cbc1673ab3e3d0944dbe648acf1638353d01efd1b4366d716a7",
"md5": "47a563c7c0dcb8fe1716bd51dae446fc",
"sha256": "328b8ae339687a2374d02c233f73a7627d982acfa6e8145f3acc31dc2d8a3405"
},
"downloads": -1,
"filename": "avocavo-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "47a563c7c0dcb8fe1716bd51dae446fc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 29404,
"upload_time": "2025-08-01T00:51:37",
"upload_time_iso_8601": "2025-08-01T00:51:37.873917Z",
"url": "https://files.pythonhosted.org/packages/3e/7e/a47bb32d2cbc1673ab3e3d0944dbe648acf1638353d01efd1b4366d716a7/avocavo-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 00:51:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "avocavo",
"github_project": "avocavo-python",
"github_not_found": true,
"lcname": "avocavo"
}
JSON
