This is a project template that can be used to start working on a new python application.
It contains examples of the core project files like Dockerfile and docker-compose.yaml
and shows the recommended project structure.
Please install docker engine and docker-compose or upgrade them to the most recent versions. If you’re not sure how to do this, please refer to https://docs.docker.com/engine/install/
Please find .env.example file in the root of the cloned repository, it can be used as a template
for making docker env file. Please copy it to .env and fill with relevant values.
If you are not sure which values need to be saved there, you can always contact
Maxim Vinogradov (@maximv) or Eric Detterman (@eric) in Slack.
cp .env.example .env
vim .env
The easiest way to run the application locally is using the docker compose command.
Please use the docker-compose.override.example-advanced.yaml file as an example for creating
a docker-compose.override.yaml. You can adjust it as needed; this file won’t be committed
to the repository, so you can safely store there any specific settings, like a local IP address
or the database server’s port.
Then all you need is to build the docker image and run containers:
docker compose up -d
Postgres server will be started automatically with docker compose command,
but the database will be empty. To begin working with the application,
you need to add various data to different tables:
docker compose exec db bash
su postgres
psql -d app -a -f /fixtures/admin-user.sql
psql -d app -a -f /fixtures/basic-data.sql
Please install pyenv and poetry or upgrade them to the most recent versions.
Here are the links where you can find information about installation process:
It is assumed that you’re using PyCharm IDE for development.
Mark src folder as a source root: right click -> Mark Directory as -> Sources Root.
If you would like to use the specific name for your new application instead of app
please replace all occurrences of app with the name of your new service (Shift + F6 in Pycharm)
Please ensure that the target python version is installed with pyenv. Then initialize a python environment with poetry:
poetry install
To execute binaries depending on python environment you need to use
poetry run command, e.g. poetry run alembic upgrade heads.
Alternatively, you may want to the activate virtual environment:
poetry shell
Execute poetry add command. It will add a new record to the pyproject.toml
and update poetry lock file. You can find extra details on this
at their documentation. Example:
poetry add pendulum@latest
Please note that poetry doesn’t sort the dependency list, but we prefer to keep it in the alphabetical order. So please re-order records in pyproject.toml after this:
poetry run toml-sort pyproject.toml --all --in-place
poetry run uvicorn app.api:app --host 0.0.0.0 --port 8000 --reload
Our main database management system is PostgreSQL.
If your service doesn’t depend on any database, then you can safely skip this section of README and drop all references to db-related things. If your service uses some shared database, then you likely don’t need to manage its structure, so you can delete all alembic-related stuff.
If your service uses its own database then you need to initialize it prior to the first launch of the application. Please run a container for PostgreSQL and exec there several commands:
docker-compose up -d db
docker exec -it <repo_name>_db_1 bash
su postgres
psql -c "CREATE USER <db_user> WITH PASSWORD '<db_password>';"
psql -c "CREATE DATABASE <db_name>;"
psql -c "GRANT ALL privileges ON DATABASE <db_name> TO <db_user>;"
psql -c "ALTER DATABASE <db_name> OWNER TO <db_user>;"
Once this is done please launch a container for the main app, it will automatically apply all necessary migrations.
Earlier we actively used Tortoise ORM because it works pretty fast. But then we switched back to SQLAlchemy because Tortoise ORM doesn’t have official support of CockroachDB.
This section needs extending.
To create a new migration please use alembic revision command:
poetry run alembic revision --autogenerate -m "Some Message"
To apply all pending migrations execute the upgrade command:
poetry run alembic upgrade head
We black to format the code and isort to ensure the import order. Their settings can be found
in pyproject.tome file. In most cases it’s enough to run these two commands to format your code:
isort src/app
black src/app
The project contains a set of helper functions for generating pydantic schemas for request payloads and responses, adding CRUD routes. Additionally, there is a CLI utility for generating schema definitions:
python utils/generate_schemas.py
You will be asked for the path to the module containing an SQLAlchemy model and its name. Then this utility will generate the python code for declaring necessary pydantic schemas.