A python microservice framework


Quick start
Project files
OpenAPI specification
API objects
Server code
Deployment pipeline
Docker packaging
JWT authentication
Error handling
Asynchronous execution
Database serialisation


pymacaron is a python microservice framework based on Flask, OpenAPI, pydantic, docker, Celery, AWS and GCP.

PyMacaron aims at abstracting away all the scaffholding of setting up a Flask microservice, its routes and its deployment pipeline. The only code you should have to write is the python method for each API endpoint of your microservice.

Core features

OpenAPI specifications

At the core of pymacaron lies your API definitions, in the form of OpenAPI yaml files.

Each OpenAPI file describes a set of API endpoints, the parameters they take and the objects they return.

REST and json

Pymacaron requires your API to consume json-encoded or form-encoded data, and produce json results.

Autogenerated Flask code

A Pymacaron server is simply a Flask server whose routes are automatically generated based on their OpenAPI definitions.

More details here.

Endpoints that take and return python objects

Pymacaron converts the body of an API request into a pymacaron model object.

This pymacaron model object is passed to the python method bound to the API endpoint, together with other query parameters.

The endpoint method returns a different pymacaron model, that gets serialized to json and converted into a Flask Response.

More details here and here.

JWT authentication

Pymacaron supports JWT authentication by default, on a per-endpoint basis.

More details here.

Deployment pipeline

Pymacaron comes with a deployment pipeline that packages the service as a docker image and deploys it to Amazon Beanstalk, Google Kubernetes or Google Cloud Run.

Asynchronous task execution

Pymacaron has optional builtin support for executing python code asynchronously, based on Celery and Redis.

More details here.

Blackbox testing framework

Pymacaron comes with a TestCase extension aimed at testing API endpoints, together with a custom nosetest wrapper.

More details here.

Object persistence

Object persistence is achieved by making pymacaron models inherit from a class that handles persistence and serialisation. pymacaron-dynamodb does that with Amazon’s DynamoDB.