Table of Contents
- Setting up a New Environment
- Testing Changes
- Cheat Sheet
Welcome to the developer documentation for pyatv, i.e. the documentation explaining how pyatv works (internally) and how to extend it. This section used to reside in the GitHub wiki, but has moved to the general documentation for greater availability. It is still under heavy development, so beware of missing and/or outdated content as it is migrated from the wiki.
Setting up a New Environment
You can run the script
scripts/setup_dev_env.sh to set up a complete development environment. It will make sure that everything works as expected by running
chickn, building documentation (with docker), etc.
$ ./scripts/setup_dev_env.sh $ ./scripts/chickn.py
There’s no helper script for windows, but you can get started manually like this:
$ git clone https://github.com/postlund/pyatv.git $ cd pyatv $ python3 -m venv venv $ source venv/Scripts/activate $ python setup.py develop $ pip install pyyaml -r requirements/requirements_test.txt -r requirements/requirements_docs.txt $ python scripts/chickn.py
If you followed the instructions above, then pyatv will be installed as “develop”. This means that you can keep doing updates without having to do
python setup.py install between changes.
Testing with chickn
To test everything, just run
This will make sure that tests pass, you have followed coding guidelines (pylint, flake8, etc), verify protobuf messages and generate coverage data.
chickn is developed for pyatv and the documentation for it is
here. The configuration file is here
You can run steps individually as well:
All available steps can be listed with
$ ./scripts/chickn.py -l clean, fixup, pylint, api, protobuf, flake8, black, pydocstyle, isort, cs_docs, cs_code, typing, pytest, report, dist
fixup will run black and isort to clean up basic mistakes before running rest of the commands.
So it can be convenient to enable that step with the
./scripts/chickn.py -t fixup
chickn will install the latest version of all dependencies. There’s however a
wish to verify that everything works the lowest version that pyatv supports. This is denoted
as “regression” in GitHub actions. These versions are listed in base_versions.txt
and can be manually overridden when needed:
$ ./scripts/chickn.py -v requirements_file=base_versions.txt 2021-10-24 11:16:19 [INFO] Installing dependencies 2021-10-24 11:16:19 [INFO] Re-installing packages with mismatching versions: aiohttp==3.1.0 (3.7.4), bitarray==2.1.2 (2.3.4), cryptography==2.6 (35.0.0), netifaces==0.10.0 (0.11.0), protobuf==3.18.0 (3.19.0), srptools==0.2.0 (1.0.1), zeroconf==0.28.2 (0.36.8) ...
You generally do not need to do this yourself as it is tested automatically by GitHub Actions.
Updating protobuf Definitions
If you have made changes to the protobuf messages in
pyatv/mrp/protobuf, you can make sure everything is updated by running:
$ ./scripts/protobuf.py --download generate
See Protobuf for more details.
Recommended way to run unit tests:
$ pytest --log-level=debug --disable-warnings $ ./scripts/chickn.py pytests # Can be run via chickn
Warnings are disabled because of deprecated
loop argument in lots of places. This flag will be lifted eventually. See Testing for details regarding tests.
All python code is formatted using black, so you don’t have to care about how the code looks. Just let black take care of it:
$ black . All done! ✨ 🍰 ✨ 77 files left unchanged.
Code formatting is checked by
chickn, so it’s not possible to check in code if it doesn’t comply with black.
NB: This step currently requires docker and is only tested on Linux!
To serve a local running web server that performs incremental updates of the documentation, run:
Navigate to http://localhost:4000 to see the result.
cs_docs step (
./scripts/chickn.py cs_docs) will do basic spell checking of the documentation
Here are a few convenient commands in short form:
|pytest –disable-warnings –log-level=debug -k XXX||Run tests matching XXX|
|black .||Re-format code with black|
|./scripts/protobuf.py –download generate||Update protobuf definitions|
|./scripts/build_doc.sh||Serve web server with documentation at http://127.0.0.1:4000|
|./scripts/api.sh generate||Update generate API