Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/returnstring/govyn
A tiny framework for writing async HTTP APIs in typed Python
https://github.com/returnstring/govyn
async http json openapi python
Last synced: 23 days ago
JSON representation
A tiny framework for writing async HTTP APIs in typed Python
- Host: GitHub
- URL: https://github.com/returnstring/govyn
- Owner: returnString
- License: mit
- Created: 2020-08-03T11:10:28.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-03-06T01:19:01.000Z (almost 2 years ago)
- Last Synced: 2024-11-08T10:15:12.695Z (3 months ago)
- Topics: async, http, json, openapi, python
- Language: Python
- Homepage:
- Size: 117 KB
- Stars: 2
- Watchers: 2
- Forks: 1
- Open Issues: 8
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# govyn
 [](https://pypi.org/project/govyn) [](https://codecov.io/gh/returnString/govyn)
A tiny framework for writing async HTTP APIs in typed Python.
> **govyn** (verb) - ask, inquire, query, question, request ([Cornish Dictionary](https://www.cornishdictionary.org.uk/#govyn))
# Features
- Async everywhere!
- Method params as query string arguments
- Dataclasses as request bodies
- Authentication with principals and privileges
- OpenAPI support with built-in routes:
- `/openapi/schema`: OpenAPI v3 schema as JSON
- `/openapi/swagger`: embedded [Swagger UI](https://swagger.io/tools/swagger-ui/) page for testing
- `/openapi/redoc`: embedded [Redoc](https://redoc.ly/redoc) documentation page
- Prometheus metrics support
# Example
```python
from dataclasses import dataclass
from typing import List
from govyn import run
@dataclass
class AddRequest:
numbers: List[int]
@dataclass
class Response:
result: int
class CalculatorAPI:
# run initialisation tasks, e.g. connecting to a database
async def startup(self) -> None:
pass
# be a good citizen and dispose of things appropriately
async def shutdown(self) -> None:
pass
# get_ methods take a query string
# callers will receive a 400 Bad Request if they supply invalid values
async def get_add(self, a: int, b: int) -> Response:
return Response(a + b)
# post_ methods take a JSON request body
# also type-checked according to the dataclass definition
async def post_add(self, req: AddRequest) -> Response:
return Response(sum(req.numbers))
run(CalculatorAPI())
```
Try out the built-in Swagger UI on this [example Heroku deployment](https://govyn-demo.herokuapp.com/openapi/swagger), built from source available in the [govyn-demo](https://github.com/returnString/govyn-demo) repository!
Or, run the server locally and hit it with curl:
```bash
> curl "http://localhost/add?a=10&b=32"
{"result": 42}
> curl "http://localhost/add" -d '{ "numbers": [ 1000, 300, 30, 7 ] }'
{"result": 1337}
```
# Installation
```bash
# from PyPI
pip install govyn
# or directly from Git
pip install git+ssh://[email protected]/returnString/govyn.git
```