From 48a6d1605539ae494562a4a118a96cce4834c233 Mon Sep 17 00:00:00 2001 From: Teemu Rytilahti Date: Sun, 5 May 2024 18:04:54 +0200 Subject: [PATCH 1/3] Move contribution instructions into docs --- README.md | 34 +--------------- docs/source/contribute.md | 84 +++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + 3 files changed, 87 insertions(+), 32 deletions(-) create mode 100644 docs/source/contribute.md diff --git a/README.md b/README.md index c17d80b56..4d029f646 100644 --- a/README.md +++ b/README.md @@ -186,41 +186,11 @@ The device type specific documentation can be found in their separate pages: ## Contributing Contributions are very welcome! To simplify the process, we are leveraging automated checks and tests for contributions. - -### Setting up development environment - -To get started, simply clone this repository and initialize the development environment. -We are using [poetry](https://python-poetry.org) for dependency management, so after cloning the repository simply execute -`poetry install` which will install all necessary packages and create a virtual environment for you. - -### Code-style checks - -We use several tools to automatically check all contributions. The simplest way to verify that everything is formatted properly -before creating a pull request, consider activating the pre-commit hooks by executing `pre-commit install`. -This will make sure that the checks are passing when you do a commit. - -You can also execute the checks by running either `tox -e lint` to only do the linting checks, or `tox` to also execute the tests. - -### Running tests - -You can run tests on the library by executing `pytest` in the source directory. -This will run the tests against contributed example responses, but you can also execute the tests against a real device: -``` -$ pytest --ip
-``` -Note that this will perform state changes on the device. - -### Analyzing network captures - -The simplest way to add support for a new device or to improve existing ones is to capture traffic between the mobile app and the device. -After capturing the traffic, you can either use the [softScheck's wireshark dissector](https://github.com/softScheck/tplink-smartplug#wireshark-dissector) -or the `parse_pcap.py` script contained inside the `devtools` directory. -Note, that this works currently only on kasa-branded devices which use port 9999 for communications. - +Please refer to [our contributing guidelines](https://python-kasa.readthedocs.io/en/latest/contribute.html). ## Supported devices -The following devices have been tested and confirmed as working. If your device is unlisted but working, please open a pull request to update the list and add a fixture file (use `python -m devtools.dump_devinfo` to generate one). +The following devices have been tested and confirmed as working. If your device is unlisted but working, please consider [contributing a fixture file](https://python-kasa.readthedocs.io/en/latest/contribute.html#contributing-fixture-files). diff --git a/docs/source/contribute.md b/docs/source/contribute.md new file mode 100644 index 000000000..e8f8796b6 --- /dev/null +++ b/docs/source/contribute.md @@ -0,0 +1,84 @@ +# Contributing + +You probably arrived to this page as you are interested in contributing to python-kasa in some form? +All types of contributions are very welcome, so thank you already! +This page aims to help you to get started. + +```{contents} Contents + :local: +``` + +## Setting up the development environment + +To get started, simply clone this repository and initialize the development environment. +We are using [poetry](https://python-poetry.org) for dependency management, so after cloning the repository simply execute +`poetry install` which will install all necessary packages and create a virtual environment for you. + +``` +$ git clone https://github.com/python-kasa/python-kasa.git +$ cd python-kasa +$ poetry install +``` + +## Code-style checks + +We use several tools to automatically check all contributions as part of our CI pipeline. +The simplest way to verify that everything is formatted properly +before creating a pull request, consider activating the pre-commit hooks by executing `pre-commit install`. +This will make sure that the checks are passing when you do a commit. + +```{note} +You can also execute the pre-commit hooks on all files by executing `pre-commit run -a` +``` + +## Running tests + +You can run tests on the library by executing `pytest` in the source directory: + +``` +$ pytest kasa +``` + +This will run the tests against the contributed example responses. + +```{note} +You can also execute the tests against a real device using `pytest --ip
`. +Note that this will perform state changes on the device. +``` + +## Analyzing network captures + +The simplest way to add support for a new device or to improve existing ones is to capture traffic between the mobile app and the device. +After capturing the traffic, you can either use the [softScheck's wireshark dissector](https://github.com/softScheck/tplink-smartplug#wireshark-dissector) +or the `parse_pcap.py` script contained inside the `devtools` directory. +Note, that this works currently only on kasa-branded devices which use port 9999 for communications. + +## Contributing fixture files + +One of the easiest ways to contribute is by creating a fixture file and uploading it for us. +These files will help us to improve the library and run tests against devices that we have no access to. + +This library is tested against responses from real devices ("fixture files"). +These files contain responses for selected, known device commands and are stored [in our test suite](https://github.com/python-kasa/python-kasa/tree/master/kasa/tests/fixtures). + +You can generate these files by using the `dump_devinfo.py` script. +Note, that this script should be run inside the main source directory so that the generated files are stored in the correct directories. +The easiest way to do that is by doing: + +``` +$ git clone https://github.com/python-kasa/python-kasa.git +$ cd python-kasa +$ python -m devtools.dump_devinfo --username --password --host 192.168.1.123 +``` + +```{note} +You can also execute the script against a network by using `--target`: `python -m devtools.dump_devinfo --target network 192.168.1.255` +``` + +The script will run queries against the device, and prompt at the end if you want to save the results. +If you choose to do so, it will save the fixture files directly in their correct place to make it easy to create a pull request. + +```{note} +When adding new fixture files, you should run `pre-commit run -a` to re-generate the list of supported devices. +You should also adjust `conftest.py` to add the new model into correct category and verify that test pass by executing `pytest kasa`. +``` diff --git a/docs/source/index.rst b/docs/source/index.rst index 9dc648a9c..f5baf3894 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,6 +10,7 @@ discover smartdevice design + contribute smartbulb smartplug smartdimmer From 5f33934a9d74e118225ff3faa8490032d3118b1a Mon Sep 17 00:00:00 2001 From: Teemu Rytilahti Date: Sun, 5 May 2024 18:10:51 +0200 Subject: [PATCH 2/3] Add CONTRIBUTING.md --- CONTRIBUTING.md | 4 ++++ docs/source/contribute.md | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..1f4005438 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,4 @@ +# Contributing to python-kasa + +All types of contributions are very welcome. +To make the process as straight-forward as possible, we have written [some instructions in our docs](https://python-miio.readthedocs.io/en/latest/contribute.html) to get you started. diff --git a/docs/source/contribute.md b/docs/source/contribute.md index e8f8796b6..39a786e8a 100644 --- a/docs/source/contribute.md +++ b/docs/source/contribute.md @@ -1,7 +1,7 @@ # Contributing You probably arrived to this page as you are interested in contributing to python-kasa in some form? -All types of contributions are very welcome, so thank you already! +All types of contributions are very welcome, so thank you! This page aims to help you to get started. ```{contents} Contents From 15afa92367340700f45f8b2f5177866c9d02e45a Mon Sep 17 00:00:00 2001 From: Teemu R Date: Tue, 7 May 2024 14:49:50 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Steven B. <51370195+sdb9696@users.noreply.github.com> --- README.md | 2 +- docs/source/contribute.md | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4d029f646..11c50ccdb 100644 --- a/README.md +++ b/README.md @@ -185,7 +185,7 @@ The device type specific documentation can be found in their separate pages: ## Contributing -Contributions are very welcome! To simplify the process, we are leveraging automated checks and tests for contributions. +Contributions are very welcome! The easiest way to contribute is by [creating a fixture file](https://python-kasa.readthedocs.io/en/latest/contribute.html#contributing-fixture-files) for the automated test suite if your device hardware and firmware version is not currently listed as supported. Please refer to [our contributing guidelines](https://python-kasa.readthedocs.io/en/latest/contribute.html). ## Supported devices diff --git a/docs/source/contribute.md b/docs/source/contribute.md index 39a786e8a..67291eba1 100644 --- a/docs/source/contribute.md +++ b/docs/source/contribute.md @@ -36,7 +36,7 @@ You can also execute the pre-commit hooks on all files by executing `pre-commit You can run tests on the library by executing `pytest` in the source directory: ``` -$ pytest kasa +$ poetry run pytest kasa ``` This will run the tests against the contributed example responses. @@ -68,6 +68,8 @@ The easiest way to do that is by doing: ``` $ git clone https://github.com/python-kasa/python-kasa.git $ cd python-kasa +$ poetry install +$ poetry shell $ python -m devtools.dump_devinfo --username --password --host 192.168.1.123 ``` @@ -80,5 +82,5 @@ If you choose to do so, it will save the fixture files directly in their correct ```{note} When adding new fixture files, you should run `pre-commit run -a` to re-generate the list of supported devices. -You should also adjust `conftest.py` to add the new model into correct category and verify that test pass by executing `pytest kasa`. +You may need to adjust `device_fixtures.py` to add a new model into the correct device categories. Verify that test pass by executing `poetry run pytest kasa`. ```