feat(ble-extra): make Bluetooth support an optional extra (tesla-fleet-api[ble])

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
         with:
           enable-cache: true
       - name: Install dependencies
-        run: uv sync --locked
+        run: uv sync --locked --extra ble
       - name: Ruff
         run: uv run ruff check tesla_fleet_api tests
       - name: Pyright
@@ -38,7 +38,7 @@ jobs:
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
       - name: Install dependencies
-        run: uv sync --locked --python ${{ matrix.python-version }}
+        run: uv sync --locked --extra ble --python ${{ matrix.python-version }}
       - name: Pytest
         run: uv run pytest tests -q
 

AGENTS.md

@@ -6,7 +6,7 @@ Teslemetry, Tessie and vehicle BLE. Published to PyPI as `tesla-fleet-api`.
 ## Development Commands
 
 ```bash
-uv sync                                 # install
+uv sync --extra ble                     # install (add --extra ble for Bluetooth work/tests)
 uv run pyright tesla_fleet_api          # type check (strict)
 uv run ruff check tesla_fleet_api       # lint
 uv run ruff format tesla_fleet_api
@@ -43,6 +43,11 @@ top-level workflow, never `workflow_call` — the trusted publisher is bound to
 - **Home Assistant pin**: protobuf refuses gencode newer than the runtime. Before
   bumping `tesla-protocol`, check HA core's `protobuf` pin
   (`homeassistant/package_constraints.txt`) and keep our `protobuf` floor in sync.
+- `bleak`/`bleak-retry-connector` are the optional `ble` extra; `cryptography`,
+  `protobuf` and `tesla-protocol` stay base (the cloud signed path needs them).
+  The bleak-backed classes resolve lazily (`Vehicles.Bluetooth` property, module
+  `__getattr__`), never by top-level import.
+  `tests/test_ble_optional_extra.py` enforces it.
 - Do not add dependencies on aiopowerwall or `teslemetry-stream`.
   `EnergySiteRouter` and `BleBroadcastStreamGlue` use local structural
   `Protocol`s instead.

README.md

@@ -20,6 +20,19 @@ You can install the library using pip:
 pip install tesla-fleet-api
 ```
 
+Bluetooth support (`TeslaBluetooth`, `VehicleBluetooth`, `createBluetooth()`) pulls in
+`bleak` and `bleak-retry-connector`, so it ships as the optional `ble` extra rather than
+a base dependency — cloud-only consumers (Fleet API, Teslemetry, Tessie) don't need to
+carry it. If you use Bluetooth, install with:
+
+```bash
+pip install tesla-fleet-api[ble]
+```
+
+Existing installs that already depend on `bleak`/`bleak-retry-connector` directly, or
+that pin `tesla-fleet-api` without extras, keep working: add the `[ble]` extra (or keep
+your own `bleak` pin) to continue resolving those packages going forward.
+
 ## Usage
 
 ### Authentication

docs/bluetooth_vehicles.md

@@ -2,6 +2,8 @@
 
 This document provides detailed examples for using Bluetooth for vehicles.
 
+Bluetooth support requires the `ble` extra: `pip install tesla-fleet-api[ble]`.
+
 ## Initialize TeslaBluetooth
 
 The `TeslaBluetooth` class provides methods to interact with Tesla vehicles using Bluetooth. Here's a basic example to initialize the `TeslaBluetooth` class and discover nearby Tesla vehicles:

pyproject.toml

@@ -23,10 +23,11 @@ dependencies = [
     "cryptography>=43",
     "protobuf>=6.33.5",
     "tesla-protocol>=3.0.0",
-    "bleak>=0.22",
-    "bleak-retry-connector>=3.9",
 ]
 
+[project.optional-dependencies]
+ble = ["bleak>=0.22", "bleak-retry-connector>=3.9"]
+
 [project.urls]
 "Homepage" = "https://github.com/Teslemetry/python-tesla-fleet-api"
 

tesla_fleet_api/__init__.py

