helper-auth 0.8.0

Request authentication using existing credential helpers.

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:

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:

auth = HelperAuth("helper")

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):

auth = HelperAuth("helper --option arg")

In addition, the first positional argument can be a path-like object:

auth = HelperAuth(Path("helper"))

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:

auth = HelperAuth("helper", cache_token=True)

The cached token can then be cleared anytime by calling

auth.clear_cache()