pyvesync 3.1.2__tar.gz → 3.1.4__tar.gz

{pyvesync-3.1.2/src/pyvesync.egg-info → pyvesync-3.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyvesync
-Version: 3.1.2
+Version: 3.1.4
 Summary: pyvesync is a library to manage Etekcity Devices, Cosori Air Fryers, and Levoit Air Purifiers run on the VeSync app.
 Author: Mark Perdue
 Author-email: Joe Trabulsy <webdjoe@gmail.com>
@@ -101,13 +101,9 @@ async def main():
         country_code="US",  # Optional - country Code to select correct server
         session=session,  # Optional - aiohttp.ClientSession
         time_zone="America/New_York",  # Optional - Timezone, defaults to America/New_York
-        debug=False,  # Optional - Debug output
         redact=True  # Optional - Redact sensitive information from logs
         ) as manager:
 
-        # To enable debug mode - prints request and response content for
-        # api calls that return an error code
-        manager.debug = True
         # Redact mode is enabled by default, set to False to disable
         manager.redact = False
 
@@ -194,8 +190,7 @@ VeSync(
     password: str,
     country_code: str = DEFAULT_COUNTRY_CODE,  # US
     session: ClientSession | None = None,
-    time_zone: str = DEFAULT_TZ  # America/New_York
-    debug: bool = False,
+    time_zone: str = DEFAULT_TZ  # America/New_York,
     redact: bool = True,
     )
 ```
@@ -325,7 +320,7 @@ from pyvesync import VeSync
 from pyvesync.logs import VeSyncLoginError
 
 # VeSync is an asynchronous context manager
-# VeSync(username, password, debug=False, redact=True, session=None)
+# VeSync(username, password, redact=True, session=None)
 
 async def main():
     async with VeSync("user", "password") as manager:
@@ -350,7 +345,7 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-If you want to reuse your token and account_id between runs. The `VeSync.auth` object holds the credentials and helper methods to save and load credentials.
+If you want to reuse your token and account_id between runs. The `VeSync.auth` object holds the credentials and helper methods to save and load credentials.  See the [Authentication Documentation](https://webdjoe.github.io/pyvesync/latest/authentication.md) for more details.
 
 ```python
 import asyncio
@@ -358,7 +353,7 @@ from pyvesync import VeSync
 from pyvesync.logs import VeSyncLoginError
 
 # VeSync is an asynchronous context manager
-# VeSync(username, password, debug=False, redact=True, session=None)
+# VeSync(username, password, redact=True, session=None)
 
 async def main():
     async with VeSync("user", "password") as manager:
@@ -403,7 +398,7 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-Devices are stored in the respective lists in the instantiated `VeSync` class:
+Devices are stored in the `VeSync.devices` attribute, which is a `DeviceContainer` instance that acts as a mutable set. The `DeviceContainer` has properties for each product type that return lists of device instances:
 
 ```python
 await manager.login()  # Asynchronous
@@ -440,15 +435,22 @@ See the [device documentation](https://webdjoe.github.io/pyvesync/latest/devices
 
 ## Debug mode and redact
 
-To make it easier to debug, there is a `debug` argument in the `VeSync` method. This prints out your device list and any other debug log messages.
+To set debug, use the `logger` object in the `VeSync` class. Setting the logger level to `DEBUG` will print debug information to the console. The `log_to_file()` method can be used to log to a file.
 
 The `redact` argument removes any tokens and account identifiers from the output to allow for easier sharing. The `redact` argument has no impact if `debug` is not `True`.
 
+This is an example of debug mode with redact enabled:
+
 ```python
+import logging
 import asyncio
 import aiohttp
 from pyvesync.vesync import VeSync
 
+logger = logging.getLogger("pyvesync")
+logger.setLevel(logging.DEBUG)
+
+
 async def main():
     async with VeSync("user", "password") as manager:
         manager.debug = True
@@ -466,6 +468,31 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+### Logging to File
+
+To log to a file, use the `log_to_file()` method of the `VeSync` class. Pass the file path as an argument.
+
+```python
+
+import asyncio
+from pyvesync import VeSync
+
+async def main():
+    async with VeSync("user", "password") as manager:
+        manager.log_to_file("pyvesync.log", level=logging.DEBUG, stdout=True)  # stdout argument prints log to console as well
+        await manager.login()
+        await manager.update()
+
+        outlet = manager.outlets[0]
+        await outlet.update()
+        await outlet.turn_off()
+        outlet.display()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+```
+
 ## Feature Requests
 
 Before filing an issue to request a new feature or device, please ensure that you will take the time to test the feature throuroughly. New features cannot be simply tested on Home Assistant. A separate integration must be created which is not part of this library. In order to test a new feature, clone the branch and install into a new virtual environment.