@@ -1,5 +1,7 @@
 """Tesla Fleet API"""
 
+from typing import TYPE_CHECKING, Any
+
 __author__ = "hello@teslemetry.com"
 __version__ = "1.18.0"
 
@@ -21,7 +23,6 @@
     get_tariff_periods,
     unwrap_tariff_v2,
 )
-from tesla_fleet_api.tesla.bluetooth import TeslaBluetooth
 from tesla_fleet_api.tesla.fleet import TeslaFleetApi
 from tesla_fleet_api.tesla.oauth import TeslaFleetOAuth
 from tesla_fleet_api.tesla.vehicle.stream_glue import BleBroadcastStreamGlue, StreamSink
@@ -31,7 +32,10 @@
     register_client,
 )
 from tesla_fleet_api.tessie.tessie import Tessie
-from tesla_fleet_api.util import firmware_at_least, firmware_compare
+from tesla_fleet_api.util import import_ble_class, firmware_at_least, firmware_compare
+
+if TYPE_CHECKING:
+    from tesla_fleet_api.tesla.bluetooth import TeslaBluetooth as TeslaBluetooth
 
 __all__ = [
     "BleBroadcastPublisher",
@@ -47,7 +51,6 @@
     "TariffRate",
     "TariffResolution",
     "TeslaFleetApi",
-    "TeslaBluetooth",
     "TeslaFleetOAuth",
     "Teslemetry",
     "TeslemetryClientRegistration",
@@ -61,3 +64,11 @@
     "register_client",
     "unwrap_tariff_v2",
 ]
+
+
+def __getattr__(name: str) -> Any:
+    # TeslaBluetooth requires bleak (the "ble" extra); import it lazily so
+    # importing this package doesn't require bleak to be installed.
+    if name == "TeslaBluetooth":
+        return import_ble_class("tesla_fleet_api.tesla.bluetooth", "TeslaBluetooth")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

tesla_fleet_api/const.py

@@ -13,6 +13,10 @@
 # broadcast, "verify" additionally reads back state on an ack/broadcast timeout.
 BluetoothConfirmation = Literal["optimistic", "ack", "verify"]
 
+# An idle held BLE link to the vehicle drops at ~42s mean; a trivial GATT read
+# every 20s keeps it alive ~10x longer. See AGENTS.md for the measured evidence.
+DEFAULT_KEEPALIVE_INTERVAL = 20.0
+
 SERVERS: dict[Region, str] = {
     "na": "https://fleet-api.prd.na.vn.cloud.tesla.com",
     "eu": "https://fleet-api.prd.eu.vn.cloud.tesla.com",

tesla_fleet_api/tesla/__init__.py

@@ -1,7 +1,8 @@
 """Tesla Fleet API classes."""
 
+from typing import TYPE_CHECKING, Any
+
 from tesla_fleet_api.tesla.fleet import TeslaFleetApi
-from tesla_fleet_api.tesla.bluetooth import TeslaBluetooth
 from tesla_fleet_api.tesla.oauth import TeslaFleetOAuth
 from tesla_fleet_api.tesla.charging import Charging
 from tesla_fleet_api.tesla.energysite import EnergySites, EnergySite
@@ -22,13 +23,16 @@
     VehiclesBluetooth,
     VehicleFleet,
     VehicleSigned,
-    VehicleBluetooth,
     Vehicle,
 )
+from tesla_fleet_api.util import import_ble_class
+
+if TYPE_CHECKING:
+    from tesla_fleet_api.tesla.bluetooth import TeslaBluetooth as TeslaBluetooth
+    from tesla_fleet_api.tesla.vehicle import VehicleBluetooth as VehicleBluetooth
 
 __all__ = [
     "TeslaFleetApi",
-    "TeslaBluetooth",
     "TeslaFleetOAuth",
     "Charging",
     "EnergySites",
@@ -41,7 +45,6 @@
     "VehiclesBluetooth",
     "VehicleFleet",
     "VehicleSigned",
-    "VehicleBluetooth",
     "Router",
     "VehicleRouter",
     "LOCAL_LIVE_STATUS_KEYS",
@@ -50,3 +53,15 @@
     "merge_live_status",
     "merge_site_info",
 ]
