mycroforge/readme/README.md

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 m4g init command will initialize new projects with git by default. If you don't want to use git you can pass the option --without git to m4g init.

.venv

To promote isolation of Python dependencies, new projects are initialized with a virtual environment by default. TODO: This is a good section to introduce the m4g hydrate command.

api/routers/hello.py

This file defines a basic example router, which is imported and mapped in main.py. This router is just an example and can be removed or modified at you discretion.

db/engine/async_session.py

This file defines the async_session function, which can be used to open an asynchronous session to a database.

db/entities/entity_base.py

This file contains an automatically generated entity base class that derives from the DeclarativeBase. All entities must inherit from this class, so that SQLAlchemy & alembic can track them. The entities directory is also where all newly generated entities will be stored.

db/versions

This is where the generated database migrations will be stored.

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 closer look at the imports, you'll see that the file has been modified to assign EntityBase.metadata to a variable called target_metadata, this will allow alembic to track changes in your entities. You'll also find 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 to include the generated classes.

db/script.py.mako

This file is automatically generated by the alembic init command.

db/settings.py

This file defines the DbSettings class, that is responsible for retrieving the database connectionstring. You will probably want to modify this class to retrieve the connectionstring from a secret manager at some point.

.gitignore

The default .gitignore file that is generated by the m4g init command. Modify this file at your discretion.

alembic.ini

This file is automatically generated by the alembic init command.

db.docker-compose.yml

A docker compose file for running a database locally.

m4g.json

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. When generating entities, many-to-many relations or routers, this file will be modified to include the generated files.

requirements.txt

The requirements file containing the Python dependencies. TODO: introduce the m4g install & m4g uninstall commands.

Scripting

TODO: Dedicate a section to scripting