@@ -492,7 +519,7 @@ pip install git+https://github.com/webdjoe/pyvesync.git@refs/pull/PR_NUMBER/head
 
 Test functionality with a script, please adjust methods and logging statements to the device you are testing.
 
-`test.py`
+See `[testing_scripts](./testing_scripts/README.md)` for a fully functioning test script for all devices.
 
 ```python
 import asyncio
@@ -502,7 +529,10 @@ import json
 from functool import chain
 from pyvesync import VeSync
 
-logger = logging.getLogger(__name__)
+vs_logger = logging.getLogger("pyvesync")
+vs_logger.setLevel(logging.DEBUG)
+
+logger = logging.getLogger('pyvesync_test')
 logger.setLevel(logging.DEBUG)
 
 USERNAME = "YOUR USERNAME"
@@ -512,7 +542,7 @@ DEVICE_NAME = "Device" # Device to test
 
 async def test_device():
     # Instantiate VeSync class and login
-  async with VeSync(USERNAME, PASSWORD, debug=True, redact=True) as manager:
+  async with VeSync(USERNAME, PASSWORD, redact=True) as manager:
       await manager.login()
 
       # Pull and update devices
@@ -571,35 +601,11 @@ if __name__ == "__main__":
 
 ## Device Requests
 
-SSL pinning makes capturing packets much harder. In order to be able to capture packets, SSL pinning needs to be disabled before running an SSL proxy. Use an Android emulator such as Android Studio, which is available for Windows and Linux for free. Download the APK from APKPure or a similiar site and use [Objection](https://github.com/sensepost/objection) or [Frida](https://frida.re/docs/gadget/). Followed by capturing the packets with Charles Proxy or another SSL proxy application.
-
-Be sure to capture all packets from the device list and each of the possible device menus and actions. Please redact the `accountid` and `token` from the captured packets. If you feel you must redact other keys, please do not delete them entirely. Replace letters with "A" and numbers with "1", leave all punctuation intact and maintain length.
-
-For example:
-
-Before:
-
-```json
-{
-  "tk": "abc123abc123==3rf",
-  "accountId": "123456789",
-  "cid": "abcdef12-3gh-ij"
-}
-```
-
-After:
-
-```json
-{
-  "tk": "AAA111AAA111==1AA",
-  "accountId": "111111111",
-  "cid": "AAAAAA11-1AA-AA"
-}
-```
+If you would like to request a new device to be added to the library, please open an issue on GitHub. Be sure to include the device model number and a link to the product page. If you are able to provide packet captures or are willing to share the device temporarily, please indicate that in the issue. See the [Packet Capturing for New Device Support](https://webdjoe.github.io/pyvesync/latest/development/capturing.md) document for more details.
 
 ## Contributing
 
-All [contributions](CONTRIBUTING.md) are welcome.
+All [contributions](https://webdjoe.github.io/pyvesync/latest/development/CONTRIBUTING.md) are welcome.
 
 This project is licensed under [MIT](LICENSE).
 

{pyvesync-3.1.2 → pyvesync-3.1.4}/README.md

@@ -55,13 +55,9 @@ async def main():
         country_code="US",  # Optional - country Code to select correct server
         session=session,  # Optional - aiohttp.ClientSession
         time_zone="America/New_York",  # Optional - Timezone, defaults to America/New_York
-        debug=False,  # Optional - Debug output
         redact=True  # Optional - Redact sensitive information from logs
         ) as manager:
 
-        # To enable debug mode - prints request and response content for
-        # api calls that return an error code
-        manager.debug = True
         # Redact mode is enabled by default, set to False to disable
         manager.redact = False
 
@@ -148,8 +144,7 @@ VeSync(
     password: str,
     country_code: str = DEFAULT_COUNTRY_CODE,  # US
     session: ClientSession | None = None,
-    time_zone: str = DEFAULT_TZ  # America/New_York
-    debug: bool = False,
+    time_zone: str = DEFAULT_TZ  # America/New_York,
     redact: bool = True,
     )
 ```
@@ -279,7 +274,7 @@ from pyvesync import VeSync
 from pyvesync.logs import VeSyncLoginError
 
 # VeSync is an asynchronous context manager
