v2.0.0 with Async Architecture

ASYNC.md

@@ -0,0 +1,141 @@
+# TinyTuya Async Roadmap (v2.x)
+
+## Vision
+Provide a first-class asyncio-native API for local Tuya LAN control that:
+* Preserves rock-solid backward compatibility with the existing synchronous API (1.x style) for the large installed base.
+* Enables high-concurrency, low-latency operations (parallel status polling, batched control, streaming updates) across mixed protocol versions (3.1–3.5) without blocking threads.
+* Establishes a sustainable architecture so future protocol changes (e.g. 3.6+, new discovery flows) can be integrated once at the async layer and selectively backported.
+
+## Goals
+1. Async Core: Non-blocking socket connect, handshake, encrypt/decrypt, send/receive framed messages for all protocol versions.
+2. High Throughput: Support dozens/hundreds of devices concurrently with graceful backpressure and timeout handling.
+3. Pluggable Crypto & Parsing: Reuse existing message framing logic but allow async pipeline (reader / writer tasks) with cancellation.
+4. Structured API: Mirror familiar synchronous class names with `Async` suffix (e.g. `XenonDeviceAsync`, `OutletDeviceAsync`).
+5. Observability: Built-in debug / trace hooks and metrics counters (messages sent, retries, handshake duration) pluggable via callbacks.
+6. Incremental Adoption: No forced migration—sync and async coexist; shared utility modules (e.g. encoding, DPS merge) remain single-source.
+
+## Out of Scope
+* Replacing synchronous classes or removing sync code paths.
+* Full async Cloud API (could follow later).
+
+## Architectural Overview (Planned)
+```
++------------------------------+            +---------------------------+
+| XenonDeviceAsync (base)      |            | MessageHelper (shared)    |
+|  - state machine             |<--calls--> |  pack/unpack (sync funcs) |
+|  - connection supervisor     |            |  crypto helpers           |
+|  - protocol v3.1..v3.5       |            +---------------------------+
+|  - send queue (asyncio.Queue)|
+|  - recv task (reader loop)   |            +---------------------------+
+|  - handshake coroutine       |<--uses---->| Crypto (AESCipher)        |
++--------------+---------------+            +---------------------------+
+               | derives
+    +----------+-----------+
+    | Async Device Mixins  |
+    | (Outlet/Bulb/etc.)   |
+    +----------------------+
+```
+
+## Milestones
+| Milestone | Description | Deliverables | Target Version |
+|-----------|-------------|--------------|----------------|
+| M0 | Planning & Version Bump | v2.0.0, `ASYNC.md`, release notes | 2.0.0 |
+| M1 | Async Core Skeleton | `xasync/connection.py`, `XenonDeviceAsync` minimal connect + status (3.1/3.3) | 2.1.0 |
+| M2 | Protocol Coverage | Support 3.4/3.5 handshake & GCM in async path | 2.2.0 |
+| M3 | Device Classes | `OutletDeviceAsync`, `BulbDeviceAsync`, `CoverDeviceAsync` parity subset | 2.3.0 |
+| M4 | High-Perf Scanner | Async scanner refactor (parallel probes, cancellation) | 2.4.0 |
+| M5 | Test & Metrics | 85%+ coverage for async modules; metrics hooks | 2.5.0 |
+| M6 | Examples & Docs | Async examples, README + PROTOCOL cross-links | 2.6.0 |
+| M7 | Optimization | Connection pooling, adaptive retry, rate limiting | 2.7.0 |
+
+## Detailed Task Breakdown
+### M1 – Async Core Skeleton
+- [ ] Create package folder `tinytuya/asyncio/` (or `tinytuya/async_`) to avoid name collision.
+- [ ] Implement `XenonDeviceAsync` with:
+  * `__init__(..., loop=None)` store config
+  * `_ensure_connection()` coroutine: open TCP, negotiate session key if needed
+  * `_reader_task()` coroutine: read frames, push to internal queue
+  * `_send_frame()` coroutine: pack + write
+  * `status()` -> `await get_status()` that sends DP_QUERY / CONTROL_NEW per version
+  * Graceful close / cancellation
+- [ ] Reuse existing `pack_message` / `unpack_message` in a thread-safe way (they are CPU-bound but fast; optionally offload heavy crypto to default loop executor only if needed later).
+
+### M2 – Protocol v3.4 / v3.5 Handshake
+- [ ] Async handshake coroutine with timeout + auto-retry
+- [ ] Session key caching per open connection
+- [ ] Automatic renegotiation on GCM tag failure
+
+### M3 – Device Class Parity
+- [ ] Async mixins or subclasses replicating key sync API (`set_value`, `set_multiple_values`, `turn_on/off`)
+- [ ] If return values differ (e.g. coroutines), document mapping in README
+- [ ] Shared DPS merge logic factored into pure functions usable by both sync/async
+
+### M4 – Async Scanner
+- [ ] Coroutine to probe IP ranges concurrently (configurable concurrency)
+- [ ] Cancel outstanding probes on shutdown
+- [ ] Integrate UDP discovery (v3.1–v3.5) with async sockets
+- [ ] Provide `await scan_network(subnet, timeout)` returning structured device list
+
+### M5 – Tests & QA
+- [ ] Pytest-asyncio test suite for: framing, handshake, reconnection, DPS updates
+- [ ] Fake device server (async) to simulate v3.1, 3.3, 3.4, 3.5 behaviors
+- [ ] Performance smoke test (N devices concurrently) gating PR merges
+
+### M6 – Documentation & Examples
+- [ ] `examples/async/` directory with: basic status, bulk control, scanner usage, bulb effects
+- [ ] README section: “Using the Async API” with migration notes
+- [ ] Cross-link PROTOCOL.md for handshake & framing details
+
+### M7 – Optimization & Enhancements
+- [ ] Connection pooling for multiple logical child devices (gateways) sharing transport
+- [ ] Adaptive retry and exponential backoff for transient network errors
+- [ ] Optional structured logging adapter (JSON events)
+- [ ] Metrics hook interface (`on_event(event_name, **data)`) for integrations
+
+## Testing Strategy
+| Layer | Strategy |
+|-------|----------|
+| Unit | Pure functions (framing, header parse) deterministic tests |
+| Integration | Async fake device endpoints per protocol version |
+| Performance | Timed concurrent status for N synthetic devices (assert throughput baseline) |
+| Regression | Mirror critical sync tests with async equivalents |
+| Fuzz (future) | Random DP payload mutation on fake server to harden parsing |
+
+## API Sketch (Draft)
+```python
+import asyncio
+import tinytuya
+from tinytuya.asyncio import XenonDeviceAsync
+
+async def main():
+    dev = XenonDeviceAsync(dev_id, address=ip, local_key=key, version=3.5, persist=True)
+    status = await dev.status()  # coroutine
+    print(status)
+    await dev.set_value(1, True)
+    await dev.close()
+
+asyncio.run(main())
+```
+Methods returning coroutines (awaitables): `status`, `set_value`, `set_multiple_values`, `heartbeat`, `updatedps`, `close`.
+
+## Backward Compatibility Plan
+* Sync code paths untouched; existing imports remain default.
+* Async lives under `tinytuya.asyncio` (explicit opt-in) to avoid polluting top-level namespace initially.
+* When async reaches parity, consider promoting selected classes to top-level import in a minor release (opt-in alias only).
+
+## Open Questions / To Refine
+- Should we introduce an event callback API for spontaneous DP updates vs polling? (Likely yes in M3/M4.)
+- Provide context manager (`async with XenonDeviceAsync(...)`) for auto-connect/close? (Planned.)
+- Rate limiting: global vs per-device? (Investigate after baseline performance metrics.)
+
+## Contribution Guidelines (Async Track)
+* Prefer small, reviewable PRs per milestone task.
+* Include tests & docs for every new public coroutine.
+* Avoid breaking sync APIs—additive only.
+* Mark experimental APIs with a leading `_` or mention in docstring.
+
+## Next Step
+Implement Milestone M1 skeleton: create async package, base class, minimal status() for 3.1 & 3.3 devices.
+
+---
+Maintained with the goal of long-term stability for existing users while enabling modern async performance.

