1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
|
# Contributing to pyvesync
Contributions are welcome! Please follow the guidelines below to ensure a quick and smooth review process.
Uses the [pre-commit](https://pre-commit.com/) framework to manage and maintain code quality. This is automatically run on `commit` to check for formatting and linting issues by the `pre-commit.ci` service. Running this manually is not required, but recommended to ensure a clean commit:
```bash
pre-commit run
```
**NOTE:** Changes must be staged in order for this to work properly.
## Code Style
### General Style Guidelines
- Single quotes for strings, except when the string contains a single quote or is a docstring.
- Use f-strings for string formatting.
- Use type hinting for function signatures and variable declarations.
- Docstrings for all public classes, methods and functions. Not required for inherited methods and properties.
- Constants should be stored in the `const` module, there should be no hardcoded strings or numbers in the code.
- Line length is limited to 90 characters.
- Classes and public variables must be camel cased.
- Local variables, methods and properties must be snake cased.
- Imports must be sorted and grouped by standard library, third party and local imports.
### Device Method and Attribute Naming
- All states specific to a device type must be stored in the `DeviceState` class in the base device type module. For example, `SwitchState` for switches, `PurifierState` for purifiers, etc.
- All device properties and methods are to be created in the specific device type base class, not in the implementation device class.
- All device methods that set one or the other binary state must be named `turn_<state>_on()` or `turn_<state>_off()`. For example, `turn_on()`, `turn_off()`, `turn_child_lock_on()`, `turn_child_lock_off()`.
- The `turn_on()` and `turn_off()` are specific methods that use the `toggle_switch()` method. Any method that toggles a binary state must be named `toggle_<state>()`. For example, `toggle_lock()`, `toggle_mute()`, `toggle_child_lock()`.
- Methods that set a specific state that is not on/off must be named `set_<state>()`. For example, `set_brightness()`, `set_color()`, `set_temperature()`.
## Testing and Linting
For convenience, the `tox` can be used to run tests and linting. This requires `tox` to be installed in your Python environment.
To run all tests and linting:
```bash
tox
```
Specific test environments:
```bash
tox -e py38 # Run tests with Python 3.8
tox -e py39 # Run tests with Python 3.9
tox -e py310 # Run tests with Python 3.10
tox -e py311 # Run tests with Python 3.11
tox -e lint # Run pylint checks
tox -e ruff # Run ruff checks
tox -e mypy # Run mypy type checks
```
## Requests to Add Devices
Please see [CAPTURING.md](./capturing.md) for instructions on how to capture the necessary information to add a new device.
|
