[![helper-auth on PyPI][PyPI badge]][PyPI page]
This Python library provides the `HelperAuth` class whose objects are intended
to be used as custom authentication handlers in conjunction with
the [Requests] library, as suggested in its [documentation].
# Installation
```
pip install helper-auth
```
# Usage
Suppose you have an existing GitHub personal access token, and
a [Git credential helper] already set up for Git to authenticate to
GitHub using this token as the password. This helper prints the following
to standard output:
```
$ git credential-github
username=YOUR_GITHUB_USERNAME
password=YOUR_GITHUB_TOKEN
```
You want to use the same token to make GitHub API calls using the Requests
library. The API expects the field `Authorization: Bearer YOUR_GITHUB_TOKEN` in
your request's headers.
You can use `HelperAuth` with its default settings:
```python
import requests
from helper_auth import HelperAuth
auth = HelperAuth("git credential-github")
response = requests.get("https://api.github.com/user", auth=auth)
```
## Specifying the helper command
The helper command can be specified as one or more positional arguments:
```python
auth = HelperAuth("helper")
```
```python
auth = HelperAuth("helper", "--option", "arg")
```
As a shortcut, a command with command-line arguments can also be passed
as single string (this form is used in the code snippet above):
```python
auth = HelperAuth("helper --option arg")
```
In addition, the first positional argument can be a path-like object:
```python
auth = HelperAuth(Path("helper"))
```
```python
auth = HelperAuth(Path("helper"), "--option", "arg")
```
## Caching the token
By default, a `HelperAuth` object never stores the value of the token
in its internal state. Rather, the helper command is invoked
each time the auth object is called. This is an intentional precaution (such
that the token cannot be retrieved *ex post* by the introspection of the
auth object) but it can also be unnecessarily expensive in situations
where such precaution is not necessary and the auth object is to
be called repeatedly, e.g. when making many simultaneous API calls.
You can override this behavior by passing `cache_token=True` to the
constructor:
```python
auth = HelperAuth("helper", cache_token=True)
```
The cached token can then be cleared anytime by calling
```python
auth.clear_cache()
```
[PyPI badge]: https://img.shields.io/pypi/v/helper-auth
[PyPI page]: https://pypi.org/project/helper-auth
[Requests]: https://requests.readthedocs.io
[documentation]: https://requests.readthedocs.io/en/latest/user/authentication/#new-forms-of-authentication
[Git credential helper]: https://git-scm.com/docs/gitcredentials#_custom_helpers
Raw data
{
"_id": null,
"home_page": "https://github.com/mportesdev/helper-auth",
"name": "helper-auth",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "http,requests,credentials",
"author": "Michal Porte\u0161",
"author_email": "michalportes1@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1a/43/0e5abc9c94a4baf7874be44a803d1d705b06fa9ce1321b71dd2ca7239930/helper_auth-0.8.0.tar.gz",
"platform": null,
"description": "[![helper-auth on PyPI][PyPI badge]][PyPI page]\n\nThis Python library provides the `HelperAuth` class whose objects are intended\nto be used as custom authentication handlers in conjunction with\nthe [Requests] library, as suggested in its [documentation].\n\n\n# Installation\n\n```\npip install helper-auth\n```\n\n\n# Usage\n\nSuppose you have an existing GitHub personal access token, and\na [Git credential helper] already set up for Git to authenticate to\nGitHub using this token as the password. This helper prints the following\nto standard output:\n\n```\n$ git credential-github\nusername=YOUR_GITHUB_USERNAME\npassword=YOUR_GITHUB_TOKEN\n```\n\nYou want to use the same token to make GitHub API calls using the Requests\nlibrary. The API expects the field `Authorization: Bearer YOUR_GITHUB_TOKEN` in\nyour request's headers.\n\nYou can use `HelperAuth` with its default settings:\n\n```python\nimport requests\nfrom helper_auth import HelperAuth\n\nauth = HelperAuth(\"git credential-github\")\n\nresponse = requests.get(\"https://api.github.com/user\", auth=auth)\n```\n\n\n## Specifying the helper command\n\nThe helper command can be specified as one or more positional arguments:\n\n```python\nauth = HelperAuth(\"helper\")\n```\n\n```python\nauth = HelperAuth(\"helper\", \"--option\", \"arg\")\n```\n\nAs a shortcut, a command with command-line arguments can also be passed\nas single string (this form is used in the code snippet above):\n\n```python\nauth = HelperAuth(\"helper --option arg\")\n```\n\nIn addition, the first positional argument can be a path-like object:\n\n```python\nauth = HelperAuth(Path(\"helper\"))\n```\n\n```python\nauth = HelperAuth(Path(\"helper\"), \"--option\", \"arg\")\n```\n\n\n## Caching the token\n\nBy default, a `HelperAuth` object never stores the value of the token\nin its internal state. Rather, the helper command is invoked\neach time the auth object is called. This is an intentional precaution (such\nthat the token cannot be retrieved *ex post* by the introspection of the\nauth object) but it can also be unnecessarily expensive in situations\nwhere such precaution is not necessary and the auth object is to\nbe called repeatedly, e.g. when making many simultaneous API calls.\n\nYou can override this behavior by passing `cache_token=True` to the\nconstructor:\n\n```python\nauth = HelperAuth(\"helper\", cache_token=True)\n```\n\nThe cached token can then be cleared anytime by calling\n\n```python\nauth.clear_cache()\n```\n\n[PyPI badge]: https://img.shields.io/pypi/v/helper-auth\n[PyPI page]: https://pypi.org/project/helper-auth\n[Requests]: https://requests.readthedocs.io\n[documentation]: https://requests.readthedocs.io/en/latest/user/authentication/#new-forms-of-authentication\n[Git credential helper]: https://git-scm.com/docs/gitcredentials#_custom_helpers\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Request authentication using existing credential helpers.",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/mportesdev/helper-auth"
},
"split_keywords": [
"http",
"requests",
"credentials"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9222c99a5c9f1c891d988ee71c89d08de44e0600ef0a7b3c20b9779537422093",
"md5": "80068355ba5000e4d17d792337ccbe84",
"sha256": "fc0faccf4d12f6946984bd935e84a2f5081ea1381e19e783d1e96c73b9ef56ec"
},
"downloads": -1,
"filename": "helper_auth-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "80068355ba5000e4d17d792337ccbe84",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 4185,
"upload_time": "2023-10-11T08:32:46",
"upload_time_iso_8601": "2023-10-11T08:32:46.420545Z",
"url": "https://files.pythonhosted.org/packages/92/22/c99a5c9f1c891d988ee71c89d08de44e0600ef0a7b3c20b9779537422093/helper_auth-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1a430e5abc9c94a4baf7874be44a803d1d705b06fa9ce1321b71dd2ca7239930",
"md5": "4bc4e7e341e6faf0a68255b0b7a9ac1b",
"sha256": "9102de42fa9c8f953a9558a1d4c79c9e9e061f4a637a59e0ea9b3c919b9a395a"
},
"downloads": -1,
"filename": "helper_auth-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "4bc4e7e341e6faf0a68255b0b7a9ac1b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 3655,
"upload_time": "2023-10-11T08:32:48",
"upload_time_iso_8601": "2023-10-11T08:32:48.253129Z",
"url": "https://files.pythonhosted.org/packages/1a/43/0e5abc9c94a4baf7874be44a803d1d705b06fa9ce1321b71dd2ca7239930/helper_auth-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-11 08:32:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mportesdev",
"github_project": "helper-auth",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"tox": true,
"lcname": "helper-auth"
}
JSON
