Metadata-Version: 2.1
Name: herre
Version: 0.3.9
Summary: oauth2/openid client tailored to pyqt and async environments
License: CC BY-NC 3.0
Author: jhnnsrs
Author-email: jhnnsrs@gmail.com
Requires-Python: >=3.7,<4.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Provides-Extra: fakts
Provides-Extra: qt
Provides-Extra: windowed
Requires-Dist: QtPy (>=2.0.1,<3.0.0); extra == "qt"
Requires-Dist: aiohttp (>3.7.4)
Requires-Dist: certifi (>2021)
Requires-Dist: fakts (>=0.2.13,<0.3.0); extra == "fakts"
Requires-Dist: koil (>=0.2.10)
Requires-Dist: oauthlib (>=3.1.1,<4.0.0)
Requires-Dist: pydantic (>=1.9.0,<2.0.0)
Description-Content-Type: text/markdown

# herre

[![codecov](https://codecov.io/gh/jhnnsrs/herre/branch/master/graph/badge.svg?token=UGXEA2THBV)](https://codecov.io/gh/jhnnsrs/herre)
[![PyPI version](https://badge.fury.io/py/herre.svg)](https://pypi.org/project/herre/)
![Maintainer](https://img.shields.io/badge/maintainer-jhnnsrs-blue)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/herre.svg)](https://pypi.python.org/pypi/herre/)
[![PyPI status](https://img.shields.io/pypi/status/herre.svg)](https://pypi.python.org/pypi/herre/)
[![PyPI download month](https://img.shields.io/pypi/dm/herre.svg)](https://pypi.python.org/pypi/herre/)

#### DEVELOPMENT

## Idea

herre is an (asynchronous) client for token authentication through oauth2 (and potentially other protocols).

## Prerequisites

herre needs a oauth2/opendid server to connect to

## Supports

- Authorization Code Flow (PKCE)
  - Within a Qt app through a QtWebengine View
  - With a Redirect Server
- Client-Credentials Flow

## Usage

In order to initialize the Client you need to specify a specific grant to retrieve the code. A grant constitutes
a way of retrieving a Token in an asynchronous manner.

```python
from herre import Herre
from herre.grants.oauth2.authorization_code_server import AuthorizationCodeServer

client = Herre(
    grant=AuthorizationCodeServerGrant(base_url="https://your_server/oauth_path",
    client_id="$YOUR_CLIENT_ID",
    client_secret="$YOUR_CLIENT_SECRET",)
)

with client:
  client.login()

```

Async usage

```python

client = Herre(
    grant=AuthorizationCodeServerGrant(base_url="https://your_server/oauth_path",
    client_id="$YOUR_CLIENT_ID",
    client_secret="$YOUR_CLIENT_SECRET",
    redirect_uri="http://localhost:6767)
)

async with client as c:
  await c.login()

```

## Composability

Herre grants provide a simple interface to be composable and enable caching, or support for refresh tokens:

```python
client = Herre(
    grant=CacheGrant(
      grant=AuthorizationCodeServerGrant(base_url="https://your_server/oauth_path",
          client_id="$YOUR_CLIENT_ID",
          client_secret="$YOUR_CLIENT_SECRET",
          redirect_uri="http://localhost:6767")
))

async with client:
  await client.login()
```

Please check out the documentation for the meta grants to see how to enable custom logic.

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

```python
class MainWindow(QtWidget)

    def __init__(self, *args, **kwargs):
        self.herre = Herre(
          grant=AuthorizationCodeQtGrant(
            base_url="https://your_server/oauth_path",
            client_id="$YOUR_CLIENT_ID",
            client_secret="$YOUR_CLIENT_SECRET",
            redirect_uri="about:blank,)
        )

        self.herre.enter() #programmatically enter context (make sure to call exit)


    def login()
        self.herre.login()
```

## Build with

- [koil](https://github.com/jhnnsrs/koil) - for pyqt event loop handling
- [oauthlib](https://github.com/oauthlib/oauthlib) - for oauth2 compliance
- [aiohttp](https://github.com/aio-libs/aiohttp) - transport layer (especially redirect server)

