Contributing to the SDK¶
Note: The SDK currently works with Python versions 3.7 through 3.10.x. Python 3.6 is no longer supported.
Setting up Prereqs¶
If poetry and pipx are not already installed:
pip3 install pipx pipx ensurepath pipx install poetry
Now you can use Poetry to install package dependencies:
# Install package and dependencies: poetry install # OR install in editable mode: poetry install --no-root
Local Developer Setup¶
First clone, then…
If you are using VS Code, make sure you have also installed the
Ensure you have the correct test library, formatters, and linters installed:
Configure Linting and Formatting Settings:
pytestfor testing (
poetry run pytest).
pydocstyleas CI linting tests.
coveragefor code coverage metrics.
The project-wide max line length is
The project has pre-commit hooks. Just run
pre-commit installand the next time you make a commit, the changes will be linted.
Set interpreter to match poetry’s virtualenv:
In VS Code, run
Python: Select interpreterand select the poetry interpreter.
To run tests:
# Run all tests (external creds required): poetry run pytest # Run just the core and cookiecutter tests (no external creds required): poetry run pytest tests/cookiecutters poetry run pytest tests/core
To run tests while gathering coverage metrics:
# Run with all tests (external creds required): poetry run coverage run -m pytest # Run with just the core tests (no external creds required): poetry run coverage run -m pytest tests/core
To view the code coverage report:
# CLI output poetry run coverage report # Or html output: poetry run coverage html && open ./htmlcov/index.html
To run all tests:
poetry run tox
Testing Updates to Docs¶
Documentation runs on Sphinx, a using ReadtheDocs style template, and hosting from ReadtheDocs.org. When a push is detected by readthedocs.org, they automatically rebuild and republish the docs. ReadtheDocs is also version aware, so it retains prior and unreleased versions of the docs for us.
First, make sure your virtual env has all the right tools and versions:
To build the docs:
cd docs # Build docs poetry run make html # Open in the local browser: open _build/html/index.html
To build missing stubs:
cd docs poetry run sphinx-autogen -o classes *.rst
Workspace Development Strategies for the SDK¶
Universal Code Formatting¶
From the Black website:
By using Black, you agree to cede control over minutiae of hand-formatting. In return, Black gives you speed, determinism, and freedom from pycodestyle nagging about formatting. You will save time and mental energy for more important matters. Black makes code review faster by producing the smallest diffs possible. Blackened code looks the same regardless of the project you’re reading. Formatting becomes transparent after a while and you can focus on the content instead.
Pervasive Python Type Hints¶
Type hints allow us to spend less time reading documentation. Public modules are checked in CI for type annotations on all methods and functions.
All public modules in the SDK are checked for the presence of docstrings in classes and functions. We follow the Google Style convention for Python docstrings so functions are required to have a description of every argument and the return value, if applicable.