spotipie.auth

Substructure

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, …)

Flow

An enumeration.

ImplicitGrantSession(client_id, redirect_uri)

Session following the “implicit grant flow” for authorization

OAuth2Token(access_token, expires_in, scope)

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.OAuth2Token(access_token, expires_in, scope, state=None, token_type='Bearer', expires_at=None, refresh_token=None)[source]

Bases: object

access_token: str = None
expires_in: int = None
scope: Tuple[str, ...] = None
state: Optional[str] = None
token_type: str = None
expires_at: Optional[float] = None
refresh_token: Optional[str] = None
staticmethod from_dict(data, ignore_unknown_keys=False)[source]
Return type

OAuth2Token

staticmethod from_json_string(string)[source]
staticmethod from_json(path)[source]
to_dict()[source]
Return type

Dict[str, Any]

to_json_string()[source]
to_json(path)[source]
is_expired(margin=2)[source]
Return type

bool

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

Bases: spotipie.auth.sessions.RefreshableOAuth2Session

Session for authorization code flow

FLOW: spotipie.auth.sessions.Flow = 'authorization_code'
authorization_url(force_dialog=False, **kwargs)[source]

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)[source]

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)[source]

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

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

auto_refresh
Return type

bool

client_id
client_secret
Return type

str

disable_auto_refresh()

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

Return type

None

enable_auto_refresh()

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

Return type

None

is_authorized
mount(prefix, adapter)
refresh_token()

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

Return type

OAuth2Token

remove_listener(event_name, listener)
Return type

None

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.

scope
Return type

Tuple[str]

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

set_token(token)
Parameters

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

token
Return type

OAuth2Token

class spotipie.auth.BaseOAuth2Session(session)[source]

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: Flow = None
add_listener(event_name, listener)[source]

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)[source]
Return type

None

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

client_id
is_authorized
token
Return type

OAuth2Token

set_token(token)[source]
Parameters

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

scope
Return type

Tuple[str]

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

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)[source]
class spotipie.auth.ClientCredentialsSession(client_id, client_secret, auto_refresh=True, **kwargs)[source]

Bases: spotipie.auth.sessions.RefreshableOAuth2Session

FLOW: spotipie.auth.sessions.Flow = 'client_credentials'
fetch_token(timeout=None)[source]
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

auto_refresh
Return type

bool

client_id
client_secret
Return type

str

disable_auto_refresh()

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

Return type

None

enable_auto_refresh()

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

Return type

None

is_authorized
mount(prefix, adapter)
refresh_token()

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

Return type

OAuth2Token

remove_listener(event_name, listener)
Return type

None

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.

scope
Return type

Tuple[str]

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

set_token(token)
Parameters

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

token
Return type

OAuth2Token

class spotipie.auth.Credentials(client_id, client_secret, redirect_uri)[source]

Bases: object

client_id: str = None
client_secret: Optional[str] = None
redirect_uri: str = None
staticmethod from_environment(prefix='SPOTIPIE')[source]

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[source]

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)[source]

Bases: spotipie.auth.sessions.BaseOAuth2Session

Session following the “implicit grant flow” for authorization

FLOW: spotipie.auth.sessions.Flow = 'implicit_grant'
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

client_id
is_authorized
mount(prefix, adapter)
remove_listener(event_name, listener)
Return type

None

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.

scope
Return type

Tuple[str]

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

set_token(token)
Parameters

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

token
Return type

OAuth2Token

authorization_url(force_dialog=False, **kwargs)[source]

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)[source]

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)[source]

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).

client_secret
Return type

str

auto_refresh
Return type

bool

enable_auto_refresh()[source]

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

Return type

None

disable_auto_refresh()[source]

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

Return type

None

refresh_token()[source]

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)[source]

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 = None
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

client_id
is_authorized
mount(prefix, adapter)
remove_listener(event_name, listener)
Return type

None

scope
Return type

Tuple[str]

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

set_token(token)
Parameters

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

token
Return type

OAuth2Token