refactor(router): relocate Router module from tesla/vehicle to tesla/router.py

AGENTS.md

@@ -59,9 +59,9 @@ Commands (vehicle/commands.py) - protobuf-based signed command implementation (A
 
 `VehicleSigned` uses multiple inheritance: `Commands` for signed command logic, `VehicleFleet` for data endpoints and fallback.
 
-`Router` (vehicle/router.py) is an entity-agnostic composition wrapper (not part of the inheritance chain) that chains an ordered list of two-or-more backends sharing a common method surface and dispatches each method call down the chain with automatic per-command failover: it tries the first backend that has the method and, on any exception, retries the same call on the next backend that has it, returning the first success (raising the last error only if every applicable backend fails, `AttributeError` only if none has the method). Non-callable attributes resolve to the first backend that has them. The constructor is `Router(primary, fallback, *more_backends, health=None)` — the two-argument form is fully backward compatible. The health check (`bool` | sync callable | async callable returning `bool`; omitted = attempt primary, fail over on exception with no probe) gates **only the primary** (the first backend); the rest of the chain is reached purely through per-command failover — there is deliberately no per-backend health matrix. Note the double-execution caveat: a non-idempotent command that fails mid-flight can be re-run on the next backend.
+`Router` (router.py) is an entity-agnostic composition wrapper (not part of the inheritance chain) that chains an ordered list of two-or-more backends sharing a common method surface and dispatches each method call down the chain with automatic per-command failover: it tries the first backend that has the method and, on any exception, retries the same call on the next backend that has it, returning the first success (raising the last error only if every applicable backend fails, `AttributeError` only if none has the method). Non-callable attributes resolve to the first backend that has them. The constructor is `Router(primary, fallback, *more_backends, health=None)` — the two-argument form is fully backward compatible. The health check (`bool` | sync callable | async callable returning `bool`; omitted = attempt primary, fail over on exception with no probe) gates **only the primary** (the first backend); the rest of the chain is reached purely through per-command failover — there is deliberately no per-backend health matrix. Note the double-execution caveat: a non-idempotent command that fails mid-flight can be re-run on the next backend.
 
-`VehicleRouter` and `EnergySiteRouter` are thin entity-specific subclasses of `Router`. `VehicleRouter(bluetooth_primary, teslemetry_fallback)` pairs a `VehicleBluetooth` primary with a cloud (`TeslemetryVehicle`) fallback; `EnergySiteRouter(local_energysite, teslemetry_energysite)` pairs a duck-typed local `EnergySite`-shaped object (e.g. aiopowerwall's `PowerwallEnergySite`, no dependency added) with a cloud `TeslemetryEnergySite` fallback. All three are exported from `tesla/vehicle/__init__.py` (and re-exported from `tesla/__init__.py`) but have no factory on the `Vehicles`/`EnergySites` collections.
+`VehicleRouter` and `EnergySiteRouter` are thin entity-specific subclasses of `Router`. `VehicleRouter(bluetooth_primary, teslemetry_fallback)` pairs a `VehicleBluetooth` primary with a cloud (`TeslemetryVehicle`) fallback; `EnergySiteRouter(local_energysite, teslemetry_energysite)` pairs a duck-typed local `EnergySite`-shaped object (e.g. aiopowerwall's `PowerwallEnergySite`, no dependency added) with a cloud `TeslemetryEnergySite` fallback. All three live in `tesla/router.py` and are re-exported from `tesla/__init__.py` (importable as `tesla_fleet_api.tesla.Router` etc.) but have no factory on the `Vehicles`/`EnergySites` collections.
 
 ### Vehicle Collections
 

README.md

@@ -174,7 +174,7 @@ The `Router` class composes an ordered list of two-or-more backends that share a
 import asyncio
 import aiohttp
 from tesla_fleet_api import TeslaBluetooth, Teslemetry
-from tesla_fleet_api.tesla.vehicle.router import VehicleRouter
+from tesla_fleet_api.tesla.router import VehicleRouter
 from tesla_fleet_api.exceptions import TeslaFleetError
 
 async def main():
@@ -205,13 +205,13 @@ By default the router attempts the primary and fails over on any error, with no
 `EnergySiteRouter` follows the same pattern for energy sites, pairing a duck-typed local `EnergySite`-shaped object (e.g. aiopowerwall's `PowerwallEnergySite`, no dependency added) with a cloud `TeslemetryEnergySite` fallback:
 
 ```python
-from tesla_fleet_api.tesla.vehicle.router import EnergySiteRouter
+from tesla_fleet_api.tesla.router import EnergySiteRouter
 
 router = EnergySiteRouter(local_energysite, teslemetry_energysite)
 await router.set_operation(...)  # local first, cloud on failure
 ```
 
-`Router`, `VehicleRouter`, and `EnergySiteRouter` are all importable from `tesla_fleet_api.tesla.vehicle.router` (and from `tesla_fleet_api.tesla`).
+`Router`, `VehicleRouter`, and `EnergySiteRouter` are all importable from `tesla_fleet_api.tesla.router` (and from `tesla_fleet_api.tesla`).
 
 > **Warning:** Because a failed call is replayed on the next backend, a non-idempotent command (e.g. `honk_horn`, `actuate_trunk`, `door_unlock`, `charge_start`) that fails _mid-flight_ — after a backend may have already partially applied it — can be **double-executed** (or executed more than once across a longer chain) when it is retried on the next backend. This is a deliberate tradeoff of per-command failover. Callers needing exactly-once semantics for such commands should gate dispatch with an explicit `health` check or call the underlying backends directly.
 >

tesla_fleet_api.egg-info/PKG-INFO

@@ -30,7 +30,7 @@ Tesla Fleet API is a Python library that provides an interface to interact with
 - Fleet API for energy sites
 - Fleet API with signed vehicle commands
 - Bluetooth for vehicles
-- Routing and failover between vehicle transports (e.g. Bluetooth primary, cloud fallback)
+- Routing and failover across backends for vehicles and energy sites (e.g. Bluetooth/local primary, cloud fallback)
 - Teslemetry integration
 - Tessie integration
 
@@ -190,13 +190,13 @@ For more detailed examples, see [Bluetooth for Vehicles](docs/bluetooth_vehicles
 
 ### Routing and Failover
 
-The `VehicleRouter` class composes a primary and a fallback vehicle instance and dispatches each method call to the primary when it is healthy, automatically failing over to the fallback on error. A common setup is a local `VehicleBluetooth` primary with a cloud fallback (e.g. a `TeslemetryVehicle`), so commands go over Bluetooth when the vehicle is reachable and route to the cloud otherwise:
+The `Router` class composes an ordered list of two-or-more backends that share a common method surface and dispatches each method call down the chain, automatically failing over on error. `VehicleRouter` and `EnergySiteRouter` are thin entity-specific subclasses. A common setup is a local `VehicleBluetooth` primary with a cloud fallback (e.g. a `TeslemetryVehicle`), so commands go over Bluetooth when the vehicle is reachable and route to the cloud otherwise:
 
 ```python
 import asyncio
 import aiohttp
 from tesla_fleet_api import TeslaBluetooth, Teslemetry
-from tesla_fleet_api.tesla.vehicle.router import VehicleRouter
+from tesla_fleet_api.tesla.router import VehicleRouter
 from tesla_fleet_api.exceptions import TeslaFleetError
 
 async def main():
@@ -220,11 +220,24 @@ async def main():
 asyncio.run(main())
 ```
 
-By default the router attempts the primary and fails over to the fallback on any error, with no up-front probe. You can also pass an explicit `health` check — a `bool`, a sync callable, or an async callable returning `bool` — to decide up front whether to route to the primary or straight to the fallback.
+The constructor is `Router(primary, fallback, *more_backends, health=None)`; the two-argument form shown above is fully backward compatible, and any number of extra backends may follow to extend the chain. Each call is tried on the first backend that has the method and, on any exception, retried on the next backend that has it, returning the first success (raising the last error only if every applicable backend fails). Non-callable attributes (e.g. `vin`) resolve to the first backend that has them.
 
-> **Warning:** Because a failed primary call is replayed on the fallback, a non-idempotent command (e.g. `honk_horn`, `actuate_trunk`, `door_unlock`, `charge_start`) that fails _mid-flight_ — after the primary may have already partially applied it — can be **double-executed** when it is retried on the fallback. This is a deliberate tradeoff of per-command failover. Callers needing exactly-once semantics for such commands should gate dispatch with an explicit `health` check or call the underlying `primary`/`fallback` instances directly.
+By default the router attempts the primary and fails over on any error, with no up-front probe. You can also pass an explicit `health` check — a `bool`, a sync callable, or an async callable returning `bool` — to decide up front whether to route to the primary or skip straight to the rest of the chain. The health check gates **only the primary** (the first backend); later backends are reached purely through per-command failover.
+
+`EnergySiteRouter` follows the same pattern for energy sites, pairing a duck-typed local `EnergySite`-shaped object (e.g. aiopowerwall's `PowerwallEnergySite`, no dependency added) with a cloud `TeslemetryEnergySite` fallback:
+
+```python
+from tesla_fleet_api.tesla.router import EnergySiteRouter
+
+router = EnergySiteRouter(local_energysite, teslemetry_energysite)
+await router.set_operation(...)  # local first, cloud on failure
+```
+
+`Router`, `VehicleRouter`, and `EnergySiteRouter` are all importable from `tesla_fleet_api.tesla.router` (and from `tesla_fleet_api.tesla`).
+
+> **Warning:** Because a failed call is replayed on the next backend, a non-idempotent command (e.g. `honk_horn`, `actuate_trunk`, `door_unlock`, `charge_start`) that fails _mid-flight_ — after a backend may have already partially applied it — can be **double-executed** (or executed more than once across a longer chain) when it is retried on the next backend. This is a deliberate tradeoff of per-command failover. Callers needing exactly-once semantics for such commands should gate dispatch with an explicit `health` check or call the underlying backends directly.
 >
-> Dispatch is implemented via `__getattr__`, which does not proxy dunder methods, so `async with VehicleRouter(...)` does **not** manage the primary's BLE connection lifecycle (`__aenter__`/`__aexit__`). Commands still auto-connect on send; for explicit connect/disconnect reach through `vehicle.primary`.
+> Dispatch is implemented via `__getattr__`, which does not proxy dunder methods, so `async with Router(...)` does **not** manage a backend's BLE connection lifecycle (`__aenter__`/`__aexit__`). Commands still auto-connect on send; for explicit connect/disconnect reach through `router.primary` (or `router.backends`).
 
 ### Teslemetry
 

tesla_fleet_api.egg-info/SOURCES.txt

@@ -17,13 +17,13 @@ tesla_fleet_api/tesla/energysite.py
 tesla_fleet_api/tesla/fleet.py
 tesla_fleet_api/tesla/oauth.py
 tesla_fleet_api/tesla/partner.py
+tesla_fleet_api/tesla/router.py
 tesla_fleet_api/tesla/tesla.py
 tesla_fleet_api/tesla/user.py
 tesla_fleet_api/tesla/vehicle/__init__.py
 tesla_fleet_api/tesla/vehicle/bluetooth.py
 tesla_fleet_api/tesla/vehicle/commands.py
 tesla_fleet_api/tesla/vehicle/fleet.py
-tesla_fleet_api/tesla/vehicle/router.py
 tesla_fleet_api/tesla/vehicle/signed.py
 tesla_fleet_api/tesla/vehicle/vehicle.py
 tesla_fleet_api/tesla/vehicle/vehicles.py
@@ -55,5 +55,5 @@ tesla_fleet_api/tessie/__init__.py
 tesla_fleet_api/tessie/tessie.py
 tesla_fleet_api/tessie/vehicles.py
 tests/test_fleet_auth_refresh.py
-tests/test_tessie_vehicle_params.py
-tests/test_vehicle_router.py
+tests/test_router.py
+tests/test_tessie_vehicle_params.py

tesla_fleet_api/tesla/__init__.py

@@ -6,6 +6,7 @@
 from tesla_fleet_api.tesla.charging import Charging
 from tesla_fleet_api.tesla.energysite import EnergySites, EnergySite
 from tesla_fleet_api.tesla.partner import Partner
+from tesla_fleet_api.tesla.router import Router, VehicleRouter, EnergySiteRouter
 from tesla_fleet_api.tesla.user import User
 from tesla_fleet_api.tesla.vehicle import (
     Vehicles,
@@ -14,9 +15,6 @@
     VehicleSigned,
     VehicleBluetooth,
     Vehicle,
-    Router,
-    VehicleRouter,
-    EnergySiteRouter,
 )
 
 __all__ = [

tesla_fleet_api/tesla/vehicle/__init__.py

@@ -4,7 +4,6 @@
 from tesla_fleet_api.tesla.vehicle.fleet import VehicleFleet
 from tesla_fleet_api.tesla.vehicle.bluetooth import VehicleBluetooth
 from tesla_fleet_api.tesla.vehicle.signed import VehicleSigned
-from tesla_fleet_api.tesla.vehicle.router import Router, VehicleRouter, EnergySiteRouter
 from tesla_fleet_api.tesla.vehicle.vehicle import Vehicle
 
 __all__ = [
@@ -14,7 +13,4 @@
     "VehicleFleet",
     "VehicleBluetooth",
     "VehicleSigned",
-    "Router",
-    "VehicleRouter",
-    "EnergySiteRouter",
 ]

tests/test_vehicle_router.py → tests/test_router.py

@@ -1,14 +1,15 @@
-"""Unit tests for VehicleRouter per-command failover and fall-through.
+"""Unit tests for the Router family (Router, VehicleRouter, EnergySiteRouter).
 
-These use plain fakes for the two composed vehicle instances so no real BLE
-hardware or network access is required.
+Covers per-command failover and fall-through for vehicle routing, N-way (>2)
+backend chains, and energy-site routing. These use plain fakes for the composed
+backend instances so no real BLE hardware or network access is required.
 """
 
 import asyncio
 from unittest import IsolatedAsyncioTestCase
 
 from tesla_fleet_api.exceptions import BluetoothTimeout
-from tesla_fleet_api.tesla.vehicle.router import (
+from tesla_fleet_api.tesla.router import (
     EnergySiteRouter,
     Router,
     VehicleRouter,