wau 0.1.0__tar.gz

wau-0.1.0/LICENSE

@@ -0,0 +1,14 @@
+GNU LESSER GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+This project is licensed under the GNU Lesser General Public License,
+version 3 or (at your option) any later version.
+
+For the full license text, see:
+https://www.gnu.org/licenses/lgpl-3.0.txt
+
+SPDX-License-Identifier: LGPL-3.0-or-later

wau-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: wau
+Version: 0.1.0
+Summary: Web API Utils
+Author: Marco Schmalz
+License-Expression: LGPL-3.0-or-later
+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: 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 to provide a simple and consistent interface for writing APIs in Python. `wau` is built for educational purposes and is not intended for production use. It is opinionated, as it only supports JSON as data format. It uses simple type annotations to define the expected input and output of the API endpoints. Common tasks as authentication, CORS and server-sent events are supported by default.
+
+## Installation
+
+Install from PyPI:
+
+```powershell
+pip install wau
+```
+
+or with uv:
+
+```powershell
+uv add wau
+```
+
+## Testing
+
+Test dependencies are separated from runtime dependencies in `pyproject.toml`
+using the `test` dependency group.
+
+Run the test suite:
+
+```powershell
+uv run --group test python -m pytest -q
+```
+
+Run doctests:
+
+```powershell
+uv run --group test python -m doctest .\wau.py
+```
+
+## Publishing
+
+Build package artifacts:
+
+```powershell
+uv build
+```
+
+Validate metadata and README rendering:
+
+```powershell
+uvx twine check dist/*
+```
+
+Upload to TestPyPI first:
+
+```powershell
+uv publish --publish-url https://test.pypi.org/legacy/
+```
+
+Then publish to PyPI:
+
+```powershell
+uv publish
+```
+
+## 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.

wau-0.1.0/README.md

@@ -0,0 +1,67 @@
+# `wau` — Web API Utils
+
+Web API Utils, or short `wau`, is a thin layer on top of Werkzeug to provide a simple and consistent interface for writing APIs in Python. `wau` is built for educational purposes and is not intended for production use. It is opinionated, as it only supports JSON as data format. It uses simple type annotations to define the expected input and output of the API endpoints. Common tasks as authentication, CORS and server-sent events are supported by default.
+
+## Installation
+
+Install from PyPI:
+
+```powershell
+pip install wau
+```
+
+or with uv:
+
+```powershell
+uv add wau
+```
+
+## Testing
+
+Test dependencies are separated from runtime dependencies in `pyproject.toml`
+using the `test` dependency group.
+
+Run the test suite:
+
+```powershell
+uv run --group test python -m pytest -q
+```
+
+Run doctests:
+
+```powershell
+uv run --group test python -m doctest .\wau.py
+```
+
+## Publishing
+
+Build package artifacts:
+
+```powershell
+uv build
+```
+
+Validate metadata and README rendering:
+
+```powershell
+uvx twine check dist/*
+```
+
+Upload to TestPyPI first:
+
+```powershell
+uv publish --publish-url https://test.pypi.org/legacy/
+```
+
+Then publish to PyPI:
+
+```powershell
+uv publish
+```
+
+## 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.

wau-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wau"
+version = "0.1.0"
+description = "Web API Utils"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "LGPL-3.0-or-later"
+authors = [
+    { name = "Marco Schmalz" },
+]
+keywords = ["api", "json", "werkzeug", "education"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Education",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "dataset>=2.0.0",
+    "pyjwt>=2.13.0",
+    "werkzeug>=3.1.8",
+]
+
+[tool.setuptools]
+py-modules = ["wau"]
+
+[dependency-groups]
+test = [
+    "playwright>=1.60.0",
+    "pytest>=9.0.3",
+    "pytest-playwright>=0.8.0",
+]
+
+dev = [
+    "black>=24.10.0",
+    "isort>=8.0.1",
+]

wau-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wau-0.1.0/tests/test_auth_exempt.py

