Migrating to v3

What changed in v3

Methods on the namespaced Fatsecret surface (fs.foods.*, fs.recipes.*, fs.diary.*, fs.profile.*, fs.weight.*, fs.exercises.*) that previously returned dict[str, Any] or list[dict[str, Any]] now return typed Pydantic v2 models — Food, Recipe, Profile, FoodEntry, ExerciseEntry, Exercise, Day and friends. The wire-level behavior is unchanged; only the in-Python return shape is new. pydantic>=2.7 is now a base dependency.

Quick fix for most callers

Replace square-bracket dict access with dotted attribute access:

# v2
food["food_id"]
food["food_name"]

# v3
food.food_id
food.food_name

If you have a downstream consumer that genuinely needs the dict shape (JSON serialization, a templating layer, an existing dict-typed signature you can’t change today) call .to_dict() on the model. That’s the one-line escape hatch:

payload_for_legacy_consumer = food.to_dict()

.to_dict() is model.model_dump(mode="json") under the hood, so Decimal values come back as JSON-safe strings — same shape your v2 code was already handling off the wire.

Side-by-side examples

Single food lookup

food = fs.foods.get_v1(food_id=12345)

# v2
food["food_name"]
food["food_type"]
food["servings"]["serving"][0]["calories"]

# v3
food.food_name                            # str
food.food_type                            # Literal["Brand", "Generic"]
food.servings.serving[0].calories         # Decimal

Food search

search_v1 returns a list of typed Food objects directly (the wrapping foods/results envelope is unwrapped for you):

foods = fs.foods.search_v1(search_expression="banana")

# v2
for entry in foods:
    print(entry["food_id"], entry["food_name"])

# v3
for entry in foods:
    print(entry.food_id, entry.food_name)   # int, str

Diary entries

import datetime
today = datetime.date.today()
entries = fs.diary.entries_get_v2(date=today)   # list[FoodEntry]

# v2
for e in entries:
    print(e["meal"], e["calories"], e["protein"])

# v3
for e in entries:
    print(e.meal, e.calories, e.protein)
    # e.meal     -> Literal["Breakfast", "Lunch", "Dinner", "Other"]
    # e.calories -> Decimal (not float!)
    # e.protein  -> Decimal

Recipe lookup

recipe = fs.recipes.get_v1(recipe_id=88339)   # Recipe

# v2
recipe["recipe_name"]
recipe["recipe_nutrition"]["calories"]

# v3
recipe.recipe_name                            # str
recipe.recipe_nutrition.calories              # Decimal

(Recipe is a friendly alias for the XSD-derived RecipesRecipe class. Either name imports the same model.)

User profile

profile = fs.profile.get_v1()   # Profile

# v2
profile["last_weight_kg"]
profile["weight_measure"]

# v3
profile.last_weight_kg                        # Optional[Decimal]
profile.weight_measure                        # Optional[Literal["Kg", "Lb"]]

Resources that still return dict

Four resource families intentionally kept their dict return shape because the upstream XSD doesn’t model them. Nothing changed for callers of these:

• Food Classification (fs.classification.*) — brands, categories, sub-categories.

• Saved Meals (fs.meals.*) — saved meal CRUD and items.

• Native APIs (fs.native.*) — image recognition, NLP.

• Feedback (fs.feedback.*) — feedback submission.

If we get an XSD (or a stable enough HTML overlay) for any of these in the future they’ll be promoted to typed models in a minor release. The dict shape is the migration path; we won’t reshape it.

Mutators still return bool

Methods that write rather than read return a plain success boolean, not a model. No change from v2:

• fs.weight.update_v1(...) -> bool

• fs.diary.entry_create_v1(...) -> list[FoodEntry] (the resulting entries, typed)

• fs.diary.entry_edit_v1(...) -> bool

• fs.diary.entry_delete_v1(...) -> bool

• fs.recipes.add_favorite_v1(...) -> bool

• fs.recipes.delete_favorite_v1(...) -> bool

Type details worth knowing

Decimal for nutrition macros

Calories, protein, carbs, fat, micronutrients — all Decimal, not float. The XSD says xsd:decimal and we honor it because floating-point rounding in nutrition math compounds quickly across a day’s worth of entries. Two consequences:

• Arithmetic between a Decimal and a float raises TypeError. Use Decimal(str(my_float)) to lift, or convert the model value with float(entry.calories) if you genuinely want lossy float math.

• json.dumps(model) won’t work — Decimal isn’t JSON-serializable by default. Use model.model_dump_json() or json.dumps(model.to_dict()) (to_dict already invokes model_dump(mode="json") which stringifies Decimals).

Literal for closed enums

Where the XSD declares an enum, the field is a Literal[...] — the IDE autocompletes it and a typo lights up under mypy/pyright:

• Food.food_type -> Literal["Brand", "Generic"]

• FoodEntry.meal -> Literal["Breakfast", "Lunch", "Dinner", "Other"]

• Profile.weight_measure -> Optional[Literal["Kg", "Lb"]]

• Profile.height_measure -> Optional[Literal["Cm", "Inch"]]

Ternary for FatSecret’s tri-state booleans

A handful of fields (Allergen.value, Preference.value) use FatSecret’s quirky three-valued truthiness:

Ternary = Literal[-1, 0, 1, "Unknown", "True", "False"]

Both numeric and string forms are accepted because the upstream API emits both depending on the endpoint version. Don’t compare with is True / is False — use == "True" / == 1 or, more defensively, normalize via a small helper.

extra="allow" — schema drift is non-fatal

Every model is configured with extra="allow". If FatSecret adds a new field tomorrow that we haven’t regenerated for, the model preserves it (accessible via model.__pydantic_extra__) instead of rejecting the response. Drift is detected by CI’s oas-regen-check, not by runtime validation failures — your production code keeps working.

The .to_dict() migration helper

Every model inherits a .to_dict() method that returns the v2 dict shape:

food = fs.foods.get_v1(food_id=12345)
legacy_shape = food.to_dict()   # {"food_id": "12345", "food_name": "...", ...}

Use it as a per-call escape hatch when migrating a large codebase incrementally. Decimal becomes a string (mode="json"), matching what v2 callers were already getting off the wire.

Frequently broken patterns

Iterating like a dict

# v2 — works on dicts
for k, v in food.items():
    ...

# v3 — Pydantic models aren't dicts
for k, v in food.model_dump().items():
    ...

JSON-serializing a model

# v2
json.dumps(food)

# v3 — pick one
food.model_dump_json()              # returns a JSON string directly
json.dumps(food.to_dict())          # round-trips through the dict shape

.get() with a default

# v2
brand = food.get("brand_name", "Unknown")

# v3 — use getattr or check Optional
brand = food.brand_name or "Unknown"
# or, if the field could be missing on a model with extra="allow":
brand = getattr(food, "brand_name", None) or "Unknown"

Membership tests

# v2
if "brand_name" in food:
    ...

# v3
if food.brand_name is not None:
    ...

Why typed models?

• IDE autocompletion. food.<TAB> lists every field with its type. No more guessing whether the key is food_name or foodName or name.

• Real types. food.food_id is int, not str; serving.calories is Decimal, not whatever the wire happened to send. Pydantic coerces both directions, so legacy fixtures that serialized integers as strings still validate.

• Runtime validation catches schema drift. When FatSecret changes an XSD-typed field’s shape (rename, type change), validation fails loudly at the call site instead of silently propagating malformed data into your business logic.

• Closed enums document themselves. Literal["Brand", "Generic"] is the spec — your type checker will tell you if you compare against the wrong string.