Metadata-Version: 2.1
Name: asfquart
Version: 0.1.10
Summary: ASF Quart Framework
Home-page: https://github.com/apache/infrastructure-asfquart
License: Apache-2.0
Author: ASF Infrastructure
Author-email: users@infra.apache.org
Requires-Python: >=3.10,<4
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: aioldap
Requires-Dist: PyYAML (>=6.0.1,<7.0.0)
Requires-Dist: aiohttp (>=3.9.2,<4.0.0)
Requires-Dist: asfpy (>=0.55,<0.56)
Requires-Dist: bonsai ; extra == "aioldap"
Requires-Dist: easydict (>=1.13,<1.14)
Requires-Dist: exceptiongroup (>=1.1.0) ; python_version < "3.11"
Requires-Dist: ezt (>=1.1,<1.2)
Requires-Dist: quart (>=0.20.0,<0.21.0)
Requires-Dist: watchfiles (>=1.0.0,<1.1.0)
Project-URL: Repository, https://github.com/apache/infrastructure-asfquart
Description-Content-Type: text/markdown

# asfquart - a Quart framework for the ASF
<a href="https://pypi.org/project/asfquart"><img alt="PyPI" src="https://img.shields.io/pypi/v/asfquart.svg?color=blue&maxAge=600" /></a>
<a href="https://pypi.org/project/asfquart"><img alt="PyPI - Python Versions" src="https://img.shields.io/pypi/pyversions/asfquart.svg?maxAge=600" /></a>
<a href="https://github.com/apache/infrastructure-asfquart/actions/workflows/unit-tests.yml?query=branch%3Amain"><img alt="Unit Tests" src="https://github.com/apache/infrastructure-asfquart/actions/workflows/unit-tests.yml/badge.svg?branch=main" /></a>
<a href="https://github.com/apache/infrastructure-asfquart/blob/main/LICENSE"><img alt="Apache License" src="https://img.shields.io/github/license/apache/infrastructure-asfquart" /></a>

This is a [Quart](https://github.com/pallets/quart/) framework for ASF web applications.

On top of Quart, this package layers a lot of functionality, much of which is specific to
the ASF and its infrastructure and preferred approaches for website application development.

asfquart adds the following items to basic quart:

* simple construction of the `APP`
* default `config.yaml`
* watching the .py and config for changes, to cause a restart/reload
* watch SIGINT to halt and SIGUSR2 to restart/reload
* template watching and rendering for EZT templates
* URL path routing for pages and API endpoints
* Oauth with our ASF provider for authn
* LDAP group testing for authz
* long-running tasks and their lifecycle management

Current (known, public) users of asfquart:

* [Board Agenda Tool](https://github.com/apache/infrastructure-agenda/)
* [Infrastructure's Reporting Dashboard](https://github.com/apache/infrastructure-reporting-dashboard)
* [ASF Self Serve Portal](https://github.com/apache/infrastructure-selfserve-portal)


Future users of asfquart:

* Apache STeVe
* Identity management (replaces the old id.a.o)
* Gitbox UI
* ??

## Primer

See the [documentation page](docs/readme.md) for more information.

~~~python
import asfquart
from asfquart.auth import Requirements as R

def my_app():
    # Construct the quart service. By default, the oauth gateway is enabled at /oauth.
    app = asfquart.construct("my_app_service")

    @app.route("/")
    async def homepage():
        return "Hello!"

    @app.route("/secret")
    @asfquart.auth.require(R.committer)
    async def secret_page():
      return "Secret stuff!"
    
    asfquart.APP.run(port=8000)


if __name__ == "__main__":
    my_app()

~~~

## Installation

Create and activate a virtual environment and then install `asfquart` using [pip](https://pip.pypa.io):

```console
$ pip install "asfquart"
```

Note: Adding the `[aioldap]` extra will install optional dependencies for LDAP support that will
require additional [system dependencies](https://github.com/noirello/bonsai?tab=readme-ov-file#requirements-for-building):

```console
$ pip install "asfquart[aioldap]"
```

## Building asfquart package

Prerequisites:

- `poetry`: install e.g. with pipx `pipx install poetry`

Building the package:

```console
$ poetry build
```

Running the tests:

```console
$ poetry run pytest
```

