Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/yezz123/yasgi

yasgi is a tiny ASGI framework ✨
https://github.com/yezz123/yasgi

asgi framework http python requests uvicorn websocket

Last synced: about 1 month ago
JSON representation

yasgi is a tiny ASGI framework ✨

Awesome Lists containing this project

README

        


Yasgi framework a tiny, small, easy to learn, fast to code ⚡️




Test


Coverage


Package version


Supported Python versions

Yasgi is a tiny, small (high-performance), web framework for building APIs with Python 3.9+ using orjson.

The key features are:

* **Tiny**: Small size and performance.
* **Fewer bugs**: Reduce about 40% of human (developer) induced errors.
* **Intuitive**: Great editor support. Completion everywhere. Less time debugging.
* **Easy**: Designed to be easy to use, Play and Plug.
* **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs.

## Installation

```console
$ pip install yasgi

---> 100%
```

You will also need an ASGI server, for production such as Uvicorn or Hypercorn.

```console
$ pip install "uvicorn[standard]"

---> 100%
```

## Example

### Create it

* Create a file `main.py` with:

```py
from yasgi import YASGI, Routing

app = YASGI(content_type="text/html")

@Routing("/endpoint", methods=["GET", "POST"])
async def endpoint(Request, Response):
# set response header
Response.add_header("X-header", "hello")
# set response cookie
Response.set_cookie("cookie_from_server", "384")
# set response body
return "hello world"
```

Now you should run it!

### Run it

Run the server with:

```console
$ uvicorn main:app --reload

INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [28720]
INFO: Started server process [28722]
INFO: Waiting for application startup.
INFO: Application startup complete.
```

The command `uvicorn main:app` refers to:

* `main`: the file `main.py` (the Python "module").
* `app`: the object created inside of `main.py` with the line `app = YASGI()`.
* `--reload`: make the server restart after code changes. Only do this for development.

### Initializing

```py
from yasgi import YASGI

application = YASGI(content_type="application/json", allow="*", charset="UTF-8")

```

#### ASGI parameters

* `content_type` - specifies the default content type of generated responses (optional, default: `application/json`)
* `charset` - specifies the default charset generated responses (optional, default: `UTF-8`)
* `allow` - specifies global setting for `Access-Control-Allow-Origin` header - can be overwrite by passing that header to response headers (optional, default `None` - for public API should be set to `*`)

### Routing

#### Routers parameters

* `endpoint` - object should contain str or regex Pattern to match request path (mandatory)
* `type` - defines that routed is serving HTTP or WebSocket protocol (possible values: `http`, `websocket`; default: `http`)
* `methods` - list of HTTP methods to match request method - higher priority than method (optional, default: [`GET`], should be only be specified on `http` type routes)
* \*kwargs - other arguments - can be accessed by middleware in states `routed` and `end`
* `content-type`

#### Usage

Route is used as a decorator callable object you want to use as router method.
Router method takes two mandatory arguments `Request` and `Response` (explained below in a separate section).
Router method can also take variables from router regex match (if used).

#### HTTP Examples

```py
import re
from yasgi import Routing

# simple route
@Routing("/endpoint", method="GET")
# simple route method
async def routed_method_1(request, response):
# response return without status code & mime type
return "Response from route 1"

# re package import needed
@Routing(re.compile("/endpoint/(\d+)$"), methods=["GET", "POST"])
# regex route, with multiple methods
async def routed_method_2(request, response, number):
# full response return
return f"Response from route - url_number is: {number}", "200 OK", "text/html"

@Routing("/endpoint3", methods=["GET", "POST"])
#simple route, with multiple methods
async def routed_method_2(request, response):
# alternatively can be called response method set to set response
response.set("Response by set")

```

### Raise HTTP status

Raise HTTPStatus is used to raise HTTP status code, and optional message.

```py
from http import HTTPStatus
from yasgi import Routing

@Routing("/raise_endpoint", methods=["POST"])
async def routed_method_2(request, response):
if not request.data:
raise HTTPStatus("400 BAD REQUEST", "400 BAD REQUEST")
return "data sent"
```

### Request & Response objects

Instances of these object are given to every function that is called with `@Routing` decorator.

```py
from yasgi import Routing

@Routing("/endpoint", method="GET")
async def endpoint(Request, Response):
# instances of Request and Response objects
pass
```

#### Request items and methods (HTTP)

* `method` - request method (GET, POST etc.) : read only
* `path` - request path: read only
* `query_params` - `dict` of query_string parameters
* `data` - request parsed data (json, -www-form-urlencoded, multipart/form-data) : read only
* `headers` - HTTP headers : read only (may contain `content_length` and `content_type` in post requests)
* `cookies` - dict contains `SimpleCookie` object of every cookie loaded
* `scope` - raw asgi scope object
* `event` - raw asgi event object

#### Response items and methods (HTTP)

* `content_type` - response content-type : read only - can be specified in route
* `charset` - response encoding; default: `UTF-8`
* `headers` - `list` of response headers:
* `redirect(location, status)` - redirects response to (`location`, `status` if not provide is set to `302`)
* `set_cookie(name, value, expires=None, maxAge=None, **kwargs)` - adds cookie to response with obvious parameters, you can alow add additional arguments (`kwargs`) such as `Domain`, `Path`, `Secure`, `HttpOnly`
* `add_header(name, value)` - adds header to response
* `process(data, status=200)` - allow to manual process response

## Development 🚧

### Setup environment 📦

You should create a virtual environment and activate it:

```bash
python -m venv venv/
```

```bash
source venv/bin/activate
```

And then install the development dependencies:

```bash
# Install Flit
pip install flit

# Install dependencies
flit install --symlink
```

### Run tests 🌝

You can run all the tests with:

```bash
bash scripts/test.sh
```

> Note: You can also generate a coverage report with:

```bash
bash scripts/test_html.sh
```

### Format the code 🍂

Execute the following command to apply `pre-commit` formatting:

```bash
bash scripts/format.sh
```

Execute the following command to apply `mypy` type checking:

```bash
bash scripts/lint.sh
```

## License

This project is licensed under the terms of the [GNU GENERAL PUBLIC LICENSE Version 3](https://www.gnu.org/licenses/gpl-3.0.en.html).