mycroforge/docs

General introduction

What is MycroForge?

MycroForge is an opinionated CLI tool that is meant to facilitate the development of FastAPI & SQLAlchemy based backends. It provides a command line interface that allows users to generate a skeleton project and other common items like database entities, migrations, routers and even basic CRUD functionality. The main purpose of this tool is to generate boilerplate code and to provide a unified interface for performing recurrent development activities.

Generating a project

To generate a project you can run the following command.

m4g init <name>

Description:
  Initialize a new project

Usage:
  m4g init <name> [options]

Arguments:
  <name>  The name of your project

Options:
  --without <api|db|git>  Features to exclude
  -?, -h, --help          Show help and usage information

Running this command will generate the following project structure.

📦<project_name>
 ┣ 📂.git
 ┣ 📂.venv
 ┣ 📂api
 ┃ ┗ 📂routers
 ┃ ┃ ┗ 📜hello.py
 ┣ 📂db
 ┃ ┣ 📂engine
 ┃ ┃ ┗ 📜async_session.py
 ┃ ┣ 📂entities
 ┃ ┃ ┗ 📜entity_base.py
 ┃ ┣ 📂versions
 ┃ ┣ 📜README
 ┃ ┣ 📜env.py
 ┃ ┣ 📜script.py.mako
 ┃ ┗ 📜settings.py
 ┣ 📜.gitignore
 ┣ 📜alembic.ini
 ┣ 📜db.docker-compose.yml
 ┣ 📜m4g.json
 ┣ 📜main.py
 ┗ 📜requirements.txt

Let's go through these one by one.

.git

The project is automatically initialised with git by the m4g init command. If you don't want to use git you can run m4g init <name> --without git.

.venv

To promote isolation of Python dependencies, the project is initialized with a virtual environment by default.

api/routers/hello.py

This file defines a basic example router, which is imported and mapped in main.py.

db/engine/async_session.py

This file defines the async_session function, which can be used to asynchronously connect to a database.

db/entities/entity_base.py

This is the automatically generated base class that all database entities will inherit from. SQLAlchemy requires a base entity class to properly function.

db/entities/versions

This is where the generated database migrations will be kept.

db/README

This README file is automatically generated by the alembic init command.

db/env.py

This is the database environment file that is used by alembic to interact with the database. If you take a close look at the imports, you'll see that the file has been modified to include the entity metadata, i.e. EntityBase.metadata and you should also notice that the DbSettings class is used to get the connectionstring. Any time you generate a new database entity or create a many-to-many relation between two entities, this file will also be modified.

db/script.py.mako

This file is automatically generated by the alembic init command.

db/settings.py

This file defines a class that is responsible for retrieving the connectionstring.

.gitignore

The default .gitignore file/

alembic.ini

The alembic ini file

db.docker-compose.yml

A docker compose file for running a database locally.

m4g.json

The m4g config file, this file contains some configs that are used by the CLI, for example the ports to map to the API and database.

main.py

The entrypoint for the application.

requirements.txt

The requirements file containing the Python dependencies.