mirror of
https://github.com/python-kasa/python-kasa.git
synced 2024-12-22 19:23:34 +00:00
Move contribution instructions into docs (#901)
Moves the instructions away from README.md to keep it simpler, and extend the documentation to be up-to-date and easier to approach. --------- Co-authored-by: Steven B. <51370195+sdb9696@users.noreply.github.com>
This commit is contained in:
parent
353e84438c
commit
1e8e289ac7
4
CONTRIBUTING.md
Normal file
4
CONTRIBUTING.md
Normal file
@ -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.
|
36
README.md
36
README.md
@ -185,42 +185,12 @@ 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 <address>
|
||||
```
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
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).
|
||||
|
||||
<!--Do not edit text inside the SUPPORTED section below -->
|
||||
<!--SUPPORTED_START-->
|
||||
|
86
docs/source/contribute.md
Normal file
86
docs/source/contribute.md
Normal file
@ -0,0 +1,86 @@
|
||||
# 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!
|
||||
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:
|
||||
|
||||
```
|
||||
$ poetry run 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 <address>`.
|
||||
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
|
||||
$ poetry install
|
||||
$ poetry shell
|
||||
$ python -m devtools.dump_devinfo --username <username> --password <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 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`.
|
||||
```
|
@ -10,6 +10,7 @@
|
||||
discover
|
||||
smartdevice
|
||||
design
|
||||
contribute
|
||||
smartbulb
|
||||
smartplug
|
||||
smartdimmer
|
||||
|
Loading…
Reference in New Issue
Block a user