[cdheiser]

Closes #140.

The problem

There is no way to shut a connection down. _done does nothing on its own — the reader is parked in readline(), which returns only on data or a closed socket:

set _done = True on a live connection, wait 2s:
  thread_alive=True  loop_closed=False

So the thread and its telnet session outlive the caller, and the event loop built in __init__ is never closed either, leaking its selector fd alongside them.

Downstream this is the blocker for home-assistant/core#181995 (3). Home Assistant constructs a fresh Lutron per config entry setup and has no way to tear the old one down, so every reload of a live entry leaks a thread, a repeater session and a loop — and the orphaned client keeps invoking callbacks on entities that no longer exist. That one cannot be fixed on the HA side.

The change

Lutron.disconnect(timeout=5.0) and LutronConnection.disconnect(timeout=5.0). Idempotent, safe from any thread except the reader's own, and blocking until the thread exits or the timeout elapses.

Three pieces make it work:

• _main_loop runs inside _runner(), so shutdown has a task to cancel. Cancellation is the mechanism that does the work: it unblocks a pending readline() and cuts short the reconnect backoff alike. The writer is closed first so the socket goes away even if the task sits between awaits.
• run() closes the loop in a finally, after run_until_complete returns — it has to happen on the reader thread, which is the only one that may touch it.
• run() also wakes anyone blocked in connect() on the way out, rather than leaving them waiting on a thread that is gone.

disconnect() is terminal: a threading.Thread cannot be restarted, so callers wanting a new session construct a new Lutron. The docstrings say so.

HA's side then becomes:

async def async_unload_entry(hass, entry):
    unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
    if unload_ok:
        await hass.async_add_executor_job(entry.runtime_data.client.disconnect)
    return unload_ok

Tests

Four, driving the real thread rather than _main_loop directly, because the point is the cross-thread handshake. Each was verified by reverting the thing it covers:

revert	test that fails
drop _main_task.cancel()	test_disconnect_stops_thread_and_closes_loop, test_disconnect_is_idempotent
never self._loop.close()	test_disconnect_stops_thread_and_closes_loop
drop the is_alive() guard before join()	test_disconnect_without_connect (RuntimeError)
drop self._writer.close()	test_disconnect_stops_thread_and_closes_loop

Measured: disconnecting a live connection and disconnecting mid-backoff both complete in 0.00s, with no threads left behind.

79 tests pass, mypy clean.

Notes

An earlier draft had more machinery. I had an asyncio.Event and a wait_for to make the 5s backoff interruptible. Reverting that to a plain asyncio.sleep(5) changed no test result — cancelling the task already interrupts the sleep — so it came out. The backoff comment now says why the plain sleep is fine.

Related but deliberately not included: #141. connect() can block forever if the session drops between the connect and the waiter re-checking its predicate. It is a separate pre-existing bug with a one-line fix, and it changes what a successful connect() guarantees, so it deserves its own review rather than riding along here. Worth noting the two interact: with #141 unfixed, a consumer can still hang in connect() before it ever gets the chance to call disconnect().

Still open for HA: marking entities unavailable during an outage needs the connected property and connection-state callback from #140, which this PR does not add. Happy to follow up with those if the shape here looks right.