starlette-decoRouter 1.0.0

FastAPI style decorators for starlette ASGI

starlette_decoRouter

A FastAPI style router for Starlette.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • The good
   • The less good
   • The best of both
2. Installation
3. Usage
4. Contact
5. Acknowledgments

About The Project

FastApi is a great tool for developping API's in a quick and easy way. In their own words:

FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+ based on standard Python type hints.

It is build using starlette which is in their own words:

a lightweight ASGI framework/toolkit, which is ideal for building high performance asyncio services.

The good

One of the things that I love about FastAPI is how easy it is to setup different routes. Just use a decorator above the function that corresponds to that route and done. It's easy to see which route corresponds to which function and vice versa.

(back to top)

The less good

In starlette you first declare different functions and then at the end of the file you map the path, allowed HTTP methods and endpoint function together.

This makes it easy to make mistakes as there is no way to immediately know which endoint corresponds to a certain function, unless you check the routes at the end of the file. They might not even be declared in that file at all.

(back to top)

The best of both

decoRouter auto generates your routes for you based on decorators, just like FastAPI. The downside is that you have to import an extra module, but the added bonus of easier to read and maintain code is certainly worth it.

(back to top)

Installation

You can simply install the module using pip.

• > pip install decorouter

(back to top)

Usage

To use decoRouter you will need to know how starlette works. decoRouter will not create an app for you, it will only generate the routes.

For more info regarding starlette, please refer to the Documentation

Example

below is a basic example.
There is one endpoint '/' which only accepts GET requests, and returns {'hello': 'world'}.

• example.py:

from starlette.applications import Starlette
from starlette.responses import JSONResponse
from decoRouter import Router

router = Router()

@router.get('/')
async def homepage(request):
    return JSONResponse({'hello': 'world'})


app = Starlette(routes=router)

Then run the application...

$ uvicorn example:app

---

Multiple HTTP methods

It's also possible to accept multiple HTTP methods for one endpoint.
Below you can see one endpoint '/' which accepts both POST and PUT requests.

from starlette.applications import Starlette
from starlette.responses import JSONResponse
from decoRouter import Router

router = Router()

@router.PUT()
@router.POST('/')
async def homepage(request):
    return JSONResponse({'hello': 'world'})


app = Starlette(routes=router)

As you can see only the last decorator has a path. It is not necessary to define it multiple times as only the last one will be used.

For example:

@router.PUT()
@router.POST('/')
@router.POST('/home')
async def home(request):
    pass

Above, the second decorator will do nothing.
This will result in the endpoint '/home' accepting both PUT and POST requests. The endpoint '/' will return a 404.

This means that there is ONE endpoint per function. You can't add multiple endpoints to the same function or vice versa.

---

Multiple endpoints

Unique endpoints are created based on the function name.
The function names will have no influence over the path of the endpoint. If a function with a duplicate name is created it will NOT override the original one. This this means.
Duplicate function names will be ignored, only the first one will be used.

@router.get('/')
async def home(request):
    pass

@router.get('/home')
async def home(request):
    pass

The above will result in only one endpoint: '/'.
The second occurence of home will be ignored

---

Extra

starlette does not check for correct HTTP methods, so neither does decoRouter. Methods are case insensitive. router.get() is the same as router.GET() or even router.GeT(). And since there are no checks, things like router.ilasdfggb() are perfectly fine and will not result in an error. Keep this in mind while debugging.

(back to top)

Contact

Thomas - @TEeckhout - LinkedIn - [e-mail]
Project Link: https://github.com/MrPigss/DecoRouter

(back to top)

Acknowledgments

Thank you

• Starlette
• FastAPI
• Img Shields

(back to top)

PS.

Apparently starlette still supports using decorators but these are not documented anywhere since they are deprecated since 0.13.0, see changelog.