+
+
+def __getattr__(name: str) -> Any:
+    # TeslaBluetooth/VehicleBluetooth require bleak (the "ble" extra);
+    # import them lazily so importing this package doesn't require bleak.
+    if name == "TeslaBluetooth":
+        return import_ble_class("tesla_fleet_api.tesla.bluetooth", "TeslaBluetooth")
+    if name == "VehicleBluetooth":
+        return import_ble_class(
+            "tesla_fleet_api.tesla.vehicle.bluetooth", "VehicleBluetooth"
+        )
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

tesla_fleet_api/tesla/vehicle/__init__.py

@@ -1,16 +1,32 @@
 """Tesla Fleet API classes."""
 
+from typing import TYPE_CHECKING, Any
+
 from tesla_fleet_api.tesla.vehicle.vehicles import Vehicles, VehiclesBluetooth
 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.vehicle import Vehicle
+from tesla_fleet_api.util import import_ble_class
+
+if TYPE_CHECKING:
+    from tesla_fleet_api.tesla.vehicle.bluetooth import (
+        VehicleBluetooth as VehicleBluetooth,
+    )
 
 __all__ = [
     "Vehicles",
     "VehiclesBluetooth",
     "Vehicle",
     "VehicleFleet",
-    "VehicleBluetooth",
     "VehicleSigned",
 ]
+
+
+def __getattr__(name: str) -> Any:
+    # VehicleBluetooth requires bleak (the "ble" extra); import it lazily so
+    # importing this package doesn't require bleak to be installed.
+    if name == "VehicleBluetooth":
+        return import_ble_class(
+            "tesla_fleet_api.tesla.vehicle.bluetooth", "VehicleBluetooth"
+        )
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

tesla_fleet_api/tesla/vehicle/bluetooth.py

@@ -17,7 +17,12 @@
 from cryptography.hazmat.primitives.asymmetric import ec
 from google.protobuf.message import DecodeError
 