@@ -0,0 +1,85 @@
+"""Tests for BaseJWTAuthMiddleware exempt-route matching."""
+
+from werkzeug.test import Client
+
+from wau import API, DummyAuth
+
+SECRET = "not a secret but still quite long"
+
+
+def _build_app(exempt):
+    api = API()
+
+    @api.GET("/items/{id:int}")
+    def get_item(request, id):
+        return {"id": id, "user": request.remote_user}
+
+    @api.POST("/items/{id:int}")
+    def update_item(request, id, name: str):
+        return {"id": id, "name": name, "user": request.remote_user}
+
+    @api.GET("/public")
+    def public(request):
+        return "public"
+
+    return DummyAuth(api, SECRET, exempt=exempt)
+
+
+def test_exempt_path_with_typed_placeholder_allows_request():
+    app = _build_app(exempt=[("GET", "/items/{id:int}")])
+    client = Client(app)
+    response = client.get("/items/42")
+    assert response.status == "200 OK"
+    assert response.get_json() == {"id": 42, "user": None}
+
+
+def test_exempt_path_does_not_match_wrong_type():
+    app = _build_app(exempt=[("GET", "/items/{id:int}")])
+    client = Client(app)
+    # 'abc' is not an int, so the exempt rule does not match; auth is required.
+    response = client.get("/items/abc")
+    assert response.status == "401 UNAUTHORIZED"
+
+
+def test_exempt_method_is_method_specific():
+    app = _build_app(exempt=[("GET", "/items/{id:int}")])
+    client = Client(app)
+    response = client.post("/items/42", json={"name": "x"})
+    assert response.status == "401 UNAUTHORIZED"
+
+
+def test_non_exempt_path_still_requires_auth():
+    app = _build_app(exempt=[("GET", "/items/{id:int}")])
+    client = Client(app)
+    response = client.get("/public")
+    assert response.status == "401 UNAUTHORIZED"
+
+
+def test_plain_exempt_path_allows_request():
+    app = _build_app(exempt=[("GET", "/public")])
+    client = Client(app)
+    response = client.get("/public")
+    assert response.status == "200 OK"
+    assert response.get_json() == "public"
+
+
+def test_login_and_renew_are_auto_exempt():
+    app = _build_app(exempt=[])
+    client = Client(app)
+
+    # Login is always reachable without auth.
+    response = client.post("/auth/login")
+    assert response.status == "200 OK"
+    token = response.get_json()["token"]
+
+    # Renew is reachable without auth (token is supplied in body).
+    response = client.post("/auth/renew", json={"token": token})
+    assert response.status == "200 OK"
+
+
+def test_login_method_restriction():
+    # Default login_methods=("POST",); GET on /auth/login must require auth.
+    app = _build_app(exempt=[])
+    client = Client(app)
+    response = client.get("/auth/login")
+    assert response.status == "401 UNAUTHORIZED"

wau-0.1.0/tests/test_cors_same_host.py

@@ -0,0 +1,61 @@
+from werkzeug.test import Client
+
+from wau import API, _cors_same_host_middleware
+
+
+def _build_api():
+    api = API()
+
+    @api.GET("/")
+    def root():
+        return {"ok": True}
+
+    return api
+
+
+def test_cors_disabled_by_default():
+    client = Client(_build_api())
+
+    response = client.get("/", headers={"Origin": "http://localhost:5173"})
+
+    assert "Access-Control-Allow-Origin" not in response.headers
+
+
+def test_same_host_allows_any_port():
+    app = _cors_same_host_middleware(_build_api(), "localhost")
+    client = Client(app)
+
+    response = client.get("/", headers={"Origin": "http://localhost:5173"})
+
+    assert response.status_code == 200
+    assert response.headers["Access-Control-Allow-Origin"] == "http://localhost:5173"
+
+
+def test_other_host_is_not_allowed():
+    app = _cors_same_host_middleware(_build_api(), "localhost")
+    client = Client(app)
+
+    response = client.get("/", headers={"Origin": "http://example.com:5173"})
+
+    assert response.status_code == 200
+    assert "Access-Control-Allow-Origin" not in response.headers
+
+
+def test_preflight_for_allowed_host():
+    app = _cors_same_host_middleware(_build_api(), "localhost")
+    client = Client(app)
+
+    response = client.open(
+        "/",
+        method="OPTIONS",
+        headers={
+            "Origin": "http://localhost:3001",
+            "Access-Control-Request-Method": "PUT",
+            "Access-Control-Request-Headers": "Content-Type, Authorization",
+        },
+    )
+
+    assert response.status_code == 204
+    assert response.headers["Access-Control-Allow-Origin"] == "http://localhost:3001"
+    assert "PUT" in response.headers["Access-Control-Allow-Methods"]
+    assert "Content-Type" in response.headers["Access-Control-Allow-Headers"]

