Monster Spawner

📝 Table of Contents

• About
• Getting Started
• Usage
• Development
• Acknowledgments

🧐 About

Simple FastAPI application that manages Minecraft monsters. General purpose of me doing this at all, is to learn some new design patterns, while learning how to use FastAPI and SQLAlchemy together. In this example I wanted to extract and decouple service and domain layers of the application. Thus, some useful abstractions can be found in the domain folder. Since this is a very basic app, you can use it as a starting point for your own app.

Update

I've created another repositories under Microcraft organization, to proceed with implementing a little bit of Event-Driven Architecture. This repo obviously received an update to support publishing events, but I think I did a slightly better job in terms of DDD in the newer repos, so I highly encourage you to check those.

🏁 Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

To get started you need to have Docker installed and optionally Poetry, if you want to have virtual environment locally. All the needed commands are available via Makefile.

Installing

First, build the images.

make build

Then, you can just start the containers.

make up

After that, you should be able to see the output from the FastAPI server. It will be running on port 8002, so you can access the documentation via http://localhost:8002/api/docs.

🎈 Usage

There are also few useful commands to help manage the project.

If you have Poetry installed, you can run below command to have all the dependencies installed locally.

make install

In case you want to avoid installing anything locally, you can enter server container and run other commands from there.

make enter

After making changes to the models, there is an alembic command to create a new migration.

make makemigrations

There is also one to apply the migrations.

make migrate

The last command is actually being used every time before starting the server.

🔧 Development

To make development smoother, this project supports pre-commit hooks for linting and code formatting along with pytest for testing. All the configs can be found in .pre-commit-config.yaml and pyproject.toml files.

To install the hooks, run the following command.

pre-commit install

Then you can use the following to run the hooks.

make lint

There is also a command for running tests.

make test

pytest is configured to use database separated from the one that app uses - by default its the postgres one. Tests are also using different sessions to have a clean separation. You can check more fixtures in the conftest.py file, or the general configuration in the pytest.ini section.

🎉 Acknowledgements

To get more insights about design patters in Python i highly recommend Architecture Patterns with Python by Harry Percival and Bob Gregory.

I also strongly encourage to check out the ArjanCodes YouTube channel, where many Python concepts are explained.

A big inspiration for this project was SqlAlchemy 1.4 async ORM with FastAPI article by Piotr Rogulski.