wau 0.1.8

Web API Utils for Werkzeug

wau - Web API Utils

Web API Utils, or short wau, is a thin layer on top of Werkzeug 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), 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 is recommended for installing and managing dependencies, and managing virtual environments. Install wau into the current environment with:

uv add wau

An Introductory Example

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

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:

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.