wau-0.1.0/tests/test_hangman_e2e.py

@@ -0,0 +1,40 @@
+from playwright.sync_api import expect
+
+from examples.hangman import hangman_api
+
+
+def _open_hangman_page(page, hangman_server_url):
+    page.goto(f"{hangman_server_url}/hangman_client.html")
+    expect(page.get_by_role("heading", name="Hangman")).to_be_visible()
+    expect(page.locator("button.letter").first).to_be_visible()
+
+
+def test_hangman_successful_game(page, monkeypatch, hangman_server_url):
+    hangman_api.games.clear()
+    monkeypatch.setattr(hangman_api.random, "randrange", lambda _n: 111111)
+    monkeypatch.setattr(hangman_api.random, "choice", lambda _words: "abc")
+
+    _open_hangman_page(page, hangman_server_url)
+
+    page.get_by_role("button", name="a").click()
+    page.get_by_role("button", name="b").click()
+    page.get_by_role("button", name="c").click()
+
+    expect(page.get_by_role("button", name="Neues Spiel")).to_be_visible()
+    assert page.locator("span.letters", has_text="_").count() == 0
+    assert page.locator("img").get_attribute("src") == "image_0.png"
+
+
+def test_hangman_failed_game(page, monkeypatch, hangman_server_url):
+    hangman_api.games.clear()
+    monkeypatch.setattr(hangman_api.random, "randrange", lambda _n: 222222)
+    monkeypatch.setattr(hangman_api.random, "choice", lambda _words: "z")
+
+    _open_hangman_page(page, hangman_server_url)
+
+    for letter in "abcdef":
+        page.get_by_role("button", name=letter).click()
+
+    expect(page.get_by_role("button", name="Neues Spiel")).to_be_visible()
+    assert page.locator("img").get_attribute("src") == "image_6.png"
+    assert page.get_by_role("button", name="a").is_disabled()

wau-0.1.0/tests/test_hangman_example.py

@@ -0,0 +1,71 @@
+from werkzeug.test import Client
+
+from examples.hangman import hangman_api
+from wau import API
+
+
+def test_optional_request_and_readable_placeholders():
+    api = API()
+
+    @api.PUT("/sum/{value:int}")
+    def add(value, inc: int):
+        return {"total": value + inc}
+
+    client = Client(api)
+    response = client.put("/sum/7", json={"inc": 5})
+
+    assert response.status_code == 200
+    assert response.get_json() == {"total": 12}
+
+
+def test_typed_url_placeholder_rejects_invalid_type():
+    api = API()
+
+    @api.GET("/items/{item_id:int}")
+    def get_item(item_id):
+        return {"item_id": item_id}
+
+    client = Client(api)
+    response = client.get("/items/not-a-number")
+
+    assert response.status_code == 404
+
+
+def test_simple_wrapper_rejects_unexpected_body():
+    api = API()
+
+    @api.POST("/ping")
+    def ping():
+        return "pong"
+
+    client = Client(api)
+    response = client.post("/ping", data="{}")
+
+    assert response.status_code == 415
+
+
+def test_hangman_works_with_wau(monkeypatch):
+    hangman_api.games.clear()
+
+    monkeypatch.setattr(hangman_api.random, "randrange", lambda _n: 424242)
+    monkeypatch.setattr(hangman_api.random, "choice", lambda _words: "abc")
+
+    client = Client(hangman_api.api)
+
+    create = client.post("/api/hangman/")
+    assert create.status_code == 200
+    game = create.get_json()
+    assert game["game_id"] == 424242
+    assert game["word_length"] == 3
+    assert game["guesses_left"] == 6
+
+    correct = client.put("/api/hangman/424242", json={"letter": "a"})
+    assert correct.status_code == 200
+    assert correct.get_json() == {"letter_found": True, "positions": [0]}
+
+    wrong = client.put("/api/hangman/424242", json={"letter": "z"})
+    assert wrong.status_code == 200
+    assert wrong.get_json() == {"letter_found": False, "guesses_left": 5}
+
+    delete = client.delete("/api/hangman/424242")
+    assert delete.status_code == 200

