Merge pull request #503 from uzlonewolf/argparse

Rewrite main to use argparse and add additional options

.github/workflows/contrib.yml

@@ -14,7 +14,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ["3.6", "3.7", "3.8"]
+        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
       - uses: "actions/checkout@v2"

.github/workflows/test.yml

@@ -14,7 +14,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ["3.5", "3.6", "3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
       - uses: "actions/checkout@v3"

README.md

@@ -34,8 +34,11 @@ NOTE: Devices need to be **activated** by Smart Life App.
 ## TinyTuya Installation  
 
 ```bash
-# Install TinyTuya
+# Install TinyTuya Library
 python -m pip install tinytuya
+
+# Optional: Install Command Line Tool
+pipx install tinytuya
 ```
 
 Pip will attempt to install `cryptography`, `requests` and `colorama` if not already installed.
@@ -128,6 +131,7 @@ d.turn_off()
 ### TinyTuya Module Classes and Functions 
 ```
 Classes
+
   AESCipher - Cryptography Helpers
   XenonDevice(args...) - Base Class
     Device(args...) - Tuya Class for Devices
@@ -139,16 +143,20 @@ Classes
           address (str): Device Network IP Address e.g. 10.0.1.99 or "Auto" to auto-find
           local_key (str): The encryption key
           dev_type (str): Device type for payload options (see below)
-          connection_timeout = 5 (int): Timeout in seconds
           version = 3.1 (float): Tuya Protocol (e.g. 3.1, 3.2, 3.3, 3.4, 3.5)
           persist = False (bool): Keep TCP link open
           cid = None (str): Optional sub device id
           node_id = None (str): Alias for cid
           parent = None (object): Gateway device object this is a child of
+          port = TCPPORT (int): The port to connect to device
+          connection_timeout = 5 (int): Timeout in seconds
           connection_retry_limit = 5 (int)
           connection_retry_delay = 5 (int)
-          port = TCPPORT (int): The port to connect to device
 
+          Total timeout = (connection_timeout * connection_retry_limit) + 
+                          (connection_retry_delay * (connection_retry_limit - 1))
+                          Defaults: (5 * 5) + (5 * (5 - 1)) = 45 seconds
+                        
   Cloud(apiRegion, apiKey, apiSecret, apiDeviceID, new_sign_algorithm)
 
 TinyTuya Base Functions
@@ -229,7 +237,7 @@ Cloud Functions
     getdevicelog(deviceid, start=[now - 1 day], end=[now], evtype="1,2,3,4,5,6,7,8,9,10", size=100, params={})
       -> when start or end are negative, they are the number of days before "right now"
           i.e. "start=-1" is 1 day ago, "start=-7" is 7 days ago
-
+          
 ```
 
 ### TinyTuya Error Codes
@@ -429,21 +437,71 @@ Tuya devices use AES encryption which is not available in the Python standard li
 
 ### Command Line
 
+TinyTuya provides a built-in command line interface to get Local key, scan and poll devices.
+
+Installation
+
+```bash
+# Option-1: pip install tinytuya
+python -m tinytuya
+
+# Option-2: pipx install tinytuya
+tinytuya 
 ```
-python -m tinytuya <command> [<max_time>] [-debug] [-nocolor] [-force [192.168.0.0/24 192.168.1.0/24 ...]] [-h]
+
+Command Line Usage
+
+```
+tinytuya <command> [-debug] [-nocolor] [-h] [-yes] [-no-poll] [-device-file FILE] [-snapshot-file FILE]
 
   wizard         Launch Setup Wizard to get Tuya Local KEYs.
   scan           Scan local network for Tuya devices.
   devices        Scan all devices listed in devices.json file.
   snapshot       Scan devices listed in snapshot.json file.
   json           Scan devices listed in snapshot.json file [JSON].
-  <max_time>     Maximum time to find Tuya devices [Default=18]
-  -nocolor       Disable color text output.
-  -force         Force network scan of device IP addresses based on format:
-                 [net1/mask1 net2/mask2 ...] Auto-detects if none provided.
-  -no-broadcasts Ignore broadcast packets when force scanning.
-  -debug         Activate debug mode.
-  -h             Show usage.
+
+  Wizard
+      tinytuya wizard [-h] [-debug] [-force [0.0.0.0/24 ...]] [-no-broadcasts] [-nocolor] [-yes] [-no-poll]
+                [-device-file FILE] [-raw-response-file FILE] [-snapshot-file FILE] [-credentials-file FILE]
+                [-key KEY] [-secret SECRET] [-region {cn,eu,eu-w,in,us,us-e}] [-device DEVICE [DEVICE ...]]
+                [-dry-run] [max_time]
+
+        Common Options
+        max_time             Maximum time to find Tuya devices [Default: 18]
+        -no-broadcasts       Ignore broadcast packets when force scanning
+        -nocolor             Disable color text output.
+        -debug               Activate debug mode.
+        -h, -help            Show usage help for command.
+        -yes, -y             Answer "yes" to all questions
+        -no-poll, -no        Answer "no" to "Poll?" (overrides -yes)
+        -device-file FILE    JSON file to load devices from [Default: devices.json]
+        -snapshot-file FILE  JSON file to load/save snapshot from/to [Default: snapshot.json]
+        -force [0.0.0.0/24 ...], -f [0.0.0.0/24 ...]
+                             Force network scan of device IP addresses [Default: Auto-detects net/mask]
+        -no-broadcasts       Ignore broadcast packets when force scanning
+        -raw-response-file   JSON file to save the raw server response to [Default: tuya-raw.json]
+
+        Wizard Cloud API Options
+        -dry-run             Do not actually connect to the Cloud
+        -credentials-file    JSON file to load/save Cloud credentials from/to [Default: tinytuya.json]
+        -key KEY             Cloud API Key to use
+        -secret SECRET       Cloud API Secret to use
+        -region              Cloud API Region to use {cn,eu,eu-w,in,us,us-e}
+        -device DEVICE(S)    One or more Device ID(s) to use
+
+  Scan
+      tinytuya scan [-h] [-debug] [-force [0.0.0.0/24 ...]] [-no-broadcasts] [-nocolor] [-yes] 
+                [-device-file FILE] [-snapshot-file FILE] [max_time]
+
+  Devices
+      tinytuya devices [-h] [-debug] [-force [0.0.0.0/24 ...]] [-no-broadcasts] [-nocolor] [-yes] 
+                [-no-poll] [-device-file FILE] [-snapshot-file FILE] [max_time]
+
+  Snapshot
+      tinytuya snapshot [-h] [-debug] [-nocolor] [-yes] [-no-poll] [-device-file FILE] [-snapshot-file FILE]
+
+  JSON
+      tinytuya json [-h] [-debug] [-device-file FILE] [-snapshot-file FILE]
 
 ```
 

RELEASE.md

@@ -1,5 +1,12 @@
 # RELEASE NOTES
 
+## v1.14.0 - Command Line Updates
+
+* PyPI 1.14.0 rewrite of main to use argparse and add additional options by @uzlonewolf in https://github.com/jasonacox/tinytuya/pull/503
+* Add support for `pipx install tinytuya` as raised by @felipecrs in https://github.com/jasonacox/tinytuya/issues/500 allowing for easier CLI use.
+* Note possible breaking change: Running `tinytuya` by itself will now produce a "Usage" page instead of running a scan.  Use `tinytuya scan` or `python -m tinytuya scan`.
+* Updated docs to explain timeout as raised by @GamerPeggun in https://github.com/jasonacox/tinytuya/issues/501
+
 ## v1.13.2 - Contrib Updates
 
 * Add example for XmCosy+ RGBW patio string lights by @bikerglen in https://github.com/jasonacox/tinytuya/pull/445

pyproject.toml

@@ -0,0 +1,2 @@
+[build-system]
+requires = ["setuptools", "colorama", "requests", "cryptography"]

setup.py

@@ -40,6 +40,7 @@
     url='https://github.com/jasonacox/tinytuya',
     packages=setuptools.find_packages(exclude=("sandbox",)),
     install_requires=INSTALL_REQUIRES,
+    entry_points={"console_scripts": ["tinytuya=tinytuya.__main__:dummy"]},
     classifiers=[
         "Programming Language :: Python :: 3",
         "License :: OSI Approved :: MIT License",

tinytuya/BulbDevice.py

@@ -182,7 +182,7 @@ def _hexvalue_to_rgb(hexvalue, bulb="A"):
             r = int(hexvalue[0:2], 16)
             g = int(hexvalue[2:4], 16)
             b = int(hexvalue[4:6], 16)
-        if bulb == "B":
+        elif bulb == "B":
             # hexvalue is in hsv
             h = float(int(hexvalue[0:4], 16) / 360.0)
             s = float(int(hexvalue[4:8], 16) / 1000.0)
@@ -191,6 +191,9 @@ def _hexvalue_to_rgb(hexvalue, bulb="A"):
             r = int(rgb[0] * 255)
             g = int(rgb[1] * 255)
             b = int(rgb[2] * 255)
+        else:
+            # Unsupported bulb type
+            raise ValueError(f"Unsupported bulb type {bulb} - unable to determine RGB values.")
 
         return (r, g, b)
 
@@ -207,12 +210,15 @@ def _hexvalue_to_hsv(hexvalue, bulb="A"):
             h = int(hexvalue[7:10], 16) / 360.0
             s = int(hexvalue[10:12], 16) / 255.0
             v = int(hexvalue[12:14], 16) / 255.0
-        if bulb == "B":
+        elif bulb == "B":
             # hexvalue is in hsv
             h = int(hexvalue[0:4], 16) / 360.0
             s = int(hexvalue[4:8], 16) / 1000.0
             v = int(hexvalue[8:12], 16) / 1000.0
-
+        else:
+            # Unsupported bulb type
+            raise ValueError(f"Unsupported bulb type {bulb} - unable to determine HSV values.")
+
         return (h, s, v)
 
     def set_version(self, version): # pylint: disable=W0621