freelancer / esapyi

A dockerized and production ready python API template with no setup required.

esapyi ·

A dockerized and production ready python API template with no setup required.

This project aims to provide a pre-configured python API server template based on the Flask python framework.

Table of Contents
Quickstart Guide
The Hitchhicker's Guide to api_boilerplate
Developer Guide

Quickstart guide

1. Ensure that you have docker installed on your system.
2. Clone this repository using git clone https://github.com/freelancer/esapyi.git
3. (Optional) Pick a new name for your project and run ./project_rename.sh "my_project_name"
4. Start the python server using ./run.sh dev

The Hitchhicker's Guide to api_boilerplate

This section will take you through the following

• Project Structure
• Writing versioned APIs (TODO)

Project Structure

api_boilerplate
├── app.py
├── config
│   ├── __init__.py
│   ├── local_development.py
│   ├── prod.py
│   └── testing.py
├── exceptions
├── handlers
├── healthcheck
├── models
├── utils
└── v1
    ├── exceptions
    ├── handlers
    ├── input_schemas.py
    ├── output_schemas.py

Developer Guide

This section goes through the various tools and procedures a developer would need when developing using this setup.

Contents

• Commands Quickstart: Getting the most out of the utility scripts
• Linting: The linter setup and now to customize it
• Testing: Getting the most out of the test setup
• Database Migrations: How to track and alter the database schema
• Production Deployment: The ideal way of running the production server

Commands Quickstart

All of the common development tasks that need to be performed are done through the run.sh script located at the root of the project. run.sh has the following commands

• run.sh dev - start the local db and python development server at port 8080
• run.sh prod - start the local db and the production uWSGI python server at port 8080
• run.sh lint - lint the entire project
• run.sh test - run the entire test suite for the project
• run.sh check - run the lint and test command in succession
• run.sh dev db - spin up and connect to the local dev database
• run.sh alembic - proxy to the alembic cli

Linting

This project uses 2 main linting programs

• pyright - a static type-checker
• ruff - a code quality checker

If you want to customize the lint configuration, modify the following files

• pyproject.toml - to customize the mypy setup
• pyproject.toml - to customize the ruff setup

Testing

This project uses the pytest framework for writing and maintaining unit tests.

• In order to configure pytest, use the pytest.ini file

The unit tests also spin up a dockerized MySQL database. Every run.sh test call will kill and re-create the database to ensure tests are running in a fresh environment.

There are 3 base test classes which you should extend when writing tests.

• BaseTestCase
  • An empty class that extends unittest.TestCase
• AppContextTestCase
  • A class makes a flask test client available at self.client
• DbContextTestCase
  • Waits for the database to become available if it's not
  • Re-sets the database after every test using alembic.

Database Migrations

This project uses alembic as a database migrations tool. This tool essentially acts as a version control for your database schema. Any changes that need to be made should be tracked and done through alembic.

Example: Adding a new column

Say we want to add a new column to our users table - first_name.
To do so, follow these steps

1. Modify the user model and add the first_name column

first_name = Column(Text, nullable=False)

2. Run the alembic command to autogenerate a revision
   • This command creates a new file under the migrations/versions folder which contains code to create this new column in the db

./run.sh alembic revision --autogenerate -m"add_fname_to_user"

3. Run the alembic command to upgrade the database

./run.sh alembic upgrade head

4. That's it! The user table in the local docker database now has a first_name column. Remember to commit the generated migration file to git.

Production Deployment

It is recommended that you deploy this API as a docker container on your production server. In order to help build this container there is a production ready dockerfile provided.

In production, the python app is run using uWSGI. The configuration for this uWSGI server is in uwsgi_prod_app_config.ini.