Session

Session object

class proton.session.Session(appversion: str = 'Other', user_agent: str = 'None')
__init__(appversion: str = 'Other', user_agent: str = 'None')

Get a session towards the Proton API.

Parameters:
  • appversion (str, optional) – version for the new Session object, defaults to "Other"

  • user_agent (str, optional) –

    user agent to use, defaults to "None". It should be of the following syntax:

    • Linux based -> ClientName/client.version (Linux; Distro/distro_version)

    • Non-linux based -> ClientName/client.version (OS)

async async_api_request(endpoint, jsondata=None, data=None, additional_headers=None, method=None, params=None, no_condition_check=False)

Do an API request.

This call can return any of the exceptions defined in proton.session.exceptions.

Parameters:
  • endpoint (str) – API endpoint

  • jsondata (dict) – JSON serializable dict to send as request data

  • data (FormData) – data to be sent as either multipart/form-data or application/x-www-form-urlencoded. multipart/form-data is used when required, for example if data includes fields with a file-like value (i.e. is an instance of io.IOBase).

  • additional_headers (dict) – additional headers to send

  • method (str) – HTTP method (get|post|put|delete|patch)

  • params (str, dict or iterable) – URL parameters to append to the URL. If a dictionary or list of tuples [(key, value)] is provided, form-encoding will take place.

  • no_condition_check (bool, optional) – Internal flag to disable locking, defaults to False

Returns:

Deserialized JSON reply

Return type:

dict

async async_authenticate(username: str, password: str, client_secret: str = None, no_condition_check: bool = False, additional_headers=None) bool

Authenticate against Proton API

Parameters:
  • username (str) – Proton account username

  • password (str) – Proton account password

  • client_secret (str, optional) – Client Secret for SRP

  • no_condition_check (bool, optional) – Internal flag to disable locking, defaults to False

  • additional_headers (dict) – additional headers to send

Returns:

True if authentication succeeded, False otherwise.

Return type:

bool

async async_provide_2fa(code: str, no_condition_check=False, additional_headers=None) bool

Provide Two Factor Authentication Code to the API.

Parameters:
  • code (str) – 2FA code

  • no_condition_check (bool, optional) – Internal flag to disable locking, defaults to False

Returns:

True if 2FA succeeded, False otherwise.

Return type:

bool

Raises:

ProtonAPIAuthenticationNeeded – if 2FA failed, and the session was reset by the API backend (this is normally the case)

async async_refresh(only_when_refresh_revision_is=None, no_condition_check=False, additional_headers=None)

Refresh tokens.

Refresh AccessToken with a valid RefreshToken. If the RefreshToken is invalid then the user will have to re-authenticate.

Returns:

True if refresh succeeded, False otherwise (doesn’t throw an exception)

Return type:

bool

async async_logout(no_condition_check=False, additional_headers=None)

Logout from API.

Returns:

True if logout was successful (or nothing was done)

Return type:

bool

async async_lock(no_condition_check=False, additional_headers=None)

Lock the current user (remove PASSWORD and LOCKED scopes)

async async_human_verif_request_code(address=None, phone=None, additional_headers=None)

Request a verification code. Either address (email address) or phone (phone number) should be specified.

async async_human_verif_provide_token(method, token)
api_request(**kw)

Synchronous wrapper for async_api_request()

authenticate(**kw)

Synchronous wrapper for async_authenticate()

provide_2fa(**kw)

Synchronous wrapper for async_provide_2fa()

logout(**kw)

Synchronous wrapper for async_logout()

refresh(**kw)

Synchronous wrapper for async_refresh()

lock(**kw)

Synchronous wrapper for async_lock()

human_verif_request_code(**kw)

Synchronous wrapper for async_human_verif_request_code()

human_verif_provide_token(**kw)

Synchronous wrapper for async_human_verif_provide_token()

register_persistence_observer(observer: object)

Register an observer that will be notified of any persistent state change of the session

