{"id":20244285,"url":"https://github.com/protonmail/proton-python-client","last_synced_at":"2025-04-12T19:48:48.706Z","repository":{"id":39585250,"uuid":"259947084","full_name":"ProtonMail/proton-python-client","owner":"ProtonMail","description":"Python Proton client module","archived":false,"fork":false,"pushed_at":"2024-07-31T12:45:42.000Z","size":1754,"stargazers_count":387,"open_issues_count":16,"forks_count":64,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-04-12T19:48:32.960Z","etag":null,"topics":["api","client","protonmail","protonvpn","python","srp"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ProtonMail.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-29T14:22:26.000Z","updated_at":"2025-04-08T21:10:28.000Z","dependencies_parsed_at":"2024-06-19T01:48:35.413Z","dependency_job_id":"cb1a7e74-9c4c-4a65-9394-3b4566902943","html_url":"https://github.com/ProtonMail/proton-python-client","commit_stats":{"total_commits":111,"total_committers":5,"mean_commits":22.2,"dds":"0.46846846846846846","last_synced_commit":"5d9dfa77fdaccb0c800134dab08dc3d5d8147363"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProtonMail%2Fproton-python-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProtonMail%2Fproton-python-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProtonMail%2Fproton-python-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ProtonMail%2Fproton-python-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ProtonMail","download_url":"https://codeload.github.com/ProtonMail/proton-python-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248625501,"owners_count":21135513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","client","protonmail","protonvpn","python","srp"],"created_at":"2024-11-14T09:14:03.025Z","updated_at":"2025-04-12T19:48:48.676Z","avatar_url":"https://github.com/ProtonMail.png","language":"Python","readme":"# Proton API Python Client\n\nCopyright (c) 2021 Proton Technologies AG\n\nThis repository holds the Proton Python Client.\nFor licensing information see [COPYING](COPYING.md).\nFor contribution policy see [CONTRIBUTING](CONTRIBUTING.md).\n\n## Description\nThe Python Proton Client is intended for every Proton service user.\n\nYou can download the latest stable release, either from our official repositories or directly on the [official GitHub repository](https://github.com/ProtonMail/proton-python-client/releases/latest).\n\n## Dependencies\n| **Python** | **Debian** | **Fedora** | **Arch** |\n|:-----------|:-----------|:-----------|:---------|\n| [requests](https://github.com/psf/requests) \u003e= 2.16.0 **\\*** | python3-requests | python3-requests | python-requests |\n| [bcrypt](https://github.com/pyca/bcrypt/) | python3-bcrypt | python3-bcrypt | python-bcrypt                   |\n| [python-gnupg](https://docs.red-dove.com/python-gnupg/) | python3-gnupg | python3-gnupg | python-gnupg        |\n| [pyopenssl](https://www.pyopenssl.org/en/stable/) | python3-openssl | python3-pyOpenSSL | python-pyopenssl    |\n\n\n**\\*** versions lower than 2.16 of the Python Requests library are not officially supported due to the missing support for TLS pinning, which is required in order to properly verify and trust the connection to the Proton API. It is possible disable TLS pinning (ie: to run with lower requests versions), but be aware of the risk.\n\n## Table of Contents\n- [Install](#install)\n- [Usage](#usage)\n    - [Import](#import)\n    - [Setup](#setup)\n    - [Authenticate](#authenticate)\n    - [Store session](#store-session)\n    - [Load session](#load-session)\n    - [Refresh Session](#refresh-session)\n    - [API calls](#api-calls)\n    - [Error handling](#error-handling)\n\n## Install\nThe recommended way to install the client is via OS-respective packages (.deb/.rpm/.zst), by either compiling it yourself or downloading the binaries from our repositories. If for some reason that is not possible, then a normal python installation can be accomplished.\n\n# Usage\n\n## Import\n`from proton.api import Session, ProtonError`\n\n## Setup\nBy default, TLS pinning is enabled. If you would like to disable it, you can additionally pass `TLSPinning=False`.\n```\nproton_session = Session(\n    api_url=\"https://example.api.com\",\n    appversion=\"GithubExample_0.0.1\",\n    user_agent=\"Ubuntu_20.04\",\n)\n```\n`api_url`: The base API url\n\n`appversion`: Usually this is the version of the application that is implementing the client. Leave it empty for non-official Proton clients.\n\n`user_agent`: This helps us to understand on what type of platforms the client is being used. This usually can be fed with the output of a python package called [distro](https://github.com/nir0s/distro). Leave empty in case of doubt.\n\nNow that we've setup our Proton session, we're ready for authentication.\n\n## Authenticate\nTo authenticate against the Proton API, two types of information would need to be provided first, the Proton username and password.\n```\nproton_session.authenticate(username, password)\n```\n`username`: Proton username, ie: protonvpn@protonmail.ch\n\n`password`: Proton password\n\nAfter successfully authenticating against the API, we can now start using our `proton_session` object to make API calls. More on that in [API calls](#api-calls).\n\n## Store session\nTo store the session locally on disk (for later re-use), we need to first extract its contents. To accomplish that we will need to use a method called `dump()`. This method returns a dict.\n\n```\nproton_session.dump()\n```\n\nThe output of a dump will usually look something like this:\n```\nsession_dump = proton_session.dump()\nprint(session_dump)\n---\n{\"api_url\": \"https://example.api.com\", \"appversion\": \"GithubExample_0.0.1\", \"User-Agent\": \"Ubuntu_20.04\", \"cookies\": {}, \"session_data\": {}}\n```\nIf cookies and session_data contain no data, then it means that we've attempted to make an API call and it failed or we haven't made one yet.\n\nIf authenticated, `session_data` will contain some data that will be necessary for the [Refresh Session](#refresh-session) chapter, in particular the keys `AccessToken` and `RefreshToken`.\n\n**Note:** It is recommended to store the contents as JSON.\n\n## Load session\nTo re-use a session that we've previously stored we need to do as following:\n1. Get session contents\n2. Instantiate our session\n\nIf for example we've previously stored the session on a JSON file, then we would need to extract the session contents from file first (step 1):\n```\nwith open(PATH_TO_JSON_SESSION_FILE, \"r\") as f:\n    session_in_json_format = json.loads(f.read())\n```\n\nNow we can proceed with session instantiation (step 2):\n```\nproton_session = Session.load(\n    dump=session_in_json_format\n)\n```\n\nNow we're able to start using our `proton_session` object to make API calls. More on that in [API calls](#api-calls).\n\n## Refresh Session\nAs previously introduced in the [Store session](#store-session) chapter, `AccessToken` and `RefreshToken` are two tokens that identify us against the API. As their names imply, `AccessToken` is used to give us access to the API while `RefreshToken` is used to refresh the `AccessToken` whenever this one is invalidated by the servers. An `AccessToken` can be invalidated for the following reasons:\n- When the session is removed via the webclient\n- When a `logout()` is executed\n- When the session has expired\n\nIf for any reason the API responds with error 401, then it means that the `AccessToken` is invalid and it needs to be refreshed (assuming that the `RefreshToken` is valid). To refresh the tokens **\\*** we can use the following method:\n\n```\nproton_session.refresh()\n```\n\nOur tokens **\\*** have now been updated. To make sure that we can re-use this session with the refreshed tokens **\\***, we can store them into file (or keyring). Consult the [Store session](#store-session) chapter on how to accomplish that.\n\n**\\*** when we use the `refresh()` method, both `AccessToken` and `RefreshToken` are refreshed.\n\n## API calls\nOnce we're authenticated and our tokens are valid, we can make api calls to various endpoints. By default a `post` request is made, unless another type of request is passed: `method=get|post|put|delete|patch|None`. Also additional custom headers can be sent with `additional_headers=\"{'header': 'custom_header'}\"`. Then to make the request we can use the following:\n```\nproton_session.api_request(endpoint=\"custom_api_endpoint\")\n```\n\n## Error handling\nFor all of commands presented in the previous chapters, it is recommended to use them within try/except blocks. Some common errors that might come up:\n- `401`: Invalid `AccessToken`, client should refresh tokens ([Refresh Session](#refresh-session))\n- `403`: Missing scopes, client should re-authenticate (logout and login)\n- `429`: Too many requests. Retry after time provided by `ProtonError.headers[\"Retry-After\"]`\n- `503`: Unable to reach API (most probably API is down)\n- `8002`: Provided password is wrong\n- `10002`:  Account is deleted\n- `10003`:  Account is disabled\n- `10013`:  `RefreshToken` is invalid. Client should re-authenticate (logout and login)\n\nBelow are some use cases:\n\n- Authentication\n```\nerror_message = {\n    8002: \"Provided password is incorrect\",\n    10002: \"Account is deleted\",\n    10003: \"Account is disabled\",\n}\ntry:\n    proton_session.authenticate(\"proton_user@protonmail.ch\", \"Su!erS€cretPa§§word\")\nexcept ProtonError as e:\n    print(error_message.get(e.code, \"Unknown error\")\n```\n\n- API requests\n```\nerror_message = {\n    401: \"Invalid access token, client should refresh tokens\",\n    403: \"Missing scopes, client should re-authenticate\",\n    429: \"Too many requests, client needs to retry after specified in headers\",\n    503: \"API is unreacheable\",\n    10013: \"Refresh token is invalid. Client should re-authenticate (logout and login)\",\n}\n\ntry:\n    proton_session.api_request(endpoint=\"custom_api_endpoint\")\nexcept ProtonError as e:\n    print(error_message.get(e.code, \"Unknown error\")\n```\n- Refresh token\n\n```\ntry:\n    proton_session.api_request(endpoint=\"custom_api_endpoint\")\nexcept ProtonError as e:\n    e.code == 401:\n        proton_session.refresh()\n        print(\"Now we can retry making another API call since tokens have been refreshed\")\n```","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprotonmail%2Fproton-python-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprotonmail%2Fproton-python-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprotonmail%2Fproton-python-client/lists"}