Development - Contributing
First, you might want to see the basic ways to help and get help.
Developing¶
Once you’ve cloned the repository, here are some guidelines to set up your environment:
Set up the development evironment¶
After cloning the repository, you can use poetry
to create a virtual environment:
$ make develop
Behind the scenes, this checks that you have python3 and poetry installed, then creates a virtual environment and installs the dependencies. At the end, it will print out the path to the executable in case you want to add it to your IDE.
Activate the environment¶
Once the virtual environment is created, you can activate it with:
$ poetry shell
To check if this worked, try running:
$ which python
some/directory/fastapi-utils-SOMETHING-py3.X/bin/python
If the output of this command shows the python
binary in a path containing fastapi-utils
somewhere in the name
(as above), then it worked! 🎉
Tip
Every time you install a new package with pip
under that environment, activate the environment again.
This makes sure that if you use a terminal program installed by that package (like mypy
),
you use the one from your local environment and not any other that could be installed globally.
Static Code Checks¶
This project makes use of black
, autoflake8
, and isort
for formatting,
flake8
for linting, and mypy
for static type checking.
To auto-format your code, just run:
$ make format
It will also auto-sort all your imports, and attempt to remove any unused imports.
You can run flake8 with:
$ make lint
and you can run mypy with:
$ make mypy
There are a number of other useful makefile recipes; you can see basic documentation of these by calling plain make
:
$ make
Docs¶
The documentation uses MkDocs.
All the documentation is in Markdown format in the directory ./docs
.
Many of the sections in the User Guide have blocks of code.
In fact, those blocks of code are not written inside the Markdown, they are Python files in the ./docs/src/
directory.
And those Python files are included/injected in the documentation when generating the site.
Docs for tests¶
Most of the tests actually run against the example source files in the documentation.
This helps making sure that:
- The documentation is up to date.
- The documentation examples can be run as is.
- Most of the features are covered by the documentation, ensured by test coverage.
During local development, there is a script that builds the site and checks for any changes, live-reloading:
$ bash scripts/docs-live.sh
It will serve the documentation on http://0.0.0.0:8008
.
That way, you can edit the documentation/source files and see the changes live.
Tests¶
You can run all tests via:
$ make test
You can also generate a coverage report with:
make testcov
On MacOS, if the tests all pass, the coverage report will be opened directly in a browser; on other operating systems a link will be printed to the local HTML containing the coverage report.
Tests in your editor¶
If you want to use the integrated tests in your editor add ./docs/src
to your PYTHONPATH
variable.
For example, in VS Code you can create a file .env
with:
PYTHONPATH=./docs/src