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 <a href="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 <a href="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
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 <a href="https://www.mkdocs.org/" target="_blank">MkDocs</a>.
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.
* 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:
+
+```env
+PYTHONPATH=./docs/src
+```
projects / thirdparty / fastapi / fastapi.git / commitdiff
