GeezerVison

Codecov Report

❌ Patch coverage is 94.81481% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.48%. Comparing base (a4fe376) to head (a479b51).
⚠️ Report is 5 commits behind head on master.

@@            Coverage Diff             @@
##           master    #1810      +/-   ##
==========================================
+ Coverage   93.43%   93.48%   +0.05%     
==========================================
  Files         159      161       +2     
  Lines       10116    10164      +48     
  Branches     1044     1041       -3     
==========================================
+ Hits         9452     9502      +50     
- Misses        471      473       +2     
+ Partials      193      189       -4     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

Nice work, this reads a lot better than the old tables. I ran it against master, tried a few plugins with real entry points, and packaged TPAP (#1592) as a plugin on top of it to see how a real transport fits. Notes below, most important first.

What I ran (a479b51 merged with master bd4826f, merges clean)

• Full suite passes on 3.11 to 3.15 (24458 passed on each).
• All 252 family × encryption × https × login_version combinations get the same protocol and transport as on master, and the 107 fixtures with a discovery result come out identical.
• A few device classes change, but only for combinations no device reaches (cameras and doorbells without https, Tapo hubs with KLAP over https), and each now matches its protocol. Maybe worth a line in the description.
• try_connect_all makes the same 8 attempts as master, now in a fixed order. Master's order depended on PYTHONHASHSEED, so that's an improvement.

Needs fixing

1. import kasa can blow up

Plugins load during import kasa (kasa/__init__.py:87), but two parts of load_plugins are outside the try. Either of these makes import kasa itself raise, which takes out the CLI and the HA integration:

• A malformed entry_points.txt in any installed package, plugin or not, since entry_points(group="kasa.plugins") (registry.py:204) parses all of them. A line without = gives TypeError: Pair.__new__() missing 1 required positional argument: 'value', and non-UTF-8 bytes give a UnicodeDecodeError. Neither names the package. Unlikely, but master imports fine with the same package installed.
• A plugin that passes a member name instead of its value, like register_transport("SMART", "Klap", ...) rather than "KLAP". That overwrites _member_map_["Klap"], so the real KLAP member drops out of iteration, and the override check (registry.py:217-221) raises KeyError from import kasa. Overriding with "KLAP" itself works fine: I swapped SMART KLAP and the camera transport for subclasses, and both were picked up, with the override warning.

Putting the entry point lookup, _choices() and the override check in the same try as the plugin call would fix the first. For the second, requiring encryption values to be uppercase would do it. The built-in names are CamelCase, and everything devices report is uppercase (KLAP, AES, and TPAP with #1592), so a value in any other case could never match discovery anyway.

2. Enum members added by plugins

register_transport adds DeviceEncryptionType members by hand (registry.py:146-152), and they don't behave like real members. With a plugin adding NEWENC:

("KLAP" in DeviceEncryptionType is True on 3.12+, so the False on 3.13+ only hits added members.)

• Rollback leaves the member behind. A plugin that registers FAILENC and then raises has its entries dropped, but FAILENC stays in the enum. It shows up in kasa --encrypt-type, and a stored config with it loads, then fails at connect with UnsupportedDeviceError. And since the enum is global, even a separate Registry() adds to it. The autouse _restore_encryption_types fixture in tests/test_registry.py hides both.
• No validation. A typo, a lowercase family or an old "SMART.TAPOPLUG.HTTPS" key is accepted and never matches. The uppercase check from point 1 covers encryption values. Checking the family against DeviceFamily (or IOT/SMART) would cover the rest.

3. try_connect_all and discovery

• Shared parameter objects. The device try_connect_all returns has the module-level _TRY_CONNECT_PARAMETERS entry as its config.connection_type. So changing it on the device (I set login_version to 99) changes what the next try_connect_all tries. Master built new ones on each call, and dataclasses.replace(conn_params) would fix it.
• A plugin transport that raises takes things down. REGISTRY.get_protocol(config) runs before the try (discover.py:688). With a plugin transport that raises RuntimeError for SMART AES, try_connect_all raised it after the IOT KLAP, KLAP v2 and XOR attempts and never tried the other five. In UDP discovery the same exception ends up in the event loop's exception handler and the device just disappears: discover() doesn't list it, and discover_single says "Timed out getting discovery response".
• A protocol with no device class crashes the CLI. Master skipped rows without a class. Now a plugin protocol that isn't a SmartProtocol subclass gives ConnectAttempt(device=None), and kasa discover config fails with 'NoneType' object has no attribute '__name__' (cli/discover.py:266).

4. Breaking changes, labelled enhancement

The changelog now groups by label (#1809), so with only enhancement these won't show up as breaking:

• @dataclass(kw_only=True) on DeviceConnectionParameters makes every positional call a TypeError, including through the deprecated kasa.ConnectionType alias.
• The get_protocol shim dropped strict, so get_protocol(config, strict=True) is a TypeError instead of a deprecation warning. No test calls the shim.
• get_device_class_from_family is gone without a shim, and so are the 14 names kasa.device_factory used to re-export (SmartDevice, SmartProtocol, the transports and so on).

HA's tplink integration uses none of these, so it's only other users. The breaking change label would cover it. Shims for strict and the removed names (a module __getattr__, like kasa/__init__.py has) would keep them working for a release, if you want that.

TPAP (#1592) as a plugin

I packaged #1592's transport as a kasa.plugins plugin on top of this to see how a real transport fits. The transport only needed a few small changes to live outside kasa (absolute imports, its own TpapParameters, and a raw-value check for -2203, which has no SmartErrorCode). setup() is five register_transport lines: SMART, cameras and doorbells (their any-encryption entries would win otherwise), hubs over https, and IOT over http.

The routing works well. All 28 family × https combinations with TPAP get the same protocol and transport as #1592 on master, and nothing built in gets replaced. Against a fake TPAP device answering from the KP125M fixture, these all work: discovery then update(), reconnecting from a stored config with the credentials hash (as HA does), kasa --host … state, and --encrypt-type TPAP.

What a plugin can't do, and #1592 does in kasa itself:

• Pick TPAP from the discovery reply. Like the Tapo app, TPAP Implementation #1592 uses TPAP when the UDP reply has a tpap object, whatever encrypt_type says. Cameras advertise AES next to it (the C101 fixture in the repo, a C510W fw 1.3.4 reply), so with the plugin they stay on SslAesTransport.
• Use the values in that object. TPAP Implementation #1592 keeps tls, port, pake, dac, user_hash_type and the MAC in the connection parameters, so the login uses them and they're stored with the config. A plugin can't add that field, so it has to ask the device again with the in-band discover, which cameras refuse.
• Add try_connect_all attempts. TPAP Implementation #1592 tries TPAP last and stops after a refused login, since every TPAP login with a wrong password counts toward the device's lockout. With the fixed _TRY_CONNECT_PARAMETERS, a TPAP-only device isn't found when discovery fails.
• Smaller: the -2203 error code, masking the session token in HttpClient's debug log, CLI options.

TPAP stays in #1592 either way. But I think the registry should carry everything a transport brings, not just the route. Right now a plugin can only answer "which transport for these parameters", and everything that builds the parameters is hard-coded. If a plugin can add a transport, it should also be able to add:

• its try_connect_all attempts, including where they go in the order and a way to stop after a refused login, which TPAP needs;
• the CLI bits that depend on the transport. The --type shortcuts hardcode AES for camera and KLAP for smart, and transport options like TPAP Implementation #1592's --tpap have nowhere to go.

Otherwise a plugin transport is only reached when discovery already names it, or through a hand-written config.

And just asking: would you want discovery in there too? Other new transports may need something from the discovery reply as well, like TPAP's tpap object. A way for a plugin to add to or change how the reply is read into parameters would help them.

Smaller points

Plugin loading

• Import order. Plugins load while kasa/__init__.py is still running. So if a plugin's own package gets imported before kasa (its tests, or from some_plugin import X), EntryPoint.load() gets a half-initialised module, logs "Unable to load plugin" and skips the plugin for the process. Putting import kasa first thing in the plugin package avoids it, which is worth documenting.
• Import cost. Every import kasa now reads every installed distribution's entry_points.txt: +3 ms with a dev venv's 71 distributions, and +49 ms with about 1,000 (median of 11 to 15 fresh interpreters).
• Every import logs. An intended override is a WARNING, and a failing plugin's traceback is printed, on every import kasa. With no logging set up, both land on stderr through the last-resort handler, so every CLI run shows them. INFO for overrides might be enough.
• Any-encryption entries swallow new types. SMART.IPCAMERA, SMART.TAPODOORBELL and IOT.IPCAMERA match any encryption type and are more specific than a plugin's ("SMART", "NEWENC"). So a doorbell reporting NEWENC still gets SslAesTransport, with no warning. A new type has to register those families itself (TPAP does), which is also worth documenting.
• Smaller:
  • KASA_DISABLE_PLUGINS=0 (or false) also disables plugins.
  • load_plugins() isn't idempotent.
  • The load order follows the installed distributions, and the log names the entry point but not the distribution.

Small things

• REGISTRY is imported into kasa but isn't in __all__.
• Docs. Nothing in docs/ covers kasa.plugins, the setup(registry) contract, precedence, when plugins load or KASA_DISABLE_PLUGINS, and kasa.registry isn't in the API reference. From the TPAP plugin, two more things are worth a line:
  • HA only turns on debug logging for the kasa logger, so a plugin logging under its own package name is missing from HA debug logs;
  • which private names a transport can rely on (_RetryableError, _ConnectionError, _DeviceConfigBaseMixin, Credentials._from_plaintext_hash).
• The plugin tests patch entry_points with SimpleNamespace objects, so nothing loads a real entry point or runs the import-time call.

Not from this PR: IOT devices from 20002 discovery get their family's class

Not new here, but the new comment in get_device_class ("IOT device classes are decided by the sysinfo, discovery only has the family") reads as if it's handled, and it isn't for every caller.

• A fresh dump of an HS300(US) hw 2.0 fw 1.1.2 (KLAP, lv 2) comes out of Discover._get_device_instance as IotPlug over KlapTransportV2. Device.connect then picks IotStrip from sysinfo (Classify IOT devices via sysinfo regardless of transport (fixes #1740) #1769), so anything that connects with the discovered config is fine, like HA's integration discovery.
• Anything that calls update() on the discovered object fails with KeyError: 'relay_state'. That covers kasa --host <ip> state and discover, and, from reading HA's config flow, _async_try_discover_and_update, which its DHCP, manual add, reauth and reconfigure steps use. A KeyError isn't a KasaException, so those steps don't catch it. Same symptom as KLAP v2 Authentication Failure on TP-Link HS300 (US) — Hardware Version 2.0 #1604.
• With the fixture added, four existing tests fail here exactly as on master: test_device_factory.py::test_connect, test_discovery.py::test_discover_try_connect_all, and test_cli.py::test_discover and test_discover_host. IOT light strips announced as IOT.SMARTBULB come out as IotBulb instead of IotLightStrip the same way.

I'd like to fix this in a follow-up once this lands: classify from sysinfo when the login works, otherwise return an IOT device of unknown type whose update() raises AuthenticationError, so HA keeps working. Nothing needed here, though maybe reword the comment for now.