Skip to main content

A powerful tool to enable super fast [async] module-to-API transformations. Learn in minutes, implement in seconds.

Project description

Asymmetric

PyPI - Version

A powerful tool to enable super fast [async] module-to-API transformations. Learn in minutes, implement in seconds.

Linters Workflow

Why Asymmetric?

Raw developing speed and ease of use, that's why. asymmetric is based on Starlette ✨! While Starlette is a powerful tool to have, getting it to work from scratch can be a bit of a pain, especially if you have never used it before. The idea behind asymmetric is to be able to take any module already written and transform it into a working API in a matter of minutes, instead of having to design the module ground-up to work with Starlette (it can also be used to build an API from scratch really fast). With asymmetric, you will also get some neat features, namely:

  • Auto logging.
  • Server-side error detection and exception handling.
  • Auto-generated /docs endpoint for your API with interactive documentation. [UNDER CONSTRUCTION]
  • Auto-generated OpenAPI Specification documentation files for your API. [UNDER CONSTRUCTION]

The complete documentation is available on the official website.

Installing

Install using pip!

pip install asymmetric

Usage

Running the development server

To start a server, choose your favorite ASGI server and target the asymmetric object!

uvicorn run:<module>

Where <module> is your module name (in the examples, we will be writing in a file named module.py, so the module name will be just module). A Starlette instance will be spawned immediately and can be reached at http://127.0.0.1:8000 by default. We don't have any endpoints yet, so we'll add some later.

Defining the API endpoints

The module consists of a main object called asymmetric, which includes an important element: the router decorator. Let's analyze it:

from asymmetric import asymmetric

@asymmetric.router("/some-route", methods=["post"], response_code=200)

The decorator recieves 3 arguments: the route argument (the endpoint of the API to which the decorated function will map), the methods argument (a list of the methods accepted to connect to that endpoint, defaults in only POST requests) and the response_code argument (the response code of the endpoint if everything goes according to the plan. Defaults to 200).

Now let's imagine that we have the following method:

def some_function():
    """Greets the world."""
    return "Hello World!"

To transform that method into an API endpoint, all you need to do is add one line:

@asymmetric.router("/sample", methods=["get"])
def some_function():
    """Greets the world."""
    return "Hello World!"

Run uvicorn run:module and send a GET request to http://127.0.0.1:8000/sample. You should get a Hello World! in response! (To try it with a browser, make sure to run the above command and click this link).

But what about methods with arguments? Of course they can be API'd too! Let's now say that you have the following function:

def another_function(a, b=372):
    """
    Adds :a and :b and returns the result of
    that operation.
    """
    return a + b

To transform that method into an API endpoint, all you need to do, again, is add one line:

@asymmetric.router("/add")
def another_function(a, b=372):
    """
    Adds :a and :b and returns the result of
    that operation.
    """
    return a + b

Querying API endpoints

To give parameters to a function, all we need to do is send a json body with the names of the parameters as keys. Let's see how! Run symmetric run module and send a POST request (the default HTTP method) to http://127.0.0.1:8000/add, now using the httpx module.

import httpx

payload = {
    "a": 48,
    "b": 21
}
response = httpx.post("http://127.0.0.1:8000/add", json=payload)
print(response.json())

We got a 69 response! (48 + 21 = 69). Of course, you can return dictionaries from your methods and those will get returned as a json body in the response object automagically!

With this in mind, you can transform any existing project into a usable API very quickly!

What about async?

Given that the underlying framework is Starlette, you can use async to define your methods, no problem! Here's an example:

@asymmetric.router("/another-add")
async def another_async_function(a, b=372):
    """
    Adds :a and :b asynchronously and returns the
    result of that operation.
    """
    return a + b

ReDoc Documentation

[UNDER CONSTRUCTION]

By default, you can GET the /docs endpoint (using a browser) to access to interactive auto-generated documentation about your API. It will include request bodies for each endpoint, response codes, authentication required, default values, and much more!

Tip: Given that the ReDoc Documentation is based on the OpenAPI standard, using type annotations in your code will result in a more detailed interactive documentation. Instead of the parameters being allowed to be any type, they will be forced into the type declared in your code. Cool, right?

Developing

Clone the repository:

git clone https://github.com/daleal/asymmetric.git

cd asymmetric

Recreate environment:

./environment.sh

. .venv/bin/activate

Test install:

poetry install

Resources

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

asymmetric-0.0.1.tar.gz (10.3 kB view details)

Uploaded Source

Built Distribution

asymmetric-0.0.1-py3-none-any.whl (9.5 kB view details)

Uploaded Python 3

File details

Details for the file asymmetric-0.0.1.tar.gz.

File metadata

  • Download URL: asymmetric-0.0.1.tar.gz
  • Upload date:
  • Size: 10.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/50.3.0 requests-toolbelt/0.9.1 tqdm/4.50.2 CPython/3.8.6

File hashes

Hashes for asymmetric-0.0.1.tar.gz
Algorithm Hash digest
SHA256 877b2f48febfb68e5c300b7b7c0c0035a44055a6c8791121cae33807b840e659
MD5 57d3ed8591796a5ac8bf66bc7cd87385
BLAKE2b-256 f0c756d28859695bfce620d2012f338bafc173dabb63241a399d123372105b7e

See more details on using hashes here.

File details

Details for the file asymmetric-0.0.1-py3-none-any.whl.

File metadata

  • Download URL: asymmetric-0.0.1-py3-none-any.whl
  • Upload date:
  • Size: 9.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/50.3.0 requests-toolbelt/0.9.1 tqdm/4.50.2 CPython/3.8.6

File hashes

Hashes for asymmetric-0.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 a366d5385ca109023467720f3f1abc25dae3d84cee80974b3437ad1452e3b3a4
MD5 545e2223b7ade9166fa9411dd5c6fbd5
BLAKE2b-256 13c25d599f57961a854443603a60ce179c3dd140d7b1c81686a720712e874383

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page