spotipie.auth

Substructure

• spotipie.auth.events
• spotipie.auth.sessions
• spotipie.auth.utils

Classes

AuthorizationCodeSession(client_id, …[, …])	Session for authorization code flow
BaseOAuth2Session(session)	Base class for all session classes.
ClientCredentialsSession(client_id, …[, …])
Credentials(client_id, client_secret, …)	Method generated by attrs for class Credentials.
Flow(value)	An enumeration.
ImplicitGrantSession(client_id, redirect_uri)	Session following the “implicit grant flow” for authorization
OAuth2Token(access_token, expires_in, scope)	Method generated by attrs for class OAuth2Token.
RefreshableOAuth2Session(session, …)	Base abstract class for sessions whose token can be refreshed automatically either using a refresh-token (authorization code flow) or not (client credentials flow).

class spotipie.auth.AuthorizationCodeSession(client_id, client_secret, redirect_uri, scope=None, auto_refresh=True, **kwargs)

Bases: spotipie.auth.sessions.RefreshableOAuth2Session

Session for authorization code flow

FLOW: spotipie.auth.sessions.Flow = 'authorization_code'

authorization_url(force_dialog=False, **kwargs)

Generates the URL the user has to visit in order to authorize (the application using) this session. The “state” parameter (useful for security reasons) is automatically generated and included in the URL. This function returns the authorization url and the generated state.

Parameters

• force_dialog (bool) – Whether or not to force the user to approve the app again if they’ve already done so. If false (default), a user who has already approved the application may be automatically redirected to the URI specified by redirect_uri. If True, the user will not be automatically redirected and will have to approve the app again.

• **kwargs – other query arguments to include in the authorization URLs; at the moment of writing this functions, no other parameter exists.

Return type

Tuple[str, str]

Returns

tuple(authorization_url, state)

fetch_token(callback_url, timeout=None)

Extracts the code and the state parameters from the callback URL and, after having checked the correctness of the state, it makes a request to Spotify in order to exchange the authorization code for an access token.

Parameters

• callback_url – the URL Spotify redirects to after the user grants his authorization to your app, i.e. the redirect URI with query arguments “code” and “state” (at least). The function raises an exception if the callback URL contains an “error” argument

• timeout –

Raises

• AccessDenied – if the user decides to not grant access

• AuthorizationException – the callback_url has an error argument different from “access_denied”

• requests.Timeout –

fetch_token_given_code(code, state, timeout=None)

Variant of fetch_token() where you pass the code and state parameters directly rather than a callback URL.

class spotipie.auth.BaseOAuth2Session(session)

Bases: abc.ABC

Base class for all session classes. Please, note that this class is not a subclass of requests.Session. In fact, it is a wrapper of requests_oauthlib.OAuth2Session which is a subclass of requests.Session. You can access the actual session object using the property session.

Properties:

session (requests_oauthlib.OAuth2Session): (get-only) session object token (OAuth2Token): (get/set) token object client_id (str): (get-only) scope (FrozenSet[str]): (get-only)

FLOW: spotipie.auth.sessions.Flow

add_listener(event_name, listener)

Adds a listener for one of the available events (see events).

Parameters

• event_name (str) – either “token_updated” or “token_expired”

• listener (Callable[[SessionEvent], Any]) – a callable taking an event object in input

Return type

None

remove_listener(event_name, listener)

Return type

None

property session: requests.sessions.Session

Returns the requests_oauthlib.OAuth2Session instance wrapped by this object. You should not need to use this. If you do, makes sure your use doesn’t interfere with the behavior of the wrapper.

Return type

Session

property client_id

property is_authorized

property token: spotipie.auth._token.OAuth2Token

Return type

OAuth2Token

set_token(token)

Parameters

token (Union[Dict, OAuth2Token]) – a OAuth2Token or an equivalent dictionary

property scope: Tuple[str]

Return type

Tuple[str]

request(method, url, params=None, data=None, headers=None, withhold_token=False, **kwargs)

Make a request. See requests.Session documentation for the full argument list.

Raises

