141 lines
4.4 KiB
Markdown
141 lines
4.4 KiB
Markdown
# 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 |