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

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.

expires_at: int#: The number of seconds since the epoch when the provided access token will expire

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

Bases: object

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

server = 'www.strava.com'#

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

exchange_code_for_token(client_id: int, client_secret: str, code: str) → AccessInfo[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

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

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

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

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

Return type:

Replaces current online content with new content.

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.