Merge pull request #76 from vchrisb/pyright

* added type hints
* added pyright static type checking
* code refactoring
* web connection is only using rscp via websocket
* enhanced test scripts

Author: vchrisb

.github/workflows/validate.yml

@@ -17,12 +17,14 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install black flake8 flake8-docstrings isort
+          pip install .[develop]
       - name: Run flake8
         run: flake8
       - name: Run isort
         run: isort ./ --check
       - name: Run black
         run: black ./ --check
+      - name: Run pyright
+        run: pyright
       - name: Run test install
         run: pip install .

README.md

@@ -30,9 +30,7 @@ This package can be installed from pip:
 
 `pip install pye3dc`
 
-## Local Connection
-
-### Configuration
+## Configuration
 
 There is a great variety of E3/DC implementation configurations, that can't automatically be detected. For example the `index` of the root power meter can be either `0` or `6`, depending how the system was installed. Additional power meter can have an ID of `1-4` and there might be also multiple inverter.
 This library assumes, that there is one inverter installed and the root power meter has an index of `6` for S10 mini and `0` for other systems.
@@ -64,7 +62,9 @@ For any other configurations, there is an optional `configuration` object that c
 
 > Note: Not all options need to be configured.
 
-### Usage
+## Usage
+
+### Local Connection
 
 An example script using the library is the following:
 
@@ -79,13 +79,34 @@ CONFIG = {}
 # CONFIG = {"powermeters": [{"index": 6}]}
 
 print("local connection")
-e3dc = E3DC(E3DC.CONNECT_LOCAL, username=USERNAME, password=PASS, ipAddress = TCP_IP, key = KEY, configuration = CONFIG)
+e3dc_obj = E3DC(E3DC.CONNECT_LOCAL, username=USERNAME, password=PASS, ipAddress = TCP_IP, key = KEY, configuration = CONFIG)
 # The following connections are performed through the RSCP interface
-print(e3dc.poll())
-print(e3dc.get_pvi_data())
+print(e3dc_obj.poll(keepAlive=True))
+print(e3dc_obj.get_pvi_data(keepAlive=True))
+e3dc_obj.disconnect()
+```
+
+### Web Connection
+
+An example script using the library is the following:
+
+```python
+from e3dc import E3DC
+
+USERNAME = 'test@test.com'
+PASS = 'MySecurePassword'
+SERIALNUMBER = 'S10-012345678910'
+CONFIG = {} 
+
+print("web connection")
+e3dc_obj = E3DC(E3DC.CONNECT_WEB, username=USERNAME, password=PASS, serialNumber = SERIALNUMBER, isPasswordMd5=False, configuration = CONFIG)
+# connect to the portal and poll the status. This might raise an exception in case of failed login. This operation is performed with Ajax
+print(e3dc_obj.poll(keepAlive=True))
+print(e3dc_obj.get_pvi_data(keepAlive=True))
+e3dc_obj.disconnect()
 ```
 
-### poll() return values
+## Example: poll() return values
 
 Poll returns a dictionary like the following:
 
@@ -108,7 +129,7 @@ Poll returns a dictionary like the following:
 }
 ```
 
-### Available methods
+## Available methods
 
 - `poll()`
 - `get_system_info()`
@@ -117,10 +138,13 @@ Poll returns a dictionary like the following:
 - `get_idle_periods()`
 - `set_idle_periods()`
 - `get_db_data()`
+- `get_batteries()`
 - `get_battery_data()`
 - `get_batteries_data()`
+- `get_pvis()`
 - `get_pvi_data()`
 - `get_pvis_data()`
+- `get_powermeters()`
 - `get_powermeter_data()`
 - `get_powermeters_data()`
 - `get_power_settings()`