Parameters:

observer (object) –

Observer to register. It has to provide the following interface (see proton.sso.ProtonSSO for an actual implementation):

  • _acquire_session_lock(account_name : str, session_data : dict)

  • _release_session_lock(account_name : str, new_session_data : dict)

property transport_factory

Set/read the factory used for transports (i.e. how to reach the API).

If the property is set to a class, it will be wrapped in a factory.

If the property is set to None, then the default transport will be obtained from Loader.

property appversion: str
Returns:

The appversion defined at construction (used for creating requests by transports)

Return type:

str

property user_agent: str
Returns:

The user_agent defined at construction (used for creating requests by transports)

Return type:

str

property authenticated: bool
Returns:

True if session is authenticated, False otherwise.

Return type:

bool

property UID: str | None
Returns:

the session UID, None if not authenticated

Return type:

str, optional

property Scopes: list[str] | None
Returns:

list of scopes of the current session, None if unknown or not defined.

Return type:

list[str], optional

property AccountName: str
Returns:

session account name (mostly used for SSO)

Return type:

str

property AccessToken: str
Returns:

return the access token for API calls (used by transports)

Return type:

str

property needs_twofa: bool
Returns:

True if a 2FA authentication is needed, False otherwise.

Return type:

bool

property environment

Get/set the environment in use for that session. It can be only set once at the beginning of the session’s object lifetime, as changing the environment can lead to security hole.

If the new value is:

  • None: do nothing

  • a string: will use Loader.get("environment", newvalue)() to get the actual class.

  • an environment: use it

Exceptions

Copyright (c) 2023 Proton AG

This file is part of Proton.

Proton is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Proton is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with ProtonVPN. If not, see <https://www.gnu.org/licenses/>.

exception proton.session.exceptions.ProtonError(message, additional_context=None)

Base class for Proton API specific exceptions

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception proton.session.exceptions.ProtonCryptoError(message, additional_context=None)

Exception thrown when something is wrong on the crypto side. In general this has to be handled as being fatal, as something is super-wrong.

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception proton.session.exceptions.ProtonUnsupportedAuthVersionError(message, additional_context=None)

When the auth_version returned by the API is lower then what is currently supported. This is usually fixed with a login via the webclient.

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception proton.session.exceptions.ProtonAPIError(http_code, http_headers, json_data)

Exception that is raised whenever the API call didn’t return a 1000/1001 code. Logic for handling these depend on the call (see API doc)

property http_code: int
Returns:

HTTP error code (401, 403, 422…)

Return type:

int

property http_headers: dict
Returns:

Dictionary of HTTP headers of the error reply

Return type:

dict

property json_data: dict
Returns:

JSON data of the error reply

Return type:

dict

property body_code: int
Returns:

Body error code (“Code” in JSON)

Return type:

int

property error: str
Returns:

Body error message (“Error” in JSON)

Return type:

str

classmethod from_proton_api_error(e: ProtonAPIError)

Construct an instance of this class, based on a ProtonAPIError (this allows to downcast to a more specific exception)

Parameters:

e (ProtonAPIError) – Initial API exception

Returns:

An instance of the current class

Return type:

Any

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception proton.session.exceptions.ProtonAPINotReachable(message, additional_context=None)

Exception thrown when the transport couldn’t reach the API.

One may try using a different transport, or later if the error is transient.

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception proton.session.exceptions.ProtonAPINotAvailable(message, additional_context=None)

Exception thrown when the API is reachable (i.e. at the TLS level), but doesn’t work.

This is definitive for that transport, it will not work by retrying in the same conditions.

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception proton.session.exceptions.ProtonAPIUnexpectedError(message, additional_context=None)

Something went wrong, but we don’t know how to handle it. Good luck :-)

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception proton.session.exceptions.ProtonAPIAuthenticationNeeded(http_code, http_headers, json_data)

We tried to call a route that requires authentication, but we don’t have it.

