ytmusicapi.auth.oauth package

Submodules

ytmusicapi.auth.oauth.credentials module

class ytmusicapi.auth.oauth.credentials.Credentials(client_id: str, client_secret: str) → None

Bases: ABC

Base class representation of YouTubeMusicAPI OAuth Credentials

client_id: str
client_secret: str
abstract get_code() → collections.abc.Mapping

Method for obtaining a new user auth code. First step of token creation.

Return type:

Mapping

abstract refresh_token(refresh_token: str) → ytmusicapi.auth.oauth.models.BaseTokenDict

Method for requesting a new access token for a given refresh_token. Token must have been created by the same OAuth client.

Return type:

BaseTokenDict

abstract token_from_code(device_code: str) → ytmusicapi.auth.oauth.models.RefreshableTokenDict

Method for verifying user auth code and conversion into a FullTokenDict.

Return type:

RefreshableTokenDict

class ytmusicapi.auth.oauth.credentials.OAuthCredentials(client_id: str, client_secret: str, session: requests.sessions.Session | None = None, proxies: dict | None = None)

Bases: Credentials

Class for handling OAuth credential retrieval and refreshing.

client_id: str
client_secret: str
get_code() → ytmusicapi.auth.oauth.models.AuthCodeDict

Method for obtaining a new user auth code. First step of token creation.

Return type:

AuthCodeDict

refresh_token(refresh_token: str) → ytmusicapi.auth.oauth.models.BaseTokenDict

Method for requesting a new access token for a given refresh_token. Token must have been created by the same OAuth client.

Parameters:

refresh_token (str) – Corresponding refresh_token for a matching access_token. Obtained via

Return type:

BaseTokenDict

token_from_code(device_code: str) → ytmusicapi.auth.oauth.models.RefreshableTokenDict

Method for verifying user auth code and conversion into a FullTokenDict.

Return type:

RefreshableTokenDict

ytmusicapi.auth.oauth.exceptions module

exception ytmusicapi.auth.oauth.exceptions.BadOAuthClient

Bases: Exception

OAuth client request failure. Ensure provided client_id and secret are correct and YouTubeData API is enabled.

exception ytmusicapi.auth.oauth.exceptions.UnauthorizedOAuthClient

Bases: Exception

OAuth client lacks permissions for specified token. Token can only be refreshed by OAuth credentials used for its creation.

ytmusicapi.auth.oauth.models module

models for oauth authentication

class ytmusicapi.auth.oauth.models.AuthCodeDict

Bases: TypedDict

Keys for the json object obtained via code response during auth flow.

device_code: str

code obtained via user confirmation and oauth consent

expires_in: int

seconds from original request timestamp

interval: int

(?) “5” (?)

user_code: str

alphanumeric code user is prompted to enter as confirmation. formatted as XXX-XXX-XXX.

verification_url: str

base url for OAuth consent screen for user signin/confirmation

class ytmusicapi.auth.oauth.models.BaseTokenDict

Bases: TypedDict

Limited token. Does not provide a refresh token. Commonly obtained via a token refresh.

access_token: str

str to be used in Authorization header

expires_in: int

seconds until expiration from request timestamp

scope: Union[str, Literal['https://www.googleapis.com/auth/youtube']]

should be ‘https://www.googleapis.com/auth/youtube’

token_type: Union[str, Literal['Bearer']]

should be ‘Bearer’

class ytmusicapi.auth.oauth.models.RefreshableTokenDict

Bases: dict

Entire token. Including refresh. Obtained through token setup.

access_token: str
expires_at: int

UNIX epoch timestamp in seconds

expires_in: int
refresh_token: str

str used to obtain new access token upon expiration

scope: Union[str, Literal['https://www.googleapis.com/auth/youtube']]
token_type: Union[str, Literal['Bearer']]

ytmusicapi.auth.oauth.token module

class ytmusicapi.auth.oauth.token.OAuthToken(scope: str | Literal['https://www.googleapis.com/auth/youtube'], token_type: str | Literal['Bearer'], access_token: str, refresh_token: str, expires_at: int = 0, expires_in: int = 0) → None

Bases: Token

Wrapper for an OAuth token implementing expiration methods.

classmethod from_json(file_path: pathlib.Path) → ytmusicapi.auth.oauth.token.OAuthToken
Return type:

OAuthToken

property is_expiring: bool
static is_oauth(headers: requests.structures.CaseInsensitiveDict) → bool
Return type:

bool

update(fresh_access: ytmusicapi.auth.oauth.models.BaseTokenDict)

Update access_token and expiration attributes with a BaseTokenDict inplace. expires_at attribute set using current epoch, avoid expiration desync by passing only recently requested tokens dicts or updating values to compensate.

class ytmusicapi.auth.oauth.token.RefreshingToken(scope: str | Literal['https://www.googleapis.com/auth/youtube'], token_type: str | Literal['Bearer'], access_token: str, refresh_token: str, expires_at: int = 0, expires_in: int = 0, credentials: ytmusicapi.auth.oauth.credentials.Credentials | None = None, _local_cache: pathlib.Path | None = None) → None

Bases: OAuthToken

Compositional implementation of Token that automatically refreshes an underlying OAuthToken when required (credential expiration <= 1 min) upon access_token attribute access.