-# VeSync(username, password, debug=False, redact=True, session=None)
+# VeSync(username, password, redact=True, session=None)
 
 async def main():
     async with VeSync("user", "password") as manager:
@@ -304,7 +299,7 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-If you want to reuse your token and account_id between runs. The `VeSync.auth` object holds the credentials and helper methods to save and load credentials.
+If you want to reuse your token and account_id between runs. The `VeSync.auth` object holds the credentials and helper methods to save and load credentials.  See the [Authentication Documentation](https://webdjoe.github.io/pyvesync/latest/authentication.md) for more details.
 
 ```python
 import asyncio
@@ -312,7 +307,7 @@ from pyvesync import VeSync
 from pyvesync.logs import VeSyncLoginError
 
 # VeSync is an asynchronous context manager
-# VeSync(username, password, debug=False, redact=True, session=None)
+# VeSync(username, password, redact=True, session=None)
 
 async def main():
     async with VeSync("user", "password") as manager:
@@ -357,7 +352,7 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-Devices are stored in the respective lists in the instantiated `VeSync` class:
+Devices are stored in the `VeSync.devices` attribute, which is a `DeviceContainer` instance that acts as a mutable set. The `DeviceContainer` has properties for each product type that return lists of device instances:
 
 ```python
 await manager.login()  # Asynchronous
@@ -394,15 +389,22 @@ See the [device documentation](https://webdjoe.github.io/pyvesync/latest/devices
 
 ## Debug mode and redact
 
-To make it easier to debug, there is a `debug` argument in the `VeSync` method. This prints out your device list and any other debug log messages.
+To set debug, use the `logger` object in the `VeSync` class. Setting the logger level to `DEBUG` will print debug information to the console. The `log_to_file()` method can be used to log to a file.
 
 The `redact` argument removes any tokens and account identifiers from the output to allow for easier sharing. The `redact` argument has no impact if `debug` is not `True`.
 
+This is an example of debug mode with redact enabled:
+
 ```python
+import logging
 import asyncio
 import aiohttp
 from pyvesync.vesync import VeSync
 
+logger = logging.getLogger("pyvesync")
+logger.setLevel(logging.DEBUG)
+
+
 async def main():
     async with VeSync("user", "password") as manager:
         manager.debug = True
@@ -420,6 +422,31 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+### Logging to File
+
+To log to a file, use the `log_to_file()` method of the `VeSync` class. Pass the file path as an argument.
+
+```python
+
+import asyncio
+from pyvesync import VeSync
+
+async def main():
+    async with VeSync("user", "password") as manager:
+        manager.log_to_file("pyvesync.log", level=logging.DEBUG, stdout=True)  # stdout argument prints log to console as well
+        await manager.login()
+        await manager.update()
+
+        outlet = manager.outlets[0]
+        await outlet.update()
+        await outlet.turn_off()
+        outlet.display()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+```
+
 ## Feature Requests
 
 Before filing an issue to request a new feature or device, please ensure that you will take the time to test the feature throuroughly. New features cannot be simply tested on Home Assistant. A separate integration must be created which is not part of this library. In order to test a new feature, clone the branch and install into a new virtual environment.
@@ -446,7 +473,7 @@ pip install git+https://github.com/webdjoe/pyvesync.git@refs/pull/PR_NUMBER/head
 
 Test functionality with a script, please adjust methods and logging statements to the device you are testing.
 
-`test.py`
+See `[testing_scripts](./testing_scripts/README.md)` for a fully functioning test script for all devices.
 
 ```python
 import asyncio
@@ -456,7 +483,10 @@ import json
 from functool import chain
 from pyvesync import VeSync
 
-logger = logging.getLogger(__name__)
+vs_logger = logging.getLogger("pyvesync")
+vs_logger.setLevel(logging.DEBUG)
+
+logger = logging.getLogger('pyvesync_test')
 logger.setLevel(logging.DEBUG)
 
 USERNAME = "YOUR USERNAME"
@@ -466,7 +496,7 @@ DEVICE_NAME = "Device" # Device to test
 
 async def test_device():
     # Instantiate VeSync class and login
-  async with VeSync(USERNAME, PASSWORD, debug=True, redact=True) as manager:
+  async with VeSync(USERNAME, PASSWORD, redact=True) as manager:
       await manager.login()
 
       # Pull and update devices
@@ -525,35 +555,11 @@ if __name__ == "__main__":
 
 ## Device Requests
 
-SSL pinning makes capturing packets much harder. In order to be able to capture packets, SSL pinning needs to be disabled before running an SSL proxy. Use an Android emulator such as Android Studio, which is available for Windows and Linux for free. Download the APK from APKPure or a similiar site and use [Objection](https://github.com/sensepost/objection) or [Frida](https://frida.re/docs/gadget/). Followed by capturing the packets with Charles Proxy or another SSL proxy application.
-
-Be sure to capture all packets from the device list and each of the possible device menus and actions. Please redact the `accountid` and `token` from the captured packets. If you feel you must redact other keys, please do not delete them entirely. Replace letters with "A" and numbers with "1", leave all punctuation intact and maintain length.
-
-For example:
-
-Before:
-
-```json
-{
-  "tk": "abc123abc123==3rf",
-  "accountId": "123456789",
-  "cid": "abcdef12-3gh-ij"
-}
-```
-
-After:
-
-```json
-{
-  "tk": "AAA111AAA111==1AA",
-  "accountId": "111111111",
-  "cid": "AAAAAA11-1AA-AA"
-}
-```
+If you would like to request a new device to be added to the library, please open an issue on GitHub. Be sure to include the device model number and a link to the product page. If you are able to provide packet captures or are willing to share the device temporarily, please indicate that in the issue. See the [Packet Capturing for New Device Support](https://webdjoe.github.io/pyvesync/latest/development/capturing.md) document for more details.
 
 ## Contributing
 
-All [contributions](CONTRIBUTING.md) are welcome.
+All [contributions](https://webdjoe.github.io/pyvesync/latest/development/CONTRIBUTING.md) are welcome.
 
 This project is licensed under [MIT](LICENSE).
 

{pyvesync-3.1.2 → pyvesync-3.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyvesync"
-version = "3.1.2"
+version = "3.1.4"
 description = "pyvesync is a library to manage Etekcity Devices, Cosori Air Fryers, and Levoit Air Purifiers run on the VeSync app."
 readme = "README.md"
 requires-python = ">=3.11"

{pyvesync-3.1.2 → pyvesync-3.1.4}/src/pyvesync/auth.py

@@ -64,8 +64,6 @@ class VeSyncAuth:
             username: VeSync account username (email)
             password: VeSync account password
             country_code: Country code in ISO 3166 Alpha-2 format
-            current_region: Current region code - determines API base URL
-            token_file_path: Path to store/load authentication token
 
         Note:
             Either username/password or token/account_id must be provided.
@@ -174,7 +172,7 @@ class VeSyncAuth:
         else:
             file_path_object = Path(file_path)
         if not file_path_object or not file_path_object.exists():
-            logger.debug('No token file found to load credentials')
+            logger.debug('Credentials file not found: %s', file_path_object)
             return False
         try:
             data = await asyncio.to_thread(
@@ -184,7 +182,7 @@ class VeSyncAuth:
             self._token = data['token']
             self._account_id = data['account_id']
             self._country_code = data['country_code'].upper()
-            self._current_region = data['current_region']
+            self._current_region = data['current_region'].upper()
             logger.debug('Credentials loaded from file: %s', file_path)
         except orjson.JSONDecodeError as exc:
             logger.warning('Failed to load credentials from file: %s', exc)
@@ -196,17 +194,26 @@ class VeSyncAuth:
         self.manager.enabled = True
         return True
 
-    def output_credentials(self) -> str | None:
-        """Output current credentials as JSON string."""
+    def output_credentials_dict(self) -> dict[str, str] | None:
+        """Output current credentials as a dictionary."""
         if not self.is_authenticated:
             logger.debug('No credentials to output, not authenticated')
             return None
-        credentials = {
-            'token': self._token,
-            'account_id': self._account_id,
+        return {
+            'token': self._token or '',
+            'account_id': self._account_id or '',
             'country_code': self._country_code,
             'current_region': self._current_region,
         }
+
+    def output_credentials_json(self) -> str | None:
+        """Output current authentication credentials as a JSON string."""
+        if not self.is_authenticated:
+            logger.debug('No credentials to output, not authenticated')
+            return None
+        credentials = self.output_credentials_dict()
+        if credentials is None:
+            return None
         try:
             return orjson.dumps(credentials).decode('utf-8')
         except orjson.JSONEncodeError as exc:

{pyvesync-3.1.2 → pyvesync-3.1.4}/src/pyvesync/base_devices/fan_base.py

@@ -21,7 +21,7 @@ logger = logging.getLogger(__name__)
 
 
 class FanState(DeviceState):
-    """Base state class for Purifiers.
+    """Base state class for Fans.
 
     Not all attributes are supported by all devices.
 
@@ -73,7 +73,7 @@ class FanState(DeviceState):
         details: ResponseDeviceDetailsModel,
         feature_map: FanMap,
     ) -> None:
-        """Initialize Purifier State.
+        """Initialize Fan State.
 
         Args:
             device (VeSyncFanBase): Device object.
@@ -187,7 +187,7 @@ class VeSyncFanBase(VeSyncBaseToggleDevice):
 
     @abstractmethod
     async def set_mode(self, mode: str) -> bool:
-        """Set Purifier Mode.
+        """Set Fan Mode.
 
         Args:
             mode (str): Mode to set, varies by device type.
@@ -198,7 +198,7 @@ class VeSyncFanBase(VeSyncBaseToggleDevice):
 
     @abstractmethod
     async def set_fan_speed(self, speed: int | None = None) -> bool:
-        """Set Purifier Fan Speed.
+        """Set Fan Fan Speed.
 
         Args:
             speed (int, optional): Fan speed level according to device specs.
@@ -208,7 +208,7 @@ class VeSyncFanBase(VeSyncBaseToggleDevice):
         """
 
     async def set_auto_mode(self) -> bool:
-        """Set Purifier to Auto Mode.
+        """Set Fan to Auto Mode.
 
         Returns:
             bool: Success of request.
@@ -223,7 +223,7 @@ class VeSyncFanBase(VeSyncBaseToggleDevice):
         return False
 
     async def set_advanced_sleep_mode(self) -> bool:
-        """Set Purifier to Advanced Sleep Mode.
+        """Set Fan to Advanced Sleep Mode.
 
         Returns:
             bool: Success of request.
@@ -238,7 +238,7 @@ class VeSyncFanBase(VeSyncBaseToggleDevice):
         return False
 
     async def set_sleep_mode(self) -> bool:
-        """Set Purifier to Sleep Mode.
+        """Set Fan to Sleep Mode.
 
         This is also referred to as Advanced Sleep Mode on some devices.
 
@@ -255,7 +255,7 @@ class VeSyncFanBase(VeSyncBaseToggleDevice):
         return False
 
     async def set_manual_mode(self) -> bool:
-        """Set Purifier to Manual Mode - Normal Mode.
+        """Set Fan to Manual Mode - Normal Mode.
 
         Returns:
             bool: Success of request.
@@ -270,7 +270,7 @@ class VeSyncFanBase(VeSyncBaseToggleDevice):
         return False
 
     async def set_normal_mode(self) -> bool:
-        """Set Purifier to Normal Mode.
+        """Set Fan to Normal Mode.
 
         Returns:
             bool: Success of request.
@@ -285,7 +285,7 @@ class VeSyncFanBase(VeSyncBaseToggleDevice):
         return False
 
     async def set_turbo_mode(self) -> bool:
-        """Set Purifier to Turbo Mode.
+        """Set Fan to Turbo Mode.
 
         Returns:
             bool: Success of request.

{pyvesync-3.1.2 → pyvesync-3.1.4}/src/pyvesync/base_devices/humidifier_base.py

@@ -6,8 +6,6 @@ import logging
 from abc import abstractmethod
 from typing import TYPE_CHECKING
 
-from typing_extensions import deprecated
-
 from pyvesync.base_devices.vesyncbasedevice import DeviceState, VeSyncBaseToggleDevice
 from pyvesync.const import DeviceStatus, HumidifierFeatures, HumidifierModes
 
@@ -128,16 +126,6 @@ class HumidifierState(DeviceState):
         """
         return self.automatic_stop_config
 
-    @property
-    @deprecated('Use auto_stop_target_reached instead.')
-    def automatic_stop_target_reached(self) -> bool:
-        """Deprecated function.
-
-        Returns:
-            bool: True if automatic stop target is reached, False otherwise.
-        """
-        return self.auto_stop_target_reached
-
     @property
     def target_humidity(self) -> int | None:
         """Return the target humidity level.
@@ -161,16 +149,6 @@ class HumidifierState(DeviceState):
         """Return True if auto mode is enabled."""
         return self.mode in [HumidifierModes.AUTO, self.mode, HumidifierModes.HUMIDITY]
 
-    @property
-    @deprecated('Use humidity property instead.')
-    def humidity_level(self) -> int | None:
-        """Deprecated function.
-
-        Returns:
-            int | None: Humidity level.
-        """
-        return self.humidity
-
     @property
     def drying_mode_state(self) -> str | None:
         """Return the drying mode state.