-from tesla_fleet_api.const import BluetoothConfirmation, BluetoothVehicleData, LOGGER
+from tesla_fleet_api.const import (
+    DEFAULT_KEEPALIVE_INTERVAL,
+    BluetoothConfirmation,
+    BluetoothVehicleData,
+    LOGGER,
+)
 from tesla_fleet_api.exceptions import (
     WHITELIST_OPERATION_STATUS,
     BluetoothCommandFailed,
@@ -126,10 +131,6 @@
 NAME_UUID = "00002a00-0000-1000-8000-00805f9b34fb"
 APPEARANCE_UUID = "00002a01-0000-1000-8000-00805f9b34fb"
 
-# An idle held BLE link to the vehicle drops at ~42s mean; a trivial GATT read
-# every 20s keeps it alive ~10x longer. See AGENTS.md for the measured evidence.
-DEFAULT_KEEPALIVE_INTERVAL = 20.0
-
 # Measured on a Model 3: infotainment first answers a handshake 4-16s after an RKE
 # wake of a sleeping car, while VCSEC reports awake after ~0.5s.
 DEFAULT_WAKE_TIMEOUT = 30.0

tesla_fleet_api/tesla/vehicle/vehicles.py

@@ -1,21 +1,29 @@
 from __future__ import annotations
 from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar
 
-from bleak.backends.device import BLEDevice
 from cryptography.hazmat.primitives.asymmetric import ec
 
-from tesla_fleet_api.const import BluetoothConfirmation
+from tesla_fleet_api.const import DEFAULT_KEEPALIVE_INTERVAL, BluetoothConfirmation
 from tesla_fleet_api.tesla.vehicle.signed import VehicleSigned
-from tesla_fleet_api.tesla.vehicle.bluetooth import (
-    DEFAULT_KEEPALIVE_INTERVAL,
-    VehicleBluetooth,
-)
 from tesla_fleet_api.tesla.vehicle.fleet import VehicleFleet
 from tesla_fleet_api.tesla.vehicle.vehicle import Vehicle
+from tesla_fleet_api.util import import_ble_class
 
 if TYPE_CHECKING:
+    from bleak.backends.device import BLEDevice
+
     from tesla_fleet_api.tesla.fleet import TeslaFleetApi
     from tesla_fleet_api.tesla.bluetooth import TeslaBluetooth
+    from tesla_fleet_api.tesla.vehicle.bluetooth import VehicleBluetooth
+
+
+def _import_vehicle_bluetooth() -> type["VehicleBluetooth[Any]"]:
+    """Import VehicleBluetooth on demand so the ``ble`` extra stays optional
+    for callers who never create a bluetooth vehicle."""
+    return import_ble_class(
+        "tesla_fleet_api.tesla.vehicle.bluetooth", "VehicleBluetooth"
+    )
+
 
 FleetParentT = TypeVar("FleetParentT", bound="TeslaFleetApi")
 BluetoothClientT = TypeVar("BluetoothClientT", bound="TeslaBluetooth")
@@ -27,11 +35,16 @@ class Vehicles(dict[str, Vehicle[Any]], Generic[FleetParentT]):
     _parent: FleetParentT
     Fleet: type[VehicleFleet[FleetParentT]] = VehicleFleet
     Signed: type[VehicleSigned[FleetParentT]] = VehicleSigned
-    Bluetooth: type[VehicleBluetooth[FleetParentT]] = VehicleBluetooth
 
     def __init__(self, parent: FleetParentT) -> None:
         self._parent = parent
 
+    @property
+    def Bluetooth(self) -> type[VehicleBluetooth[FleetParentT]]:
+        """The bluetooth vehicle class, imported on demand so the ``ble``
+        extra stays optional for callers who never create one."""
+        return _import_vehicle_bluetooth()
+
     def createFleet(self, vin: str) -> VehicleFleet[FleetParentT]:
         """Creates a Fleet API vehicle."""
         vehicle = self.Fleet(self._parent, vin)
@@ -101,11 +114,16 @@ class VehiclesBluetooth(dict[str, Vehicle[Any]], Generic[BluetoothClientT]):
     """Class containing and creating bluetooth vehicles."""
 
     _parent: BluetoothClientT
-    Bluetooth: type[VehicleBluetooth[BluetoothClientT]] = VehicleBluetooth
 
     def __init__(self, parent: BluetoothClientT) -> None:
         self._parent = parent
 
+    @property
+    def Bluetooth(self) -> type[VehicleBluetooth[BluetoothClientT]]:
+        """The bluetooth vehicle class, imported on demand so the ``ble``
+        extra stays optional for callers who never create one."""
+        return _import_vehicle_bluetooth()
+
     def create(
         self,
         vin: str,

tesla_fleet_api/util.py

@@ -1,5 +1,26 @@
 """Shared utility helpers."""
 
+import importlib
+from typing import Any
+
+
+def import_ble_class(module_path: str, class_name: str) -> Any:
+    """Import a bleak-backed class on demand.
+
+    Raises a friendly ImportError naming the ``ble`` extra if bleak is not
+    installed, instead of letting a bare ``ModuleNotFoundError: No module
+    named 'bleak'`` escape to the caller. Not part of ``__all__``: this is an
+    internal cross-module helper, not a public API function.
+    """
+    try:
+        module = importlib.import_module(module_path)
+    except ImportError as err:
+        raise ImportError(
+            "Bluetooth support requires the 'ble' extra: "
+            "install with `pip install tesla-fleet-api[ble]`."
+        ) from err
+    return getattr(module, class_name)
+
 
 def _parse_firmware(version: str) -> tuple[int, ...] | None:
     """Parse a dotted numeric firmware string, or None if it doesn't parse."""