Developer Guide #
Issues and pull requests are welcome. Know that your contributions are donated to the public domain.
Environment Setup #
Python release candidates are tested against Python 3.6+, so your safest bet when developing is to use v3.6. However, we encourage you to develop in the most current stable release of Python 3 so that you can help us identify potential future compatibility issues.
Install the development environment requirements from
requirements/dev.txt. This will install the test suite and documentation tooling.
$ pip install -r requirements/dev.txt
Clone the Knackpy repo and create a new branch from the
dev branch. Use the
-e flag to install in development mode:
$ pip install -e knackpy
Knackpy Development Knack Application #
api.py are dependent on a City of Austin-owned Knack application which we rely on for over-the-wire API tests. If you work for the City of Austin Transportation Department, the credentials for this app are in our password store, and the app is called “Knackpy Development”.
Any modifications you make to the Knackpy Development app may impact tests. You should carefully review our
tests/ before you modify anything in the development app.
Some tests rely on static
json data stored in the tests directory. After modifying the app, you must refresh the static data by replacing
tests/_metadata.json with the most current app metadata, as well as
tests._all_fields.json with records exported from the
all_fields object in the Knack app.
Writing Tests #
Ideally, you would add tests for your code to the appropriate test collection in the
tests/ directory. If you don’t have access to our development Knack application, please at least write an example test in your pull request.
Running Tests #
You can run ad-hoc tests with:
$ coverage run -m pytest -c path/to/your/tests
Before you can run the entire test suite, you’ll need to create a
pytest.ini config with the appropriate environmental variables. You can model it after this example.
To run the test suite from
$ coverage run -m pytest -c tests/pytest.ini -x.
After running the tests, you can use
$ coverage html to generate HTML documentation of code coverage.
You can update the coverage badge image with:
$ coverage-badge -f -o coverage.svg
Linting and Formatting #
--max-line-length param so that the linter matches black’s line length opinion:
$ flake8 --max-line-length=88
Rebuild and commit the documentation HTML whenever you update module docstrings or the user guide.
# build html content $ pydoc-markdown --build --site-dir docs # or build and serve locally $ pydoc-markdown --server
Automated Tests and Deployment #
We use Github Actions to test Knackpy builds and to publish to PyPI. The workflows are defined in