Skip to main content

A powerful tool to enable super fast module-to-API transformations. Learn in minutes, implement in seconds. Batteries included.

Project description


PyPI - Version PyPI - Downloads

A powerful tool to enable super fast module-to-API transformations. Learn in minutes, implement in seconds. Batteries included.

Tests Workflow Linters Workflow


symmetric is no longer being maintained. But don't worry! Its spiritual successor, asymmetric, has an essentially identical API, and is faster, better designed, and has a bunch of new features. The symmetric token is the only feature present in symmetric that won't be part of asymmetric. Other than that, you can port your code performing a search and replace, replacing all the appearances of symmetric for asymmetric. Thank you for being a part of this project! Hope to see you around asymmetric!

Why Symmetric?

Raw developing speed and ease of use, that's why. symmetric is based on Flask! While Flask 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 symmetric 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 Flask (it can also be used to build an API from scratch really fast). With symmetric, 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.
  • Native support for an authentication token on a per-endpoint basis.
  • Auto-generated OpenAPI Specification and Markdown documentation files for your API.

The complete documentation is available on the official website.


Install using pip!

pip install symmetric


Running the development server

To start the development server, just run:

symmetric run <module>

Where <module> is your module name (in the examples, we will be writing in a file named, so the module name will be just module). A Flask instance will be spawned immediately and can be reached at by default. We don't have any endpoints yet, so we'll add some later. Do not use this in production. The Flask server is meant for development only. Instead, you can use any WSGI server to run the API. For example, to run the API using gunicorn, you just need to run gunicorn module:symmetric and a production ready server will be spawned.

Defining the API endpoints

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

from symmetric import symmetric

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

The decorator recieves 4 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), the response_code argument (the response code of the endpoint if everything goes according to the plan. Defaults to 200) and the auth_token argument (a boolean stating if the endpoint requires authentication using a symmetric token. Defaults to False).

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:

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

Run symmetric run module and send a GET request to 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:

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, now using the requests module.

import requests

payload = {
    "a": 48,
    "b": 21
response ="", json=payload)

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!

ReDoc Documentation

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?


Clone the repository:

git clone

cd symmetric

Recreate environment:


. .venv/bin/activate

Test install:

poetry install  # will also install the symmetric CLI

Run the tests:

python -m unittest


Download files

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

Source Distribution

symmetric-3.4.3.tar.gz (17.2 kB view hashes)

Uploaded source

Built Distribution

symmetric-3.4.3-py3-none-any.whl (18.0 kB view hashes)

Uploaded py3

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