RELEASE.md

@@ -1,5 +1,27 @@
 # RELEASE NOTES
 
+## v2.0.0 - Async Architecture Introduction (BREAKING MAJOR VERSION)
+
+This major release introduces the foundation for native asyncio-based device communication while fully preserving the existing synchronous API for backward compatibility.
+
+Highlights:
+* Version bump to 2.x to signal new async subsystem (legacy sync classes unchanged).
+* Planning document `ASYNC.md` added (vision, goals, milestones for XenonDeviceAsync & related classes).
+* No behavioral changes to existing synchronous code paths in this initial 2.0.0 tag.
+* Future minor releases (2.1.x+) will add new async classes and examples without removing sync support.
+
+Compatibility:
+* Existing imports and synchronous usage continue to work (API surface of 1.x retained).
+* New async classes will live alongside current modules (no name collisions) and require explicit opt‑in.
+* Officially removed Python 2.7 support.
+
+Migration Guidance:
+* You can adopt async incrementally—no action required if you stay with sync API.
+* When async classes land, prefer `await device.status_async()` patterns in event loops for concurrency gains.
+
+See `ASYNC.md` for roadmap details.
+
+
 ## 1.17.4 - Cloud Config
 
 - Cloud: Add `configFile` option to the Cloud constructor, allowing users to specify the config file location (default remains 'tinytuya.json') by @blackw1ng in https://github.com/jasonacox/tinytuya/pull/640

