Session and token storage#

Token storage: where a saved login lives.

A session is the (access token, refresh token, user, country, issuing client) tuple Tidal’s device flow yields. The default FileTokenStore is a single JSON file with mode 0600; hosts (Django) may supply any object implementing TokenStore (e.g. DB-backed or encrypted-at-rest) — the rest of the library only talks to the protocol.

Compatibility: files written by Tidal-Media-Downloader (~/.tidal-dl.token.json) are base64-wrapped JSON with the same field names; FileTokenStore reads them transparently and rewrites them in the plain-JSON format on first save.

class tidalpy.session.FileTokenStore(path=None)[source]#

Bases: object

JSON-file token store with atomic writes and legacy format support.

Parameters:

path (str | Path | None)

__init__(path=None)[source]#
Parameters:

path (str | Path | None)

Return type:

None

clear()[source]#
Return type:

None

load()[source]#
Return type:

TokenRecord | None

save(record)[source]#
Parameters:

record (TokenRecord)

Return type:

None

class tidalpy.session.TokenRecord(user_id=None, country_code=None, access_token=None, refresh_token=None, expires_after=0.0, client_id=None, updated_at=<factory>)[source]#

Bases: object

A saved login, bound to the OAuth client that issued it.

Parameters:

  • user_id (int | str | None)

  • country_code (str | None)

  • access_token (str | None)

  • refresh_token (str | None)

  • expires_after (float)

  • client_id (str | None)

  • updated_at (float)

classmethod from_dict(data)[source]#
Parameters:

data (dict[str, Any])

Return type:

TokenRecord

__init__(user_id=None, country_code=None, access_token=None, refresh_token=None, expires_after=0.0, client_id=None, updated_at=<factory>)#
Parameters:

  • user_id (int | str | None)

  • country_code (str | None)

  • access_token (str | None)

  • refresh_token (str | None)

  • expires_after (float)

  • client_id (str | None)

  • updated_at (float)

Return type:

None

matches_client(client_id)[source]#

A Bearer token is only valid for its issuing client.

Parameters:

client_id (str | None)

Return type:

bool

to_dict()[source]#
Return type:

dict[str, Any]

access_token: str | None = None#
client_id: str | None = None#
country_code: str | None = None#
property expired: bool#
expires_after: float = 0.0#
property present: bool#
refresh_token: str | None = None#
updated_at: float#
user_id: int | str | None = None#
class tidalpy.session.TokenStore(*args, **kwargs)[source]#

Bases: Protocol

Storage a TidalClient reads and writes.

__init__(*args, **kwargs)#
clear()[source]#

Forget the saved session.

Return type:

None

load()[source]#

Current saved session, or None when absent/unreadable.

Return type:

TokenRecord | None

save(record)[source]#

Persist record (must be durable and atomic enough).

Parameters:

record (TokenRecord)

Return type:

None