Protocol Module#

This module contains only one class. This class handles interactions with the Strava V3 API including steps in the authentication process.

Protocol#

Low-level classes for interacting directly with the Strava API webservers.

class stravalib.protocol.AccessInfo[source]#

Bases: TypedDict

Dictionary containing token exchange response from Strava.

access_token: str#

A short live token the access Strava API

clear() → None.  Remove all items from D.#
copy() → a shallow copy of D#
expires_at: int#

The number of seconds since the epoch when the provided access token will expire

classmethod fromkeys(iterable, value=None, /)#

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)#

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items#
keys() → a set-like object providing a view on D's keys#
pop(k[, d]) → v, remove specified key and return the corresponding value.#

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()#

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

refresh_token: str#

The refresh token for this user, to be used to get the next access token for this user. Please expect that this value can change anytime you retrieve a new access token. Once a new refresh token code has been returned, the older code will no longer work.

setdefault(key, default=None, /)#

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from mapping/iterable E and F.#

If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values#
class stravalib.protocol.ApiV3(access_token: str | None = None, requests_session: Session | None = None, rate_limiter: Callable[[dict[str, str], Literal['GET', 'POST', 'PUT', 'DELETE']], None] | None = None, token_expires: int | None = None, refresh_token: str | None = None, client_id: int | None = None, client_secret: str | None = None)[source]#

Bases: object

This class is responsible for performing the HTTP requests, rate limiting, and error handling.

access_token: str | None#
api_base = '/api/v3'#
authorization_url(client_id: int, redirect_uri: str, approval_prompt: Literal['auto', 'force'] = 'auto', scope: list[Literal['read', 'read_all', 'profile:read_all', 'profile:write', 'activity:read', 'activity:read_all', 'activity:write']] | Literal['read', 'read_all', 'profile:read_all', 'profile:write', 'activity:read', 'activity:read_all', 'activity:write'] | None = None, state: str | None = None) → str[source]#

Get the URL needed to authorize your application to access a Strava user’s information.

See https://developers.strava.com/docs/authentication/

Parameters:

  • client_id (int) – The numeric developer client id.

  • redirect_uri (str) – The URL that Strava will redirect to after successful (or failed) authorization.

  • approval_prompt (str) – Whether to prompt for approval even if approval already granted to app. Choices are ‘auto’ or ‘force’. (Default is ‘auto’)

  • scope (list[str]) – The access scope required. Omit to imply “read” and “activity:read” Valid values are ‘read’, ‘read_all’, ‘profile:read_all’, ‘profile:write’, ‘activity:read’, ‘activity:read_all’, ‘activity:write’.

  • state (str) – An arbitrary variable that will be returned to your application in the redirect URI.

Returns:

The URL to use for authorization link.

Return type:

str

client_id: int | None#
client_secret: str | None#
delete(url: str, check_for_errors: bool = True, **kwargs: Any) → Any[source]#

Performs a generic DELETE request for specified params, returning the response.

Parameters:

  • url (str) – String representing url to access.

  • check_for_errors (bool) – Whether to raise an error (or not)

Return type:

Deletes specified current online content.

exchange_code_for_token(client_id: int, client_secret: str, code: str, return_athlete: bool = False) → tuple[AccessInfo, dict[str, Any] | None][source]#

Exchange the temporary authorization code (returned with redirect from Strava authorization URL) for a short-lived access token and a refresh token (used to obtain the next access token later on).

Parameters:

  • client_id (int) – The numeric developer client id.

  • client_secret (str) – The developer client secret

  • code (str) – The temporary authorization code

  • return_athlete (bool (optional, default=False)) – Whether to return the SummaryAthlete object with the token response. This behavior is currently undocumented and could change at any time. Default is False.

Returns:

Dictionary containing the access_token, refresh_token and expires_at (number of seconds since Epoch when the provided access token will expire)

Return type:

dict

get(url: str, check_for_errors: bool = True, **kwargs: Any) → Any[source]#

Performs a generic GET request for specified params, returning the response.

Parameters:

  • url (str) – String representing the url to retrieve

  • check-for_errors (bool (default = True)) – Flag used to raise an error (or not)

Returns:

Performs the request and returns a JSON object deserialized as dict

Return type:

dict

post(url: str, files: dict[str, SupportsRead[str | bytes]] | None = None, check_for_errors: bool = True, **kwargs: Any) → Any[source]#

Performs a generic POST request for specified params, returning the response.

Parameters:

  • url (str) – Url string to be requested.

  • files (dict) – Dictionary of file name to file-like objects. Used by _requests

  • check_for_errors (bool) – Whether to raise an error (or not)

Return type:

Deserialized request output.

put(url: str, check_for_errors: bool = True, body: dict[str, Any] | None = None, **kwargs: Any) → Any[source]#

Performs a generic PUT request for specified params, returning the response.

Parameters:

  • url (str) – String representing url to access.

  • check_for_errors (bool) – Whether to raise an error (or not)

  • body (dict, optional) – Data to send as a JSON-encoded request body. Remaining keyword arguments are used to format the URL and are sent as query-string parameters.

Return type:

Replaces current online content with new content.

refresh_access_token(client_id: int, client_secret: str, refresh_token: str) → AccessInfo[source]#

Exchanges the previous refresh token for a short-lived access token and a new refresh token (used to obtain the next access token later on)

Parameters:

  • client_id (int) – The numeric developer client id.

  • client_secret (str) – The developer client secret

  • refresh_token (str) – The refresh token obtain from a previous authorization request

Returns:

Dictionary containing the access_token, refresh_token and expires_at (number of seconds since Epoch when the provided access token will expire)

Return type:

dict

Notes

This method is user facing. Here, we don’t populate client_id and client_secret from self; A user can call this method and refresh the token manually with those values.

refresh_expired_token() → None[source]#

Checks to see if a token has expired and auto refreshes it if the user has setup their environment with the client secret information.

Returns:

If all is setup properly, updates and resets the access_token attribute. Otherwise it logs a warning

Return type:

None

refresh_token: str | None#
resolve_url(url: str) → str[source]#
Parameters:

url (str) – url string to be be accessed / resolved

Returns:

A string representing the full properly formatted (https) url.

Return type:

str

rsession: Session#
server = 'www.strava.com'#
token_expires: int | None#