When contributing to this repository, please adhere to our Code of Conduct and first discuss the change you wish to make via an issue before submitting a pull request.
The following sections will guide you through setting up a local development environment for working on this project package. At the very least, make sure that you have the necessary pre-commit hooks installed to make sure that all commits are pristine before they make it into the change history.
If you already have Python 3.7+ installed on your local system, you can skip this step completely.
Installing Python should be done through pyenv.
To first install
pyenv please follow the guide they provided at
https://github.com/pyenv/pyenv#installation. When you finally have
pyenv you should
be good to continue on.
$ pyenv --version pyenv x.x.x
Now that you have
pyenv we can install the necessary Python version. This project’s
package depends on Python 3.7+, so we can request that through
$ pyenv install 3.7 # to install Python 3.7+ ... $ pwd /PATH/TO/CLONED/REPOSITORY/project-name $ pyenv local 3.7 # to mark the project directory as needing Python 3.7+ ... $ pyenv global 3.7 # if you wish Python 3.7 to be aliased to `python` everywhere ...
After installing and marking the repository as requiring Python 3.7+ you should be good to continue on installing the project’s dependencies.
We use Poetry to manage both our dependencies and
virtual environments. Setting up
poetry just involves installing it through
as a user-level dependency.
$ pip install --user poetry Collecting poetry Downloading poetry-x.x.x-py2.py3-non-any.whl ...
You can quickly setup your entire development environment by running the installation process from poetry.
$ poetry install Installing dependencies from lock file ...
This with create a virtual environment for you and install the necesary development
dependencies. From there you can jump into a subshell using the newly created virtual
environment using the
$ poetry shell pawning shell within ~/.local/share/virtualenvs/my-project-py3.7 ... $ exit # when you wish to exit the subshell
From this shell you have access to all the necessary development dependencies installed in the virutal environment and can start actually writing and running code within the client package.
This project’s preferred styles are fully enforced through
pre-commit hooks. In order to take advantage of these hooks
please make sure that you have
pre-commit and the configured hooks installed in your
pre-commit is done through
pip and should be installed as a
user-level dependency as it adds some console scripts that all projects using
pre-commit will need.
$ pip install --user pre-commit Collecting pre-commit Downloading pre_commit-x.x.x-py2.py3-none-any.whl ... $ pre-commit --version pre-commit 2.4.0
pre-commit is installed you should also install the hooks into the cloned
$ pwd /PATH/TO/CLONED/REPOSITORY/project-name $ pre-commit install pre-commit installed at .git/hooks/pre-commit
After this you should be good to continue on. These installed hooks will do a first-time
setup when you attempt your next commit to build hook environments. Changes that violate
the defined style specifications in
pyproject.toml will cause the
commit to fail and will likely make the necessary changes to added / changed files to
be written to the failing files.
This will give you the opprotunity to view the changes the hooks made to the failing files and add the new changes to the commit in order to make the commit pass. It also gives you the opprotunity to make tweaks to the autogenerated changes to make them more human accessible (only if necessary).
We also have some specific settings for editor configuration via
editorconfig. We recommend you install the
appropriate plugin for your editor of choice if your editor doesn’t already natively
.editorconfig configuration files.
All of our tasks are built and run through invoke which is basically just a more advanced (a little too advanced) Python alternative to make. The only reason we are using this utility is because I know how it works and I already had most of the necessary tasks defined from other projects.
From within the Poetry subshell, you can access and run these commands through the
invoke development dependency.
$ invoke --list Available tasks: build Build the project. clean Clean the project. lint Lint the project. profile Run and profile a given Python script. test Test the project. docs.build Build docs. docs.build-news Build towncrier newsfragments. docs.clean Clean built docs. docs.view Build and view docs. linter.black Run Black tool check against source. linter.flake8 Run Flake8 tool against source. linter.isort Run ISort tool check against source. linter.mypy Run MyPy tool check against source. package.build Build pacakge source files. package.check Check built package is valid. package.clean Clean previously built package artifacts. package.coverage Build coverage report for test run. package.format Auto format package source files. package.requirements Generate requirements.txt from Poetry's lock. package.stub Generate typing stubs for the package. package.test Run package tests. package.typecheck Run type checking with generated package stubs.
You can run these tasks to do many miscellaneous project tasks such as building documentation.
$ invoke docs.build [docs.build] ... building 'html' documentation Running Sphinx v3.0.3 loading pickled environment... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 0 source files that are out of date updating environment: 0 added, 0 changed, 0 removed looking for now-outdated files... none found no targets are out of date. build succeeded. The HTML pages are in build/html.
All of these tasks should just work right out of the box, but something might break eventually after required tooling gets enough major updates.
Issues should follow the included
ISSUE_TEMPLATE found in
- Issues should contain the following sections:
Steps to Reproduce (for bugs)
These sections help the developers greatly by providing a large understanding of the context of the bug or requested feature without having to launch a full fleged discussion inside of the issue.
Creating Pull Requests¶
Pull requests should follow the included
PULL_REQUEST_TEMPLATE found in
- Pull requests should always be from a
bugfix(left side) branch.Pull requests from master branches will not be merged.
Pull requests should not fail our requested style guidelines or linting checks.