Basic Concepts

Understanding the core concepts of TomatoPy will help you make the most of the library. This guide introduces the fundamental ideas and components.

Core Components

1. Ingredients

Ingredients are the building blocks of TomatoPy. Each ingredient has properties that affect how it behaves during cooking operations.

from tomatopy import Ingredient

# Create a basic ingredient
tomato = Ingredient(
    name="tomato",
    amount=1,
    unit="whole",
    properties={
        "ripeness": 0.8,
        "water_content": 0.95,
        "sugar_content": 0.03
    }
)

2. Kitchen

The Kitchen class represents your virtual cooking environment. It manages cooking operations and maintains environmental conditions.

from tomatopy import Kitchen

kitchen = Kitchen()
kitchen.set_temperature(180)  # Celsius
kitchen.set_humidity(65)      # Percentage

3. Recipes

Recipes combine multiple ingredients and define how they should be prepared.

from tomatopy import Recipe

# Create a recipe
marinara = Recipe("Classic Marinara")
marinara.add_ingredient(tomato)
marinara.set_cooking_method("simmer")
marinara.set_duration("30m")

Key Concepts

1. Property System

Ingredients have properties that affect their behavior:

• Physical Properties: weight, volume, density

• Chemical Properties: pH, water content, sugar content

• Culinary Properties: ripeness, freshness, texture

# Access and modify properties
print(tomato.properties["water_content"])  # 0.95
tomato.properties["ripeness"] = 0.9

2. Cooking Operations

Cooking operations transform ingredients through various methods:

• Heat Application: simmering, boiling, roasting

• Mechanical Action: chopping, blending, kneading

• Chemical Changes: fermentation, curing

# Perform cooking operations
sauce = kitchen.cook(
    tomato,
    method="simmer",
    temperature=100,
    duration="30m"
)

3. State Management

Ingredients maintain state throughout cooking operations:

# Check ingredient state
print(tomato.state)  # "raw"
sauce = kitchen.cook(tomato, method="simmer")
print(sauce.state)   # "cooked"

Advanced Concepts

1. Flavor Profiles

Ingredients and cooked products have flavor profiles:

from tomatopy import TasteTester

tester = TasteTester()
profile = tester.analyze(sauce)

# Access flavor components
print(profile.acidity)     # 0.7
print(profile.sweetness)   # 0.3
print(profile.umami)       # 0.8

2. Unit Conversion

TomatoPy handles unit conversions automatically:

# Convert between units
tomato.convert_to_imperial()  # Converts metric to imperial
sauce.convert_volume("ml", "cups")  # Converts between volume units

3. Error Handling

The library includes robust error handling:

try:
    kitchen.cook(tomato, temperature=1000)  # Too hot!
except TemperatureError as e:
    print(f"Error: {e}")  # "Temperature exceeds safe cooking range"

Best Practices

1. Always Use Virtual Environments

   python -m venv tomatopy-env
   source tomatopy-env/bin/activate  # or `tomatopy-env\Scripts\activate` on Windows

2. Check Ingredient Properties Before Cooking

   if tomato.properties["ripeness"] < 0.5:
       print("Warning: Tomato may be too unripe for optimal results")

3. Use Type Hints for Better Code

   from typing import Dict, Any
   
   def create_ingredient(name: str, properties: Dict[str, Any]) -> Ingredient:
       return Ingredient(name=name, properties=properties)

Next Steps

• Core Modules - Dive deeper into specific modules

• Tutorials - Follow step-by-step guides

• API Reference - Explore the full API documentation