Metadata-Version: 2.4
Name: wau
Version: 0.1.7
Summary: Web API Utils for Werkzeug
License-Expression: LGPL-3.0-or-later
Project-URL: Repository, https://codeberg.org/smlz/wau
Keywords: api,json,werkzeug,education
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dataset>=2.0.0
Requires-Dist: pyjwt>=2.13.0
Requires-Dist: watchdog>=6.0.0
Requires-Dist: werkzeug>=3.1.8
Dynamic: license-file

# wau - Web API Utils

Web API Utils, or short `wau`, is a thin layer on top of
[Werkzeug](https://werkzeug.palletsprojects.com/) and other (optional)
libraries to provide a simple way for writing APIs in Python with zero
boilerplate code.

It is built for educational purposes and is _not_ intended for production use.

`wau` supports JSON as it's only data exchange format and uses type
annotations to define and enforce the inputs of the API endpoints. It comes
with built-in support for accessing databases (via
[dataset](https://dataset.readthedocs.io/)), user authentication, and
real-time apps using server-sent events. A development server with sensible
CORS support and live reload for API code and static files easies development
and testing.

## Installation

The use of [uv](https://pypi.org/project/uv/) is recommended for installing
and managing dependencies, and managing virtual environments. Install `wau`
into the current environment with:

```sh
uv add wau
```

## An Introductory Example

The stereotypical "todo" API example looks like this with `wau`:

```py{filename="todo_api.py"}
from wau import API, NotFound, database_connect, run

api = API()
db = database_connect("todos.db")
todos = db["todos"]

@api.GET("/todo/")
def list_todos():
    return list(todos.find())

@api.POST("/todo/")
def new_entry(text: str):
    todo_id = todos.insert({"text": text, "done": False})
    return {"id": todo_id, "text": text, "done": False}

@api.PUT("/todo/{id: int}")
def update_entry(id, done: bool):
    if not todos.find_one(id=id):
        raise NotFound()
    todos.update({"id": id, "done": done}, ["id"])

@api.DELETE("/todo/{id: int}")
def delete_entry(id):
    if not todos.find_one(id=id):
        raise NotFound()
    todos.delete(id=id)

if __name__ == "__main__":
    run(api)
```

Run the backend with:
```
$ python todo_api.py
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on http://localhost:3000
Press CTRL+C to quit
 * Restarting with watchdog (windowsapi)
 ```

Now you can send requests to the API, for example with `curl`:
```sh
curl -X POST -H "Content-Type: application/json" -d '{"text": "Buy bread"}' http://localhost:3000/todo/
{"id": 1, "text": "Buy bread", "done": false}
```

The development server will by default serve static files from the same
directory as the script. For example, if you create an `index.html` file with
some JavaScript that fetches the API, you can open the mentioned URL
(`http://localhost:3000/`) in the browser and it will work without any
additional configuration.

The development server also supports live reload, so if you change the API
code or the static files, the browser will automatically refresh to reflect
the changes.

## License

This project is licensed under GNU LGPL v3 or later (`LGPL-3.0-or-later`).

If you distribute modified versions of this library, those library
modifications must be published under the same license terms.