This should be solved by calling session.authenticate() with valid credentials

add_note()

Exception.add_note(note) – add a note to the exception

property body_code: int
Returns:

Body error code (“Code” in JSON)

Return type:

int

property error: str
Returns:

Body error message (“Error” in JSON)

Return type:

str

classmethod from_proton_api_error(e: ProtonAPIError)

Construct an instance of this class, based on a ProtonAPIError (this allows to downcast to a more specific exception)

Parameters:

e (ProtonAPIError) – Initial API exception

Returns:

An instance of the current class

Return type:

Any

property http_code: int
Returns:

HTTP error code (401, 403, 422…)

Return type:

int

property http_headers: dict
Returns:

Dictionary of HTTP headers of the error reply

Return type:

dict

property json_data: dict
Returns:

JSON data of the error reply

Return type:

dict

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception proton.session.exceptions.ProtonAPI2FANeeded(http_code, http_headers, json_data)

We need 2FA authentication, but it’s not done yet.

This should be solved by calling session.provide_2fa() with valid 2FA

add_note()

Exception.add_note(note) – add a note to the exception

property body_code: int
Returns:

Body error code (“Code” in JSON)

Return type:

int

property error: str
Returns:

Body error message (“Error” in JSON)

Return type:

str

classmethod from_proton_api_error(e: ProtonAPIError)

Construct an instance of this class, based on a ProtonAPIError (this allows to downcast to a more specific exception)

Parameters:

e (ProtonAPIError) – Initial API exception

Returns:

An instance of the current class

Return type:

Any

property http_code: int
Returns:

HTTP error code (401, 403, 422…)

Return type:

int

property http_headers: dict
Returns:

Dictionary of HTTP headers of the error reply

Return type:

dict

property json_data: dict
Returns:

JSON data of the error reply

Return type:

dict

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception proton.session.exceptions.ProtonAPIMissingScopeError(http_code, http_headers, json_data)

We don’t have a required scope.

This might be because of user rights, but also might require a call to unlock.

add_note()

Exception.add_note(note) – add a note to the exception

property body_code: int
Returns:

Body error code (“Code” in JSON)

Return type:

int

property error: str
Returns:

Body error message (“Error” in JSON)

Return type:

str

classmethod from_proton_api_error(e: ProtonAPIError)

Construct an instance of this class, based on a ProtonAPIError (this allows to downcast to a more specific exception)

Parameters:

e (ProtonAPIError) – Initial API exception

Returns:

An instance of the current class

Return type:

Any

property http_code: int
Returns:

HTTP error code (401, 403, 422…)

Return type:

int

property http_headers: dict
Returns:

Dictionary of HTTP headers of the error reply

Return type:

dict

property json_data: dict
Returns:

JSON data of the error reply

Return type:

dict

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception proton.session.exceptions.ProtonAPIHumanVerificationNeeded(http_code, http_headers, json_data)

Human verification is needed for this API call to succeed.

property HumanVerificationToken: str | None

Get the Token for human verification

property HumanVerificationMethods: list[str]

Return a list of allowed human verification methods.

Returns:

human verification methods

Return type:

list[str]

add_note()

Exception.add_note(note) – add a note to the exception

property body_code: int
Returns:

Body error code (“Code” in JSON)

Return type:

int

property error: str
Returns:

Body error message (“Error” in JSON)

Return type:

str

classmethod from_proton_api_error(e: ProtonAPIError)

Construct an instance of this class, based on a ProtonAPIError (this allows to downcast to a more specific exception)

Parameters:

e (ProtonAPIError) – Initial API exception

Returns:

An instance of the current class

Return type:

Any

property http_code: int
Returns:

HTTP error code (401, 403, 422…)

Return type:

int

property http_headers: dict
Returns:

Dictionary of HTTP headers of the error reply

Return type:

dict

property json_data: dict
Returns:

JSON data of the error reply

Return type:

dict

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.