@ -4,41 +4,77 @@ First, you might want to see the basic ways to <a href="https://fastapi.tiangolo
If you already cloned the repository and you know that you need to deep dive in the code, here are some guidelines to set up your environment.
### Virtual environment with `venv`
### Pipenv
You can create a virtual environment in a directory using Python's `venv` module:
If you are using <ahref="https://pipenv.readthedocs.io/en/latest/"target="_blank">Pipenv</a>, you can create a virtual environment and install the packages with:
```console
$ python -m venv env
```
That will create a directory `./env/` with the Python binaries and then you will be able to install packages for that isolated environment.
### Activate the environment
Activate the new environment with:
```bash
pipenv install --dev
```console
$ source ./env/bin/activate
```
Then you can activate that virtual environment with:
Or in Windows' PowerShell:
```bash
pipenv shell
```console
$ .\env\Scripts\Activate.ps1
```
Or if you use Bash for Windows (e.g. [Git Bash](https://gitforwindows.org/){.external-link target=_blank}):
### No Pipenv
```console
$ source ./env/Scripts/activate
```
To check it worked, use:
If you are not using Pipenv, you can create a virtual environment with your preferred tool, and install the packages listed in the file `Pipfile`.
```console
$ which pip
some/directory/fastapi/env/bin/pip
```
If it shows the `pip` binary at `env/bin/pip` then it worked. 🎉
Or in Windows PowerShell:
```console
$ Get-Command pip
some/directory/fastapi/env/bin/pip
```
!!! 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 `flit`), you use the one from your local environment and not any other that could be installed globally.
### Flit
**FastAPI** uses <ahref="https://flit.readthedocs.io/en/latest/index.html"target="_blank">Flit</a> to build, package and publish the project.
If you installed the development dependencies with one of the methods above, you already have the `flit` command.
To install your local version of FastAPI as a package in your local environment, run:
After activating the environment as described above, install `flit`:
```bash
flit install --symlink
```console
$ pip install flit
```
It will install your local FastAPI in your local environment.
Now re-activate the environment to make sure you are using the `flit` you just installed (and not a global one).
And now use `flit` to install the development dependencies:
```console
$ flit install --deps develop --symlink
```
It will install all the dependencies and your local FastAPI in your local environment.
#### Using your local FastAPI
@ -48,25 +84,33 @@ And if you update that local FastAPI source code, as it is installed with `--sym
That way, you don't have to "install" your local version to be able to test every change.
### Format
There is a script that you can run that will format and clean all your code:
```bash
bash scripts/lint.sh
```console
$ bash scripts/format.sh
```
It will also auto-sort all your imports.
For it to sort them correctly, you need to have FastAPI installed locally in your environment, with the command in the section above:
```bash
flit install --symlink
```console
$ flit install --symlink
```
### Format imports
There is another script that formats all the imports and makes sure you don't have unused imports:
```console
$ bash scripts/format-imports.sh
```
As it runs one command after the other and modifies and reverts many files, it takes a bit longer to run, so it might be easier to use `scripts/format.sh` frequently and `scripts/format-imports.sh` only before committing.
### Docs
## Docs
The documentation uses <ahref="https://www.mkdocs.org/"target="_blank">MkDocs</a>.
@ -80,8 +124,7 @@ In fact, those blocks of code are not written inside the Markdown, they are Pyth
And those Python files are included/injected in the documentation when generating the site.
#### Docs for tests
### Docs for tests
Most of the tests actually run against the example source files in the documentation.
@ -89,35 +132,44 @@ 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 the coverage tests.
* 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
bash scripts/docs-live.sh
```console
$ 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.
#### Apps and docs at the same time
### Apps and docs at the same time
And if you run the examples with, e.g.:
If you run the examples with, e.g.:
```bash
uvicorn tutorial001:app --reload
```console
$ uvicorn tutorial001:app --reload
```
as Uvicorn by default will use the port `8000`, the documentation on port `8008` won't clash.
### Tests
## Tests
There is a script that you can run locally to test all the code and generate coverage reports in HTML:
```bash
bash scripts/test-cov-html.sh
```console
$ bash scripts/test-cov-html.sh
```
This command generates a directory `./htmlcov/`, if you open the file `./htmlcov/index.html` in your browser, you can explore interactively the regions of code that are covered by the tests, and notice if there is any region missing.
### 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:
Sebastián Ramírez
5 years ago
GitHub