Development setup
This document describes the existing developer tooling we have in place (and what to expect of it).
Environment Setup
Follow the Installation steps to prepare the source code. Then follow the steps below to set up the corresponding development environment.
Visual Studio Code
Click on the Python version at the bottom left of the editor’s window and select the Python interpreter which Poetry just created. If you do not find it, check FAQ and troubleshooting for extra instructions. This step is important because it ensures that the current workspace uses the correct Poetry virtual environment which provides all dependencies required.
You can copy the settings below into
.vscode/settings.json
.{ "markdown.extension.toc.levels": "2..6", "python.analysis.typeCheckingMode": "strict", "python.formatting.provider": "black", "python.linting.enabled": true, "python.linting.flake8Enabled": true, "python.linting.mypyEnabled": true, "python.linting.pylintEnabled": false, "editor.formatOnSave": true, "python.linting.mypyArgs": [ "--config-file", "pyproject.toml" ], "python.sortImports.path": "isort", "editor.codeActionsOnSave": { "source.organizeImports": true }, "python.analysis.useLibraryCodeForTypes": false, "python.analysis.autoImportCompletions": false, "files.eol": "\n", "terminal.integrated.env.windows": { "mypypath": "${workspaceFolder}\\typings" }, "python.analysis.diagnosticSeverityOverrides": { "reportUntypedClassDecorator": "none", "reportUnknownMemberType": "none", "reportGeneralTypeIssues": "none", "reportUnknownVariableType": "none", "reportUnknownArgumentType": "none", "reportUnknownParameterType": "none", "reportUnboundVariable": "none", "reportPrivateUsage": "none", "reportImportCycles": "none", "reportUnnecessaryIsInstance": "none", "reportPrivateImportUsage": "none", "reportUnusedImport": "none", "reportUnusedFunction": "none" }, "python.languageServer": "Pylance" }
Install extensions.
Install Pylance to get best code intelligence experience.
Install Rewrap to automatically wrap.
If there is need to update the documentation, it is recommended to install Markdown All in One. It helps to maintain the table of contents in the documentation.
Install reStructuredText to get a syntax checker for reStructuredText. To preview the document, see Local Documentation.
Emacs
Use the pyvenv package:
(use-package pyvenv
:ensure t
:hook (python-mode . pyvenv-tracking-mode))
Then run
M-x add-dir-local-variable RET python-mode RET pyvenv-activate RET <path/to/virtualenv>
where the value is the path given by the command above. This will create
a .dir-locals.el
file as follows:
;;; Directory Local Variables
;;; For more information see (info "(emacs) Directory Variables")
((python-mode . ((pyvenv-activate . "~/.cache/pypoetry/virtualenvs/lisa-s7Q404Ij-py3.8"))))
Other setups
Install and enable ShellCheck to find bash errors locally.
Code checks
If the development environment is set up correctly, the following tools will automatically check the code. If there is any problem with the development environment settings, please feel free to submit an issue to us or create a pull request for repair. You can also run the check manually.
Black, the opinionated code formatter resolves all disputes about how to format our Python files. This will become clearer after following PEP 8 (official Python style guide).
Flake8 (and integrations), the semantic analyzer, used to coordinate most other tools.
isort, the
import
sorter, it will automatically divide the import into the expected alphabetical order.mypy, the static type checker, which allows us to find potential errors by annotating and checking types.
rope, provides completion and renaming support for pyls.
Local Documentation
It’s recommended to build the documentation locally using Sphinx
for preview.
To do so, in ./lisa/docs
, run
poetry run make html
You can find all generated documents in ./lisa/docs/_build/html
folder. Open
them with a browser to view.
Note
If there are already generated documents in ./lisa/docs/_build/html
, run
poetry run make clean
to ensure the documentation is clean and not
affected by the previous build.
Extended reading
Python Design Patterns. A fantastic collection of material for using Python’s design patterns.
The Hitchhiker’s Guide to Python. This handcrafted guide exists to provide both novice and expert Python developers a best practice handbook for the installation, configuration, and usage of Python on a daily basis.
LISA performs static type checking to help finding bugs. Learn more from mypy cheat sheet and typing lib. You can also learn from LISA code.