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

   abstractmethod get_code() -> AuthCodeDict

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

      Return type:
         "AuthCodeDict"

   abstractmethod refresh_token(refresh_token: str) -> 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"

   abstractmethod token_from_code(device_code: str) -> 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: Session | None = None, proxies: dict[str, str] | None = None)

   Bases: "Credentials"

   Class for handling OAuth credential retrieval and refreshing.

   client_id: str

   client_secret: str

   get_code() -> AuthCodeDict

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

      Return type:
         "AuthCodeDict"

   refresh_token(refresh_token: str) -> 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) -> 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: str | Literal['https://www.googleapis.com/auth/youtube']

      should be 'https://www.googleapis.com/auth/youtube'

   token_type: str | Literal['Bearer']

      should be 'Bearer'

class ytmusicapi.auth.oauth.models.RefreshableTokenDict

   Bases: "BaseTokenDict"

   Entire token. Including refresh. Obtained through token setup.

   expires_at: int

      UNIX epoch timestamp in seconds

   refresh_token: str

      str used to obtain new access token upon expiration

   refresh_token_expires_in: int

      seconds until refresh token expiration from request timestamp


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: Path) -> OAuthToken

      Return type:
         "OAuthToken"

   property is_expiring: bool

   static is_oauth(headers: CaseInsensitiveDict[str]) -> bool

      Return type:
         "bool"

   update(fresh_access: BaseTokenDict) -> None

      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.

      Return type:
         "None"

class ytmusicapi.auth.oauth.token.RefreshingToken(credentials: Credentials, _local_cache: Path | None = None, *, 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: "OAuthToken"

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

   credentials: Credentials

      credentials used for access_token refreshing

   property local_cache: Path | None

   classmethod prompt_for_token(credentials: OAuthCredentials, open_browser: bool = False, to_file: str | None = None) -> RefreshingToken

      Method for CLI token creation via user inputs.

      Parameters:
         * **credentials** ("OAuthCredentials") -- Client credentials

         * **open_browser** ("bool") -- Optional. Open browser to
           OAuth consent url automatically. (Default: "False").

         * **to_file** ("str" | "None") -- 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() -> 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() -> KeysView[str]

      Return type:
         "KeysView"["str"]

   refresh_token: str

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

   token_type: str | Literal['Bearer']


Module contents
===============

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

   Bases: "Credentials"

   Class for handling OAuth credential retrieval and refreshing.

   client_id: str

   client_secret: str

   get_code() -> AuthCodeDict

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

      Return type:
         "AuthCodeDict"

   refresh_token(refresh_token: str) -> 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) -> 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: Path) -> OAuthToken

      Return type:
         "OAuthToken"

   property is_expiring: bool

   static is_oauth(headers: CaseInsensitiveDict[str]) -> bool

      Return type:
         "bool"

   update(fresh_access: BaseTokenDict) -> None

      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.

      Return type:
         "None"

class ytmusicapi.auth.oauth.RefreshingToken(credentials: Credentials, _local_cache: Path | None = None, *, 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: "OAuthToken"

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

   credentials: Credentials

      credentials used for access_token refreshing

   property local_cache: Path | None

   classmethod prompt_for_token(credentials: OAuthCredentials, open_browser: bool = False, to_file: str | None = None) -> RefreshingToken

      Method for CLI token creation via user inputs.

      Parameters:
         * **credentials** ("OAuthCredentials") -- Client credentials

         * **open_browser** ("bool") -- Optional. Open browser to
           OAuth consent url automatically. (Default: "False").

         * **to_file** ("str" | "None") -- 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"
