herre
DEVELOPMENT
Idea
Herre is a Python Library for easy integration with Token Based Authentication in Python Applications, (for example using OAuth2). It is designed to be extensible, and easy to use, and is built for the async world, while maintaining sync compatibility.
Herre is build on top of aiohttp, and uses pydantic for data validation.
Usage
In order to initialize a herre client you need to specify a specific grant to retrieve the access_token. A grant constitutes a way of retrieving a Token in an asynchronous manner.
from herre import Herre
from herre.grants.oauth2.client_credentials import ClientCredentialsGrant
client = Herre(
grant=ClientCredentialsGrant(
base_url="http://localhost:8000/o",
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
),
)
with client as c:
print(c.get_token()) # gets access token
# first time this is called it will retrieve a token from the server
Features
Herre supports the following protocols and grants to retrieve tokens:
Oauth2
- Client Credentials Flow
- Authorization Code Flow
- Authorization Code Flow with Redirect Server
- Authorization Code Flow with QtWebengine Redirect
- Refresh Token Flow
Others
- Basic Auth
Async First
Herre is fully async, and supports the async/await syntax. It is also fully compatible with the sync world, and can be used in sync applications.
Async Interface
client = Herre(
grant=ClientCredentialsGrant(
base_url="http://localhost:8000/o",
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
),
async with client as c:
token = await c.aget_token()
Composability
Herre grants provide a simple interface to be composable and enable features like caching, refresh tokens, and custom logic.
Enabling Caching the token until its expiration (or until the cache is cleared)
client = Herre(
grant=CacheGrant(
grant=AuthorizationCodeGrant(base_url="https://your_server/oauth_path",
client_id="$YOUR_CLIENT_ID",
client_secret="$YOUR_CLIENT_SECRET",
redirecter=AioHttpServerRedirecter(port=6767)
))
)
async with client:
await client.aget_token()
# This will first hit the cache and try to retrieve the token from there
await client.arefresh_token()
# This will bypass the cache and retrieve a new token from the server
Enabling refresh tokens:
client = Herre(
grant=RefreshGrant(
grant=AuthorizationCodeGrant(base_url="https://your_server/oauth_path",
client_id="$YOUR_CLIENT_ID",
client_secret="$YOUR_CLIENT_SECRET",
redirecter=AioHttpServerRedirecter(port=6767)
))
)
async with client:
await client.aget_token()
# this will try to refresh the token if it is expired, before restarting the
# authorization code flow
Please check out the documentation for the meta grants to see how to enable custom logic.
Builders
Herre comes with a set of builders to make it easier to create a client for common use cases, especially for oauth2.
Example Github
from herre import github_desktop
with github_desktop(
client_id="dfdb2c594470db113659", # This is a demo github oauth2 app
client_secret="bc59f1e3bc1ed0dcfb3548b457588f3b6e324764",
) as g:
print(g.get_token())
This will open a browser window and ask you to login to github, and then return the token. The builder will automatically create a redirect server for you, and use the github oauth2 api to retrieve the token. Builders are not magic, but simple provide convenience methods around the herre api.
Intergration with Qt
herre fully supports qt-based applications (both PySide2 and PyQt5) as well as a a redirect_flow for authentication in a webengine powered qt window Authoriation Code Flow (needs pyqtwebengine as additional dependency) ( you can still use the authorization code server if so desired, and actually recommended for production applications)
from herre import Herre
from koil.qt import async_to_qt
from PyQt5 import QtWidgets
from herre.grants.oauth2.authorization_code import AuthorizationCodeGrant
from herre.grants.oauth2.redirecters.qt_login_view import WebViewRedirecter
import sys
class LoginWidget(QtWidgets.QWidget):
def __init__(self, *args, **kwargs) -> None:
super().__init__(*args, **kwargs)
self.grant = AuthorizationCodeGrant(
base_url="https://github.com/login/oauth",
token_path="access_token",
client_id="dfdb2c594470db113659",
scopes=[],
append_trailing_slash=False,
client_secret="bc59f1e3bc1ed0dcfb3548b457588f3b6e324764",
redirecter=WebViewRedirecter(redirect_uri="http://127.0.0.1:6767/"),# this will open a
# webview to display the login page
)
self.herre = Herre(
grant=self.grant,
)
self.herre.enter() # herre requires to be entered before it can be used
self.login_task = async_to_qt(self.herre.aget_token)
self.login_task.returned.connect(self.on_login_finished)
self.login_task.errored.connect(self.on_login_error)
self.login_button = QtWidgets.QPushButton("Login")
self.greet_label = QtWidgets.QLabel("")
layout = QtWidgets.QVBoxLayout()
layout.addWidget(self.greet_label)
layout.addWidget(self.login_button)
self.setLayout(layout)
self.login_button.clicked.connect(self.greet)
def greet(self):
self.login_task.run()
def on_login_finished(self, token):
self.greet_label.setText(f"Hello User")
# do something with the token
def on_login_error(self, error):
self.greet_label.setText(f"Error: {error}")
if __name__ == '__main__':
app = QtWidgets.QApplication(['', '--no-sandbox']) # you need to pass --no-sandbox to the
# application if you are running it on linux (otherwise qtwebengine will not work)
main_window = LoginWidget()
main_window.show()
sys.exit(app.exec())
Build with
1 maintainer
Metadata
1 maintainer
Release files for herre 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| herre-1.0.0.tar.gz | 22.3 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| herre-1.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 54.5 kB
Release files / herre-1.0.0.tar.gz
| Download URL | herre-1.0.0.tar.gz |
|---|---|
| Size | 22.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
91d6a13d3a91ee1aec2953b2ca38eae7c648bfae3f0662560f7b4a45fdd73560
|
|
BLAKE2b-256 checksum How to use checksums |
004f36e39a1139fe870201827a627b2ccc5261fa2deca136a028e42b79f79ad6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.3 CPython/3.12.3 Linux/6.8.0-44-generic
|
Release files / herre-1.0.0-py3-none-any.whl
| Download URL | herre-1.0.0-py3-none-any.whl |
|---|---|
| Size | 32.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1d067ddb19c696ff34d3ca4da3f55876e91268c9047f7d9b17fb5c1f97a58a18
|
|
BLAKE2b-256 checksum How to use checksums |
2d041cb85744cd010cdeefd24f0624884f41b74e4f6529aabef9791376cf67a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/1.8.3 CPython/3.12.3 Linux/6.8.0-44-generic
|
Security for herre 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
