This is a template project to jump-start the creation of additional project repositories, managed by Blur Studio, on GitHub. Below is a walk-through of various characteristics of the project.
- Enables the
setuptoolsextensionsetuptools_scm. This extension replaces the need to statically define a package's version and instead derives the version from SCM metadata (such as the latest git tag). - Permit package installation in editable mode. (i.e.
pip install -e .)
You should not need to modify the contents setup.py.
Originally
setup.pywas the primary manor by which to define a package's metadata. It has mostly been replaced bysetup.cfg.
- Defines static package metadata such as package description, author, and PyPI classifiers.
- Lists package requirements (
install_requires). - Lists auxiliary package requirements (
extras_require). These can be installed by appending the extras group name (or "all" for all groups) in square-brackets upon install (ex:pip install -e .[lint]). - Configures
flake8.
Be sure to update the various properties so they pertain to your project.
- Defines build system characteristics, more specifically those pertaining to
setuptools_scmwhich provides automatic versioning based off git repo state. - Configures
pytest.
The only property that will need updating is the write_to destination for the version.py-file.
While it would be ideal to fully migrate to
pyproject.tomlthere are still several aspects of configuration that have not yet fully migrated to support the finalized PEP 621 standard.
- Defines a list of packages required in order to install and run the project's package.
- The
-devrequirements file lists packages useful during development (ex:pytest,flake8).
Keep these up to date with any packages required by the project.
Analyses for a number of common errors and syntactical violations. Configuration is provided by a section in setup.cfg. For consistency when testing we have pinned the tox and pre-commit versions to flake8==5.0.4 flake8-bugbear==22.12.6 pep8-naming==0.13.3.
Conforms code to a set of opinionated formatting standards. For consistency when testing we have pinned the tox and pre-commit version of black to black==22.12.0.
To simplify the linting and formatting process a basic configuration of pre-commit has been added. Integrating with Git hooks, pre-commit executes a set of actions before a commit is added to the repository interrupting the commit if any of the hooks fail or make additional changes.
Before you can start using pre-commit you will need to install it via pip (pip install pre-commit) and install the Git hook scripts into your local copy of the Git repository (pre-commit install). The next time any changes are committed those scripts will execute and run the hooks configured in .pre-commit-config.yaml. Below are the hooks currently configured:
| Hook | Description |
|---|---|
| black | Conforms code to a set of opinionated formatting standards. |
| flake8 | Analyses for a number of common errors and syntactical violations. |
| setup-cfg-fmt | Applies a consistent format to setup.cfg files. |
| check-json | Attempts to load all json files to verify syntax. |
| check-toml | Attempts to load all toml files to verify syntax. |
| check-xml | Attempts to load all xml files to verify syntax. |
| check-yaml | Attempts to load all yaml files to verify syntax. |
| debug-statements | Ensures there are no debug breakpoints present. |
| end-of-file-fixer | Ensures each file has one newline at the end. |
| requirements-txt-fixer | Sorts entries in requirements.txt and removes incorrect entries. |
| trailing-whitespace | Trims any trailing whitespace from lines. |
For consistency when testing we have pinned the tox and pre-commit versions to black==22.12.0 flake8==5.0.4 flake8-bugbear==22.12.6 pep8-naming==0.13.3. When using pre-commit autoupdate, do not change those package versions without updating the tox.ini file. To make developing multiple packages easier, changing the pinned versions of these packages should be done for all packages, not just this single package. This way the system python can have these versions installed and ide's that automatically enforce black and flake8 rules are consistent across all projects.
For the moment we are stuck using CentOS for linux workstations which still uses python 3.6. For this reason, we have added args: [--min-py3-version=3.6] to the configuration of setup-cfg-fmt. Any code intended to(or possibly might) run on user workstations or farm nodes on linux should keep this. This setting keeps the setup.cfg file from being updated to exclude python 3.6. Ideally we can remove python 3.6 requirements in the future.
Runs against every push, regardless of branch. Checks the codebase for common errors and syntactical violations with flake8 and that the code is formatted according to black.
Runs when a new release is created.
Describes a set of standards contributors and maintainers alike are intended to follow when interacting with and contributing to projects maintained by Blur Studio.
A kick-start document standardizing the manor by which other developers can contribute to projects maintained by Blur Studio.
Templates for reporting issues (bugs or feature requests) and submitting pull requests. Each provide a scaffolding for reporters and contributors to follow, ensuring each request has the appropriate information upon first submission.