The aiohttp boilerplate. A quick start for your aiohttp application.¶
What is a create aio app? This project is designed to quickly and simply create a web application based on aiohttp using best practices.
A create aio app provides testing, documentation, deploying and a lot of other helpful boilerplate code for quickly start with aiohttp.
Features¶
- aiohttp - the best python framework :)
- mypy - for optional static typing
- pytest - for running unit tests
- flake8 - for linting
- trafaret - for validating input data
- aio devtools - helpful tool for development
- aiohttp debugtoolbar - aiohttp debug toolbar
- postgres - for storage
- alembic - for migration
- sqlAlchemy - orm
- sphinx - for generate docs
- docker-compose - for running develop environment and deploy
Quick start for aiohttp¶
To use create-aio-app you have to meet the next requirements:
- python>=3.6
- docker-compose
Install¶
pip install create-aio-app
Usage¶
create-aio-app my_project
If you want to use interactive mode, enter the following command:
create-aio-app
This will create a new directory called my_project.
cd my_project
make run # start your project
Navigate in your browser to http://localhost:8080/
Make commands¶
The set of commands available in the Makefile.
Common¶
| command | description |
|---|---|
make run (make) |
Start the development server |
make stop |
Stop docker containers |
make clean |
Clean up of docker containers |
make bash |
Interactive shell inside the running container (the command can be executed only if the server is running e.g. after make run) |
make upgrade |
Upgrade dependencies |
Testing¶
| command | description |
|---|---|
make test |
Run the pytest suite inside docker |
make mypy |
Run mypy for type checking |
make black |
Run black code formatter |
make lint |
Run flake8 (All the settings for flake8 can be customized in .flake8 file) |
make profile |
Run py-spy sampling profiler. It defaults to 60 seconds. Can be change by adding the TIME variable. eg make profile TIME=30 |
Database¶
Next commands are available if you have not disabled postgres option when
creating a project:
| command | description |
|---|---|
make migrations |
Generate a new migration |
make migrate |
Apply migrations |
make psql |
Connect to the postgres inside running container |
Other¶
| command | description |
|---|---|
make doc |
Generate a sphinx documentation |
Documentation¶
The best thing you can do for future self and fellow contributors is to write both tests and documentation about your project. This section explains how to structure and organize documentation in your project.
Structure¶
We use the following structure:
- pages/ - The directory for all *.rst files about the boilerplate.
- project/ - This directory is for *.rst files associated with your project (this can include auto-generated docs, business logic, etc.)
All new files should be added to index.rst.
Linter¶
Doc8 is an opinionated style checker for rst styles of documentation. This linter used by default.
Read more:¶
- Sphinx - official sphinx documentation
- Documentation style guide - recommended style guide
- Doc8 - style checker for documentation
Testing¶
Code without tests is broken by design. Please remember this and write tests;)
This project runs tests inside Docker. It allows you to run tests locally with maximum isolation from the environment. It also gives you a simple way of adding new resources required for your tests.
Pytest¶
Use this command to run the tests:
make test
This will run flake8 and after successful execution, the command will run a test suite with pytest
If you want to run a single test, you can pass an argument to docker-compose like this:
docker-compose run test project_name/main/tests/test_views.py::test_view
mypy¶
Mypy is an optional static type checker for Python. We suggest you try it out as it allows you to catch some errors, write safer code and make refactoring of the code easier in the future.
To run mypy use this command:
make mypy
Settings for mypy reside inside the mypy.ini file.