spotipie.auth.sessions

This module contains a Session class for each OAuth2 flow. These classes are wrappers for a requests_oauthlib.OAuth2Session.

The hierarchy of the session classes is the following:

• BaseOAuth2Session

  • ImplicitGrantSession

  • RefreshableOAuth2Session

    • ClientCredentialsSession

    • AuthorizationCodeSession

ClientCredentialsSession and AuthorizationCodeSession are refreshable sessions, meaning that once the access token expires, a new one can be obtained automatically. So, if you make a request and your token is expired, a new token is automatically obtained and the request is carried out without problems.

On the other hand, an ImplicitGrantSession is not “refreshable”, at least not in the same sense. When the token expires, the authorization URL must be opened in the browser. Despite that, the user should not need to type anything since the app was already authorized. Still, an interaction with the browser is needed: the new token cannot be obtained totally “behind the scene” (in Python) as in the case of the other two flows. That’s why ImplicitGrantSession has not the auto-refresh feature. Nonetheless, you can still register a listener to the “token_expired” event to handle that.

Classes

AuthorizationCodeSession(client_id, …[, …])	Session for authorization code flow
BaseOAuth2Session(session)	Base class for all session classes.
ClientCredentialsSession(client_id, …[, …])
ImplicitGrantSession(client_id, redirect_uri)	Session following the “implicit grant flow” for authorization
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).

Reference

class spotipie.auth.sessions.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.sessions.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.sessions.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.sessions.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.sessions.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)