server/server.py

@@ -34,7 +34,6 @@
 """
 
 # Modules
-from __future__ import print_function
 import threading
 import time
 import logging

tinytuya/core/XenonDevice.py

@@ -9,7 +9,6 @@
 import socket
 import struct
 import time
-import sys
 
 from .const import DEVICEFILE, TCPPORT
 from .crypto_helper import AESCipher
@@ -20,8 +19,6 @@
 
 log = logging.getLogger(__name__)
 
-# Python 2 Support
-IS_PY2 = sys.version_info[0] == 2
 
 def find_device(dev_id=None, address=None):
     """Scans network for Tuya devices with either ID = dev_id or IP = address
@@ -904,11 +901,8 @@ def _negotiate_session_key_generate_step_3( self, rkey ):
         return MessagePayload(CT.SESS_KEY_NEG_FINISH, rkey_hmac)
 
     def _negotiate_session_key_generate_finalize( self ):
-        if IS_PY2:
-            k = [ chr(ord(a)^ord(b)) for (a,b) in zip(self.local_nonce,self.remote_nonce) ]
-            self.local_key = ''.join(k)
-        else:
-            self.local_key = bytes( [ a^b for (a,b) in zip(self.local_nonce,self.remote_nonce) ] )
+        # Python 3: nonce XOR produces bytes object directly
+        self.local_key = bytes(a ^ b for (a, b) in zip(self.local_nonce, self.remote_nonce))
         log.debug("Session nonce XOR'd: %r", self.local_key)
 
         cipher = AESCipher(self.real_local_key)

tinytuya/core/core.py

@@ -1,7 +1,8 @@
 # TinyTuya Module
 # -*- coding: utf-8 -*-
 """
- Python module to interface with Tuya WiFi smart devices
+ Python module to interface with Tuya WiFi smart devices.
+ (Python 3 only as of v2.0.0 – legacy Python 2 support removed.)
 
  Author: Jason A. Cox
  For more information see https://github.com/jasonacox/tinytuya
@@ -76,7 +77,6 @@
 """
 
 # Modules
-from __future__ import print_function  # python 2.7 support
 import logging
 import sys
 
@@ -90,45 +90,24 @@
 
 from .crypto_helper import AESCipher
 
-# Backward compatibility for python2
-try:
-    input = raw_input
-except NameError:
-    pass
-
 
 # Colorama terminal color capability for all platforms
 if HAVE_COLORAMA:
     init()
 
-version_tuple = (1, 17, 4)  # Major, Minor, Patch
+version_tuple = (2, 0, 0)  # Major, Minor, Patch
 version = __version__ = "%d.%d.%d" % version_tuple
 __author__ = "jasonacox"
 
 log = logging.getLogger(__name__)
 
 
-# Python 2 Support
-IS_PY2 = sys.version_info[0] == 2
-
-
-# Misc Helpers
 def bin2hex(x, pretty=False):
-    if pretty:
-        space = " "
-    else:
-        space = ""
-    if IS_PY2:
-        result = "".join("%02X%s" % (ord(y), space) for y in x)
-    else:
-        result = "".join("%02X%s" % (y, space) for y in x)
-    return result
+    space = " " if pretty else ""
+    return "".join("%02X%s" % (b, space) for b in x)
 
 def hex2bin(x):