@@ -130,34 +154,12 @@ Poll returns a dictionary like the following:
 
 See the full documentation on [ReadTheDocs](https://python-e3dc.readthedocs.io/en/latest/)
 
-### Note: The RSCP interface
+## Note: The RSCP interface
 
 The communication to an E3/DC system has to be implemented via a rather complicated protocol, called by E3/DC RSCP. This protocol is binary and based on websockets. The documentation provided by E3/DC is limited and outdated. It can be found in the E3/DC download portal.
 
 If keepAlive is false, the websocket connection is closed after the command. This makes sense because these requests are not meant to be made as often as the status requests, however, if keepAlive is True, the connection is left open and kept alive in the background in a separate thread.
 
-## Web connection
-
-### Usage
-
-An example script using the library is the following:
-
-```python
-from e3dc import E3DC
-
-TCP_IP = '192.168.1.57'
-USERNAME = 'test@test.com'
-PASS = 'MySecurePassword'
-SERIALNUMBER = '1234567890'
-
-print("web connection")
-e3dc = E3DC(E3DC.CONNECT_WEB, username=USERNAME, password=PASS, serialNumber = SERIALNUMBER, isPasswordMd5=False)
-# connect to the portal and poll the status. This might raise an exception in case of failed login. This operation is performed with Ajax
-print(e3dc.poll())
-# Poll the status of the switches using a remote RSCP connection via websockets
-# return value is in the format {'id': switchID, 'type': switchType, 'name': switchName, 'status': switchStatus}
-print(e3dc.poll_switches())
-```
 
 ## Known limitations
 
@@ -174,6 +176,8 @@ One limitation of the package concerns the implemented RSCP methods. This projec
 
 - Open an issue before making a pull request
 - Note the E3/DC system you tested with and implementation details
-- Pull request checks will enforce code styling (black, flake8, flake8-docstrings, isort)
+- Pull request checks will enforce code styling
+  - Install development dependencies `pip install -U --upgrade-strategy eager .[develop]`
+  - Run `tools/validate.sh` before creating a commit.
 - Make sure to support Python versions >= 3.8
 - Consider adding yourself to `AUTHORS`

e3dc/_RSCPEncryptDecrypt.py

@@ -1,6 +1,8 @@
+from __future__ import annotations  # required for python < 3.9
+
 import math
 
-from py3rijndael import RijndaelCbc, ZeroPadding
+from py3rijndael import RijndaelCbc, ZeroPadding  # type: ignore
 
 KEY_SIZE = 32
 BLOCK_SIZE = 32
@@ -12,7 +14,7 @@ class ParameterError(Exception):
     pass
 
 
-def zeroPad_multiple(string, value):
+def zeroPad_multiple(string: bytes, value: int) -> bytes:
     """Zero padding string."""
     length = len(string)
     if length % value == 0:
@@ -21,7 +23,7 @@ def zeroPad_multiple(string, value):
     return string.ljust(newL, b"\x00")
 
 
-def truncate_multiple(string, value):
+def truncate_multiple(string: bytes, value: int) -> bytes:
     """Truncating sting."""
     length = len(string)
     if length % value == 0:
@@ -33,22 +35,21 @@ def truncate_multiple(string, value):
 class RSCPEncryptDecrypt:
     """A class for encrypting and decrypting RSCP data."""
 
-    def __init__(self, key):
+    def __init__(self, key: bytes):
         """Constructor of a RSCP encryption and decryption class.
 
         Args:
-            key (str): RSCP encryption key
+            key (bytes): RSCP encryption key
         """
         if len(key) > KEY_SIZE:
             raise ParameterError("Key must be <%d bytes" % (KEY_SIZE))
-
         self.key = key.ljust(KEY_SIZE, b"\xff")
         self.encryptIV = b"\xff" * BLOCK_SIZE
         self.decryptIV = b"\xff" * BLOCK_SIZE
         self.remainingData = b""
         self.oldDecrypt = b""
 
-    def encrypt(self, plainText):
+    def encrypt(self, plainText: bytes) -> bytes:
         """Method to encryt plain text."""
         encryptor = RijndaelCbc(
             self.key,
@@ -60,7 +61,9 @@ def encrypt(self, plainText):
         self.encryptIV = encText[-BLOCK_SIZE:]
         return encText
 
-    def decrypt(self, encText, previouslyProcessedData=None):
+    def decrypt(
+        self, encText: bytes, previouslyProcessedData: int | None = None
+    ) -> bytes:
         """Method to decryt encrypted text."""
         if previouslyProcessedData is None:
             length = len(self.oldDecrypt)
@@ -92,4 +95,4 @@ def decrypt(self, encText, previouslyProcessedData=None):
             padding=ZeroPadding(BLOCK_SIZE),
             block_size=BLOCK_SIZE,
         )
-        return decryptor.decrypt(toDecrypt)
+        return decryptor.decrypt(toDecrypt)  # pyright: ignore [reportUnknownMemberType]

e3dc/__init__.py

@@ -5,7 +5,7 @@
 Licensed under a MIT license. See LICENSE for details.
 """
 
-from ._e3dc import E3DC, AuthenticationError, PollError
+from ._e3dc import E3DC, AuthenticationError, NotAvailableError, PollError, SendError
 from ._e3dc_rscp_local import CommunicationError, RSCPAuthenticationError, RSCPKeyError
 from ._e3dc_rscp_web import RequestTimeoutError, SocketNotReady
 from ._rscpLib import FrameError