wau-0.1.0/tests/test_todo_app_e2e.py

@@ -0,0 +1,24 @@
+import urllib.parse
+
+from playwright.sync_api import expect
+
+
+def test_todo_app_cross_origin_e2e(page, todo_frontend_url, todo_backend_url):
+    api_query = urllib.parse.quote(todo_backend_url, safe=":/")
+    page.goto(f"{todo_frontend_url}/todo_client.html?api={api_query}")
+
+    expect(page.get_by_role("heading", name="Todos")).to_be_visible()
+    expect(page.locator("li")).to_have_count(3)
+    expect(page.get_by_text("Abwaschen")).to_be_visible()
+
+    page.get_by_placeholder("New todo").fill("Milch kaufen")
+    page.get_by_role("button", name="Save").click()
+
+    new_item = page.locator("li", has_text="Milch kaufen")
+    expect(new_item).to_be_visible()
+    new_item.get_by_role("button", name="Done").click()
+
+    expect(new_item.locator("span.strike")).to_have_text("Milch kaufen")
+    new_item.get_by_role("button", name="Delete").click()
+
+    expect(page.locator("li", has_text="Milch kaufen")).to_have_count(0)

wau-0.1.0/wau.egg-info/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: wau
+Version: 0.1.0
+Summary: Web API Utils
+Author: Marco Schmalz
+License-Expression: LGPL-3.0-or-later
+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: 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 to provide a simple and consistent interface for writing APIs in Python. `wau` is built for educational purposes and is not intended for production use. It is opinionated, as it only supports JSON as data format. It uses simple type annotations to define the expected input and output of the API endpoints. Common tasks as authentication, CORS and server-sent events are supported by default.
+
+## Installation
+
+Install from PyPI:
+
+```powershell
+pip install wau
+```
+
+or with uv:
+
+```powershell
+uv add wau
+```
+
+## Testing
+
+Test dependencies are separated from runtime dependencies in `pyproject.toml`
+using the `test` dependency group.
+
+Run the test suite:
+
+```powershell
+uv run --group test python -m pytest -q
+```
+
+Run doctests:
+
+```powershell
+uv run --group test python -m doctest .\wau.py
+```
+
+## Publishing
+
+Build package artifacts:
+
+```powershell
+uv build
+```
+
+Validate metadata and README rendering:
+
+```powershell
+uvx twine check dist/*
+```
+
+Upload to TestPyPI first:
+
+```powershell
+uv publish --publish-url https://test.pypi.org/legacy/
+```
+
+Then publish to PyPI:
+
+```powershell
+uv publish
+```
+
+## 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.

wau-0.1.0/wau.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+wau.py
+tests/test_auth_exempt.py
+tests/test_cors_same_host.py
+tests/test_hangman_e2e.py
+tests/test_hangman_example.py
+tests/test_todo_app_e2e.py
+wau.egg-info/PKG-INFO
+wau.egg-info/SOURCES.txt
+wau.egg-info/dependency_links.txt
+wau.egg-info/requires.txt
+wau.egg-info/top_level.txt

wau-0.1.0/wau.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

wau-0.1.0/wau.egg-info/requires.txt

@@ -0,0 +1,3 @@
+dataset>=2.0.0
+pyjwt>=2.13.0
+werkzeug>=3.1.8

wau-0.1.0/wau.egg-info/top_level.txt

@@ -0,0 +1 @@
+wau