-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
acc5a9e
commit 217a288
Showing
1 changed file
with
238 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -3,3 +3,241 @@ | |
**Cosmic FastAPI** is a template for creating a [FastAPI](https://fastapi.tiangolo.com/) project following | ||
the [Cosmic Python](https://www.cosmicpython.com/) guidelines. | ||
|
||
## Content | ||
|
||
<!-- TOC --> | ||
|
||
* [Cosmic FastAPI](#cosmic-fastapi) | ||
* [Content](#content) | ||
* [Features](#features) | ||
* [Continuous Integration](#continuous-integration) | ||
* [Development Environment](#development-environment) | ||
* [Installing Poetry](#installing-poetry) | ||
* [Building the Development Environment](#building-the-development-environment) | ||
* [Running Local](#running-local) | ||
* [Running Tests](#running-tests) | ||
* [Updating Dependencies](#updating-dependencies) | ||
* [Recommended Readings](#recommended-readings) | ||
* [License](#license) | ||
* [Acknowledgements](#acknowledgements) | ||
|
||
<!-- TOC --> | ||
|
||
## About | ||
|
||
### Features | ||
|
||
This template includes `FastAPI` using the fastest `Pydantic V2` model validation. Designed for Event-Driven | ||
Architecture (EDA) and Domain-Driven Design (DDD). Providing a clean and simple structure to start a new project. With | ||
the addition of `pre-commit` hooks to ensure code quality. And ready to be used in a `CI/CD` GitHub Workflows pipeline. | ||
|
||
### Project Structure | ||
|
||
#### Environment Variables | ||
|
||
Variables prefixed with `FASTAPI_` are used to configure the API UI. | ||
|
||
| Name | Description | Default Value | | ||
|-----------------------------|---------------------|------------------| | ||
| FASTAPI_DEBUG | Debug Mode | False | | ||
| FASTAPI_PROJECT_NAME | Swagger Title | API GATEWAY | | ||
| FASTAPI_PROJECT_DESCRIPTION | Swagger Description | ... | | ||
| FASTAPI_PROJECT_LICENSE | License info | ... | | ||
| FASTAPI_PROJECT_CONTACT | Contact details | ... | | ||
| FASTAPI_VERSION | Application Version | template.version | | ||
| FASTAPI_DOCS_URL | Swagger Endpoint | /docs | | ||
|
||
Variables prefixed with `UVICORN_` are used to configure the server. | ||
|
||
| Name | Description | Default Value | | ||
|-------------------|-----------------------|---------------| | ||
| UVICORN_HOST | Server Host | '127.0.0.1' | | ||
| UVICORN_PORT | Server Port | 8000 | | ||
| UVICORN_LOG_LEVEL | Log Level | 'info' | | ||
| UVICORN_RELOAD | Enable/Disable Reload | False | | ||
|
||
### Recommended Directory Structure | ||
|
||
As our application gets bigger, we’ll need to keep tidying our directory structure. The layout of our project gives us | ||
useful hints about what kinds of object we’ll find in each file. We can use this to navigate our codebase more easily. | ||
|
||
```text | ||
. | ||
├── settings.py | ||
├── domain #(1) | ||
│ ├── commands.py | ||
│ ├── events.py | ||
│ ├── schemas.py | ||
│ └── models.py | ||
├── service_layer #(2) | ||
│ └── services.py | ||
├── adapters #(3) | ||
│ ├── orm.py | ||
│ └── repository.py | ||
├── entrypoints #(4) | ||
│ ├── __init__.py | ||
│ └── monitor.py | ||
└── tests | ||
├── __init__.py | ||
├── conftest.py | ||
├── unit | ||
├── integration | ||
└── e2e | ||
└── test_monitor.py | ||
``` | ||
|
||
- **(1)**. Domain, from Domain Driven Architecture. | ||
- **Commands**, from Command Query Responsibility Segregation (CQRS). Commands are the messages that change | ||
the state of the system. | ||
- **Events**, from Event Sourcing. Events are the messages that describe a change in the system. | ||
- **Schemas**, from FastAPI, data models or data structures that are used to define the shape or structure | ||
of data that your API receives or returns. | ||
- **Models**, represent the domain entities, business objects of interest. | ||
- **(2)**. The service layer will be distinguished. What is the difference between a domain service and a service layer? | ||
- Application service (our service layer) ts job is to handle requests from the outside world and to orchestrate an | ||
operation. | ||
- Domain Service. This is the name for a piece of logic that belongs in the domain model but doesn't sit naturally | ||
inside a stateful | ||
entity or value object. For example, if you were building a shopping cart application, you might choose to build | ||
taxation rules as a domain service. | ||
- **(3)**. Adapters, it comes from ports and adapters terminology. This will fill up with any other abstractions around | ||
external I/O. Strictly speaking, you would call these secondary adapters or driven adapters, or sometimes | ||
inward-facing adapters. | ||
- **(4)**. Entrypoints are the places we drive our application from. In the official ports and adapters terminology, | ||
these are adapters too, and are referred to as primary, driving, or outward-facing adapters. | ||
|
||
We may even consider splitting our models, schemas, events and commands into separate packages and files if they get too | ||
big. | ||
|
||
## Continuous Integration | ||
|
||
This project uses `make` as an adaptation layer. | ||
|
||
Run `make help` to see all available commands. | ||
|
||
## Development Environment | ||
|
||
### Installing Poetry | ||
|
||
This package uses poetry for dependency management. | ||
|
||
Install poetry in the system `site_packages`. DO NOT INSTALL IT in a virtual environment itself. | ||
|
||
To install poetry, run: | ||
|
||
```bash | ||
pip install poetry | ||
``` | ||
|
||
### Building the Development Environment | ||
|
||
1. Clone the repository | ||
|
||
```bash | ||
git clone "[email protected]/tomasanchez/cosmic-fastapi.git" | ||
``` | ||
2. Install dependencies | ||
|
||
```bash | ||
cd cosmic-fastapi && poetry install | ||
``` | ||
|
||
Note that poetry doesn't activate the virtual environment for you. You have to do it manually. | ||
Or prefix subsequent the commands with | ||
```bash | ||
poetry run | ||
``` | ||
You can view the environment that poetry uses with | ||
```bash | ||
poetry env info | ||
``` | ||
To activate run: | ||
```bash | ||
poetry shell | ||
``` | ||
3. Activate pre-commit hooks (Optional) | ||
Using [pre-commit](https://pre-commit.com/) to run some checks before committing is highly recommended. | ||
To activate the pre-commit hooks run: | ||
```bash | ||
pre-commit install | ||
``` | ||
To run the checks manually run: | ||
```bash | ||
poetry run pre-commit run --all-files | ||
``` | ||
The following checks are run: `black`, `flake8`, `isort`, `mypy`, `pylint`. | ||
## Running Local | ||
1. Run: | ||
```bash | ||
poetry run python -m template.main | ||
``` | ||
2. Go to http://localhost:8000/docs to see the API documentation. | ||
## Running Tests | ||
You can run the tests with: | ||
```bash | ||
poetry run pytest | ||
``` | ||
or with the `make` command: | ||
```bash | ||
make test | ||
``` | ||
To generate a coverage report add `--cov src`. | ||
```bash | ||
poetry run pytest --cov src | ||
``` | ||
Or with the `make` command: | ||
```bash | ||
make cover | ||
``` | ||
## Updating Dependencies | ||
To update the dependencies run: | ||
```bash | ||
poetry update | ||
``` | ||
## Recommended Readings | ||
- [FastAPI official Documentation](https://fastapi.tiangolo.com/) | ||
- [Pydantic official Documentation](https://pydantic-docs.helpmanual.io/) | ||
- [Cosmic Python](https://cosmicpython.com/) | ||
## License | ||
This project is licensed under the terms of the MIT license unless otherwise specified. See [`LICENSE`](LICENSE) for | ||
more details or visit https://mit-license.org/. | ||
## Acknowledgements | ||
This project was designed and developed | ||
by [Tomás Sánchez](https://tomsanchez.com.ar/about/) <[[email protected]](mailto:[email protected])>. | ||
Deeply inspired by [FastAPI-MVC](https://fastapi-mvc.netlify.app/) | ||
following [Cosmic Python](https://www.cosmicpython.com/) guidelines for project structure. | ||
If you find this project useful, please consider supporting its development by sponsoring it. |