API Documentation

As of v1.0 every endpoint method carries an explicit _vN suffix matching the upstream API version (e.g. foods_search_v5, food_get_v5, recipes_search_v3). The unsuffixed legacy names (foods_search, food_get, …) remain available as deprecated aliases for the v1.x line and emit DeprecationWarning when called. To surface those warnings during development, run Python with:

python -W default::DeprecationWarning:fatsecret

class Fatsecret(consumer_key: str, consumer_secret: str, session_token: Tuple[str, str] | None = None, auth: Literal['oauth1', 'oauth2'] = 'oauth1', scopes: List[str] | None = None)

Core FatSecret API client logic (auth, request handling, utilities).

authenticate(verifier: str | int) → Tuple[str, str]

Exchange the verifier (PIN or callback code) for permanent access tokens.

Args:

verifier: PIN displayed to user or returned via callback.

Returns:

(access_token, access_secret)

close() → None

Close the current HTTP session.

fatsecret_authenticate(password: str, consumer_key: str, consumer_secret: str)

Authenticate a user programmatically using credentials and return an authorized Fatsecret instance.

Note: This uses HTML form emulation against FatSecret’s login flow and may break if the website changes. It is provided for convenience and developer testing, not production OAuth flows.

get_authorize_url(callback_url: str = 'oob') → str

Fetch an OAuth1 request token and return the user-facing authorize URL.

Args:

callback_url: Absolute URL to redirect the user to after they authorize,

or "oob" (out-of-band) to receive a verifier PIN.

Returns:

The authorize URL with the freshly minted oauth_token appended.

static unix_time(dt: datetime) → int

Convert a datetime to number of days since the Epoch (FatSecret style).

static unix_time_v2(dt: datetime | date | int | float) → int

Convert datetime/date/timestamp into number of days since 1970-01-01.

static valid_response(response: Response)

Validate a JSON API response and extract its data or raise an error.