-    if IS_PY2:
-        return x.decode("hex")
-    else:
-        return bytes.fromhex(x)
+    return bytes.fromhex(x)
 
 def set_debug(toggle=True, color=True):
     """Enable tinytuya verbose logging"""

tinytuya/core/crypto_helper.py

@@ -1,7 +1,6 @@
 # TinyTuya Module
 # -*- coding: utf-8 -*-
 
-from __future__ import print_function  # python 2.7 support
 import base64
 import logging
 import time

tinytuya/scanner.py

@@ -13,7 +13,6 @@
 
 """
 # Modules
-from __future__ import print_function
 from collections import namedtuple
 import ipaddress
 import json
@@ -42,11 +41,6 @@
 #except:
 #    SCANLIBS = False
 
-# Backward compatibility for python2
-try:
-    input = raw_input
-except NameError:
-    pass
 
 try:
     import netifaces # pylint: disable=E0401
@@ -379,8 +373,8 @@ def get_peer(self):
                 r = self.sock.recv( 5000 )
                 if self.debug:
                     print('Debug sock', self.ip, 'closed but received data?? Received:', r)
-            # ugh, ConnectionResetError and ConnectionRefusedError are not available on python 2.7
-            #except ConnectionResetError:
+            # Connection retry logic
+            #except ConnectionResetError:  # Python 3 specific
             except OSError as e:
                 if self.initial_connect_retries and e.errno == errno.ECONNRESET:
                     # connected, but then closed
@@ -1060,8 +1054,6 @@ def scan(scantime=None, color=True, forcescan=False, discover=True, assume_yes=F
 
 def _generate_ip(networks, verbose, term):
     for netblock in networks:
-        if tinytuya.IS_PY2 and type(netblock) == str:
-            netblock = netblock.decode('latin1')
         try:
             network = ipaddress.ip_network(netblock, strict=False)
             log.debug("Starting brute force network scan %s", network)

tinytuya/wizard.py

@@ -22,7 +22,6 @@
     The TuyAPI/CLI wizard inspired and informed this python version.
 """
 # Modules
-from __future__ import print_function
 import json
 from datetime import datetime
 import tinytuya
@@ -36,11 +35,6 @@
 
 HAVE_COLOR = HAVE_COLORAMA or not sys.platform.startswith('win')
 
-# Backward compatibility for python2
-try:
-    input = raw_input
-except NameError:
-    pass
 
 # Colorama terminal color capability for all platforms
 if HAVE_COLORAMA:

tools/ttcorefunc.py

@@ -2,7 +2,6 @@
 # -*- coding: utf-8 -*-
 
 # Modules
-from __future__ import print_function  # python 2.7 support
 import binascii
 from collections import namedtuple
 import base64
@@ -96,8 +95,6 @@
 
 NO_PROTOCOL_HEADER_CMDS = [DP_QUERY, DP_QUERY_NEW, UPDATEDPS, HEART_BEAT, SESS_KEY_NEG_START, SESS_KEY_NEG_RESP, SESS_KEY_NEG_FINISH, LAN_EXT_STREAM ]
 
-# Python 2 Support
-IS_PY2 = sys.version_info[0] == 2
 
 # Tuya Packet Format
 TuyaHeader = namedtuple('TuyaHeader', 'prefix seqno cmd length total_length')
@@ -241,21 +238,11 @@ def _unpad(s, verify_padding=False):
 
 # Misc Helpers
 def bin2hex(x, pretty=False):
-    if pretty:
-        space = " "
-    else:
-        space = ""
-    if IS_PY2:
-        result = "".join("%02X%s" % (ord(y), space) for y in x)
-    else:
-        result = "".join("%02X%s" % (y, space) for y in x)
-    return result
+    space = " " if pretty else ""
+    return "".join("%02X%s" % (y, space) for y in x)
 
 def hex2bin(x):
-    if IS_PY2:
-        return x.decode("hex")
-    else:
-        return bytes.fromhex(x)
+    return bytes.fromhex(x)
 
 def set_debug(toggle=True, color=True):
     """Enable tinytuya verbose logging"""