USPolis Backend

Table of Contents

1. Stack
2. Docs
3. Setup
4. Run
5. Develop
6. Test

Stack

Here we have the tecnologies used on backend:

• FastAPI - Python async micro framework built on Starlette and PyDantic.
• SQL Model - Python library for interacting with SQL databases, powered by PyDantic and SQLAlchemy.
• PostgreSQL - Open source object-relational database.

Docs

You can see a complete documentation at USPolis-Admin Wiki, there you will find our architecture, diagrams, bussiness rules, descriptions and more.

Setup

This codebase was written for Python 3.12 and above. Don't forget about a venv as well, in this project we use Poetry for dependency management.

First we'll need to install poetry using pipx

pipx install poetry

After installing poetry now we will install only the core dependencies

poetry install --without test,dev

There are other settings in server/config.py and the included .env file, you can see all enviroment variables used at .env.example file.

Assuming you've created and setted the '.env' file, everything should run as-is if there is a local PostgreSQL instance running (see the docs for a complete step by step to how set the enviroment).

Run

This sample uses uvicorn as our ASGI web server. This allows us to run our server code in a much more robust and configurable environment than the development server. For example, ASGI servers let you run multiple workers that recycle themselves after a set amount of time or number of requests.

uvicorn server.main:app --reload --port 8080

Your API should now be available at http://localhost:8080

Develop

This codebase uses mypy for type checking and ruff for litting and formatting.

Install both with the dev tag:

poetry install --with dev

*This is also install some type libraries from other dependencies for mypy

First make sure that .venv is active (you can use poetry shell):

  source .venv/bin/activate

To run the type checker (if you use VSCode you can install MyPy extension, this will be very usefull):

mypy server

To run the linter and code formatter:

ruff check server
ruff format server

To run the server in develop mode:

python wsgi.py

Test

The sample app also comes with a test suite to get you started, we use Pytest for testing.

Make sure to install test dependencies before trying to run the tests:

poetry install --with test

The tests need access to a PostgreSQL database that will be cleared at the end of each test (look at .env file and set the test databse url and test database name).

Then just run the test suite.

pytest

Tip

If you use VSCode install Python Test Explorer extension, make sure that you are running only one time each test, otherwise the tests must be fail.