TokenExpired – if the token is expired and not refreshed/updated automatically or by a listener on the “token_expired” event.

mount(prefix, adapter)

class spotipie.auth.ClientCredentialsSession(client_id, client_secret, auto_refresh=True, **kwargs)

Bases: spotipie.auth.sessions.RefreshableOAuth2Session

FLOW: spotipie.auth.sessions.Flow = 'client_credentials'

fetch_token(timeout=None)

class spotipie.auth.Credentials(client_id, client_secret, redirect_uri)

Bases: object

Method generated by attrs for class Credentials.

client_id: str

client_secret: Optional[str]

redirect_uri: str

staticmethod from_environment(prefix='SPOTIPIE')

Reads Spotify OAuth2 credentials from the following environment variables: {prefix}_CLIENT_ID, {prefix}_CLIENT_SECRET, {prefix}_REDIRECT_URI.

Raises

KeyError – if no variable is defined for client_id and redirect_uri.

Return type

Credentials

class spotipie.auth.Flow(value)

Bases: enum.Enum

An enumeration.

CLIENT_CREDENTIALS = 'client_credentials'

IMPLICIT_GRANT = 'implicit_grant'

AUTHORIZATION_CODE = 'authorization_code'

class spotipie.auth.ImplicitGrantSession(client_id, redirect_uri, scope=None, **kwargs)

Bases: spotipie.auth.sessions.BaseOAuth2Session

Session following the “implicit grant flow” for authorization

FLOW: spotipie.auth.sessions.Flow = 'implicit_grant'

authorization_url(force_dialog=False, **kwargs)

Generates the URL the user has to visit in order to authorize (the application using) this session. The “state” parameter (useful for security reasons) is automatically generated and included in the URL. This function returns the authorization url and the generated state.

Parameters

• force_dialog (bool) – Whether or not to force the user to approve the app again if they’ve already done so. If false (default), a user who has already approved the application may be automatically redirected to the URI specified by redirect_uri. If True, the user will not be automatically redirected and will have to approve the app again.

• **kwargs – other query arguments to include in the authorization URLs; at the moment of writing this functions, no other parameter exists.

Return type

Tuple[str, str]

Returns

tuple(authorization_url, state)

read_token_from_callback_url(callback_url)

Parses the callback URL and grab the token information contained in the fragment of the URL. Sets the token property and returns the token.

Return type

OAuth2Token

class spotipie.auth.RefreshableOAuth2Session(session, client_secret, auto_refresh)

Bases: spotipie.auth.sessions.BaseOAuth2Session, abc.ABC

Base abstract class for sessions whose token can be refreshed automatically either using a refresh-token (authorization code flow) or not (client credentials flow).

property client_secret: str

Return type

str

property auto_refresh: bool

Return type

bool

enable_auto_refresh()

Enable token auto-refresh. Equivalent to session.auto_refresh = True.

Return type

None

disable_auto_refresh()

Disable token auto-refresh. Equivalent to session.auto_refresh = False.

Return type

None

refresh_token()

Obtains a new token, stores it in the session and returns it.

Return type

OAuth2Token

request(method, url, params=None, data=None, headers=None, withhold_token=False, **kwargs)

Make a request. See requests.Session documentation for the full argument list.

Raises

TokenExpired – if the token is expired and not refreshed/updated automatically or by a listener on the “token_expired” event.

FLOW: spotipie.auth.sessions.Flow

class spotipie.auth.OAuth2Token(access_token, expires_in, scope, state=None, token_type='Bearer', expires_at=None, refresh_token=None)

Bases: object

Method generated by attrs for class OAuth2Token.

access_token: str

expires_in: int

scope: Tuple[str, ...]

state: Optional[str]

token_type: str

expires_at: Optional[float]

refresh_token: Optional[str]

staticmethod from_dict(data, ignore_unknown_keys=False)

Return type

OAuth2Token

staticmethod from_json_string(string)

staticmethod from_json(path)

to_dict()

Return type

Dict[str, Any]

to_json_string()

to_json(path)

is_expired(margin=2)

Return type

bool