credentials: Optional[Credentials] = None

credentials used for access_token refreshing

property local_cache: Path | None
classmethod prompt_for_token(credentials: ytmusicapi.auth.oauth.credentials.Credentials, open_browser: bool = False, to_file: str | None = None) → ytmusicapi.auth.oauth.token.RefreshingToken

Method for CLI token creation via user inputs.

Parameters:

  • credentials (Credentials) – Client credentials

  • open_browser (bool) – Optional. Open browser to OAuth consent url automatically. (Default: False).

  • to_file (Optional[str]) – Optional. Path to store/sync json version of resulting token. (Default: None).

Return type:

RefreshingToken

store_token(path: str | None = None) → None

Write token values to json file at specified path, defaulting to self.local_cache. Operation does not update instance local_cache attribute. Automatically called when local_cache is set post init.

Return type:

None

class ytmusicapi.auth.oauth.token.Token(scope: str | Literal['https://www.googleapis.com/auth/youtube'], token_type: str | Literal['Bearer'], access_token: str, refresh_token: str, expires_at: int = 0, expires_in: int = 0) → None

Bases: object

Base class representation of the YouTubeMusicAPI OAuth token.

access_token: str
as_auth() → str

Returns Authorization header ready str of token_type and access_token.

Return type:

str

as_dict() → ytmusicapi.auth.oauth.models.RefreshableTokenDict

Returns dictionary containing underlying token values.

Return type:

RefreshableTokenDict

as_json() → str
Return type:

str

expires_at: int = 0
expires_in: int = 0
property is_expiring: bool
static members()
refresh_token: str
scope: Union[str, Literal['https://www.googleapis.com/auth/youtube']]
token_type: Union[str, Literal['Bearer']]

Module contents

class ytmusicapi.auth.oauth.OAuthCredentials(client_id: str, client_secret: str, session: requests.sessions.Session | None = None, proxies: dict | None = None)

Bases: Credentials

Class for handling OAuth credential retrieval and refreshing.

client_id: str
client_secret: str
get_code() → ytmusicapi.auth.oauth.models.AuthCodeDict

Method for obtaining a new user auth code. First step of token creation.

Return type:

AuthCodeDict

refresh_token(refresh_token: str) → ytmusicapi.auth.oauth.models.BaseTokenDict

Method for requesting a new access token for a given refresh_token. Token must have been created by the same OAuth client.

Parameters:

refresh_token (str) – Corresponding refresh_token for a matching access_token. Obtained via

Return type:

BaseTokenDict

token_from_code(device_code: str) → ytmusicapi.auth.oauth.models.RefreshableTokenDict

Method for verifying user auth code and conversion into a FullTokenDict.

Return type:

RefreshableTokenDict

class ytmusicapi.auth.oauth.OAuthToken(scope: str | Literal['https://www.googleapis.com/auth/youtube'], token_type: str | Literal['Bearer'], access_token: str, refresh_token: str, expires_at: int = 0, expires_in: int = 0) → None

Bases: Token

Wrapper for an OAuth token implementing expiration methods.

classmethod from_json(file_path: pathlib.Path) → ytmusicapi.auth.oauth.token.OAuthToken
Return type:

OAuthToken

property is_expiring: bool
static is_oauth(headers: requests.structures.CaseInsensitiveDict) → bool
Return type:

bool

update(fresh_access: ytmusicapi.auth.oauth.models.BaseTokenDict)

Update access_token and expiration attributes with a BaseTokenDict inplace. expires_at attribute set using current epoch, avoid expiration desync by passing only recently requested tokens dicts or updating values to compensate.

class ytmusicapi.auth.oauth.RefreshingToken(scope: str | Literal['https://www.googleapis.com/auth/youtube'], token_type: str | Literal['Bearer'], access_token: str, refresh_token: str, expires_at: int = 0, expires_in: int = 0, credentials: ytmusicapi.auth.oauth.credentials.Credentials | None = None, _local_cache: pathlib.Path | None = None) → None

Bases: OAuthToken

Compositional implementation of Token that automatically refreshes an underlying OAuthToken when required (credential expiration <= 1 min) upon access_token attribute access.

access_token: str
credentials: Optional[Credentials] = None

credentials used for access_token refreshing

property local_cache: Path | None
classmethod prompt_for_token(credentials: ytmusicapi.auth.oauth.credentials.Credentials, open_browser: bool = False, to_file: str | None = None) → ytmusicapi.auth.oauth.token.RefreshingToken

Method for CLI token creation via user inputs.

Parameters:

  • credentials (Credentials) – Client credentials

  • open_browser (bool) – Optional. Open browser to OAuth consent url automatically. (Default: False).

  • to_file (Optional[str]) – Optional. Path to store/sync json version of resulting token. (Default: None).

Return type:

RefreshingToken

refresh_token: str
scope: Union[str, Literal['https://www.googleapis.com/auth/youtube']]
store_token(path: str | None = None) → None

Write token values to json file at specified path, defaulting to self.local_cache. Operation does not update instance local_cache attribute. Automatically called when local_cache is set post init.

Return type:

None

token_type: Union[str, Literal['Bearer']]