yasgi 0.1.0

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

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

$ pip install yasgi

---> 100%

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

$ pip install "uvicorn[standard]"

---> 100%

Example

Create it

• Create a file main.py with:

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:

$ 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.

Initializing

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

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.

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.

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:

python -m venv venv/

source venv/bin/activate

And then install the development dependencies:

# Install Flit
pip install flit

# Install dependencies
flit install --symlink

Run tests 🌝

You can run all the tests with:

bash scripts/test.sh

Note: You can also generate a coverage report with:

bash scripts/test_html.sh

Format the code 🍂

Execute the following command to apply pre-commit formatting:

bash scripts/format.sh

Execute the following command to apply mypy type checking:

bash scripts/lint.sh

License

This project is licensed under the terms of the GNU GENERAL PUBLIC LICENSE Version 3.