This template was created so that a new python3 CLI program could be quickly whipped up with a nice infrastructure.
This template is based on several projects that originated at or as part of collaborations involving The Broad Institute of MIT and Harvard. In particular, the following people were instrumental in those projects:
- Kiran Garimella (@kvg)
- Winni Kretzschmar (@winni2k)
- Karl Johan Westrin (@karljohanw)
Included in this template are the following features:
clickfor argument parsing with examples- an over-engineered logging module (ensures that all log messages have correct leading whitespace to be column-aligned)
toxsetup (linting, black for code formatting, testing)- examples of tests (already connected to tox for quick starting)
.gitignorefor most kinds of local files- include sort ordering defaults
- a
readthedocstemplate - a
bumpversionconfig file - a
pylintconfig file
If you check this out and run tox the tests will all pass.
To make this project-specific, several placeholder values need to be replaced with your content.
| FIELD | DESCRIPTION |
|---|---|
| PROJECT_NAME | The name of your new project / tool. |
| _SHORT_PROJECT_DESCRIPTION_ | A concise description of your new project / tool. |
| _AUTHOR_ | The name of the primary author / point of contact. |
| _AUTHOR_EMAIL_ | The email address of the primary author / point of contact. |
This find/replace will be needed until github implements template repo variables.
However, fear not! I have provided initialize.sh for this very purpose. Run it with the following parameters after creating your repo to initialize your specific repository info:
./initialize.sh PROJECT_NAME "SHORT PROJECT DESCRIPTION" "AUTHOR NAME" AUTHOR_EMAIL
I quoted the fields that are likely to contain spaces - this will be necessary.
You may also need to do the following:
- Update the LICENSE file - it defaults to the BSD 3-Clause License.
When you add development dependencies, add them to dev-requirements.txt.
When you add testing dependencies, add them to test-requirements.txt.
When you add runtime dependencies, add them to setup.py in the install_requires section.
When running tox, you'll notice that the linter runs before black8. This is intentional. Rather than have it blindly reformat your code, I wanted to make sure you knew what you were doing wrong (i.e. against PEP 8 standards). You can configure this order to suit your needs.
Notable projects already using this template are:
Lastly, it's worth double-checking everything to make sure you want what's included here.
Below this line begins the project-specific portion of the README that should be modified after creating a new project:
_SHORT_PROJECT_DESCRIPTION_
Current version: 0.0.1
pip install .
To do development in this codebase, the python3 development package must be installed.
After installation the development environment can be set up by the following commands:
python3 -mvenv venv
. venv/bin/activate
pip install -r dev-requirements.txt
pip install -e .
# run all linting commands
tox -e lint
# reformat all project files
black src tests setup.py
# sort imports in project files
isort -rc src tests setup.py
# check pep8 against all project files
flake8 src tests setup.py
# lint python code for common errors and codestyle issues
pylint src
# run all linting and test
tox
# run only (fast) unit tests
tox -e unit
# run only linting
tox -e lint
Note: If you run into "module not found" errors when running tox for testing, verify the modules are listed in test-requirements.txt and delete the .tox folder to force tox to refresh dependencies.
We use bumpversion to maintain version numbers.
DO NOT MANUALLY EDIT ANY VERSION NUMBERS.
Our versions are specified by a 3 number semantic version system (https://semver.org/):
major.minor.patch
To update the version with bumpversion do the following:
bumpversion PART where PART is one of:
- major
- minor
- patch
This will increase the corresponding version number by 1.