➖ Use venv with Flit for local development, instead of requiring Flit and Pipenv (#877)

.gitignore

@@ -13,3 +13,4 @@ coverage.xml
 test.db
 log.txt
 Pipfile.lock
+env3.*

Pipfile

@@ -1,38 +0,0 @@
-[[source]]
-name = "pypi"
-url = "https://pypi.org/simple"
-verify_ssl = true
-
-[dev-packages]
-mypy = "*"
-black = "*"
-jupyter = "*"
-better-exceptions = "*"
-pytest = "*"
-pytest-cov = "*"
-isort = "*"
-requests = "*"
-flit = "*"
-mkdocs = "*"
-mkdocs-material = "*"
-markdown-include = "*"
-autoflake = "*"
-email-validator = "*"
-ujson = "*"
-flake8 = "*"
-python-multipart = "*"
-sqlalchemy = "*"
-uvicorn = "*"
-
-[packages]
-starlette = "==0.12.9"
-pydantic = "==1.0.0"
-databases = {extras = ["sqlite"],version = "*"}
-hypercorn = "*"
-orjson = "*"
-
-[requires]
-python_version = "3.6"
-
-[pipenv]
-allow_prereleases = true

docs/contributing.md

@@ -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 <a href="https://pipenv.readthedocs.io/en/latest/" target="_blank">Pipenv</a>, you can create a virtual environment and install the packages with:
-
-```bash
-pipenv install --dev
+```console
+$ python -m venv env
 ```
 
-Then you can activate that virtual environment with:
+That will create a directory `./env/` with the Python binaries and then you will be able to install packages for that isolated environment.
 
-```bash
-pipenv shell
+### Activate the environment
+
+Activate the new environment with:
+
+```console
+$ source ./env/bin/activate
 ```
 
+Or in Windows' PowerShell:
 
-### No Pipenv
+```console
+$ .\env\Scripts\Activate.ps1
+```
 
-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`.
+Or if you use Bash for Windows (e.g. [Git Bash](https://gitforwindows.org/){.external-link target=_blank}):
 
+```console
+$ source ./env/Scripts/activate
+```
+
+To check it worked, use:
+
+```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.
+After activating the environment  as described above, install `flit`:
 
-To install your local version of FastAPI as a package in your local environment, run:
-
-```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
 
-### Docs
+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
 
 The documentation uses <a href="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:
+
+```env
+PYTHONPATH=./docs/src
+```

pyproject.toml

@@ -64,7 +64,11 @@ doc = [
 ]
 dev = [
     "pyjwt",
-    "passlib[bcrypt]"
+    "passlib[bcrypt]",
+    "autoflake",
+    "flake8",
+    "uvicorn",
+    "graphene"
 ]
 all = [
     "requests",

scripts/netlify-docs.sh

@@ -1,7 +1,14 @@
 #!/usr/bin/env bash
-# Install pipenv to be able to install from Pipfile
-pip install pipenv
-# Install Pipfile including --dev, to install mkdocs and plugins
-pipenv install --dev
+set -x
+set -e
+# Install pip
+cd /tmp
+curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
+python3.6 get-pip.py --user
+cd -
+# Install Flit to be able to install all
+python3.6 -m pip install --user flit
+# Install with Flit
+python3.6 -m flit install --user --extras doc
 # Finally, run mkdocs
-mkdocs build
+python3.6 -m mkdocs build