Make boto3 and warrant-lite optional dependencies (#2020)

## Summary

- Moves `boto3` and `warrant-lite` from core dependencies to a `nexity`
optional extra (`pip install pyoverkiz[nexity]`)
- Adds a clear `ImportError` with install instructions when
`NexityAuthStrategy.login()` is called without the extra
- Adds test coverage for the missing-dependency error path
- Documents the optional extra in the getting-started guide and
migration guide

Resolves PY-1 from #2014.

## Test plan

- [x] All 397 existing tests pass
- [x] New `test_login_raises_import_error_without_nexity_extra` test
verifies the error message
- [x] Existing Nexity auth tests still pass (skipped gracefully when
extra is not installed)
- [x] Pre-commit hooks pass (ruff, mypy, ty)

Author: iMicknl

docs/getting-started.md

@@ -25,6 +25,22 @@ uv add pyoverkiz
 pip install pyoverkiz
 ```
 
+### Optional extras
+
+Some servers require additional dependencies that are not installed by default:
+
+| Extra | Server | Packages |
+|-------|--------|----------|
+| `nexity` | Nexity | boto3, warrant-lite |
+
+Install an extra with:
+
+```bash
+uv add "pyoverkiz[nexity]"
+# or
+pip install "pyoverkiz[nexity]"
+```
+
 ## Choose your server
 
 Use a cloud server when you want to connect through the vendor’s public API. Use a local server when you want LAN access to a gateway.

docs/migration-v2.md

@@ -297,4 +297,4 @@ These are not breaking, but worth knowing about when migrating:
 - **Device helpers** — `Device.get_command_definition()` for looking up command metadata.
 - **Reference endpoints** — query server metadata: `get_reference_ui_classes()`, `get_reference_ui_widgets()`, `get_reference_ui_profile()`, `get_reference_controllable_types()`, etc.
 - **Firmware management** — `get_devices_not_up_to_date()`, `get_device_firmware_status()`, `update_device_firmware()`.
-- **boto3 lazy import** — `boto3` is only imported when the Nexity auth strategy is actually used.
+- **Optional Nexity dependencies** — `boto3` and `warrant-lite` are no longer installed by default. Install them with `pip install pyoverkiz[nexity]` if you use the Nexity server. A clear `ImportError` is raised at login time if the extra is missing.

pyoverkiz/auth/strategies.py

@@ -246,10 +246,16 @@ class NexityAuthStrategy(SessionLoginStrategy):
 
     async def login(self) -> None:
         """Perform login using Nexity username and password."""
-        import boto3
-        from botocore.config import Config
-        from botocore.exceptions import ClientError
-        from warrant_lite import WarrantLite
+        try:
+            import boto3
+            from botocore.config import Config
+            from botocore.exceptions import ClientError
+            from warrant_lite import WarrantLite
+        except ImportError as err:
+            raise ImportError(
+                "Nexity authentication requires the 'nexity' extra. "
+                'Install it with: pip install "pyoverkiz[nexity]"'
+            ) from err
 
         loop = asyncio.get_running_loop()
 

pyproject.toml

@@ -17,12 +17,14 @@ dependencies = [
     "aiohttp<4.0.0,>=3.10.3",
     "backoff<3.0,>=1.10.0",
     "attrs>=21.2",
-    "boto3<2.0.0,>=1.18.59",
-    "warrant-lite<2.0.0,>=1.0.4",
     "cattrs>=23.2",
 ]
 
 [project.optional-dependencies]
+nexity = [
+    "boto3<2.0.0,>=1.18.59",
+    "warrant-lite<2.0.0,>=1.0.4",
+]
 docs = [
     "mkdocs>=1.5.0,<2.0",
     "mkdocs-material>=9.5.0",

tests/test_auth.py

@@ -7,13 +7,13 @@
 
 import base64
 import datetime
+import importlib.util
 import json
 import sys
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 from aiohttp import ClientSession
-from botocore.exceptions import ClientError
 
 from pyoverkiz.auth.base import AuthContext
 from pyoverkiz.auth.credentials import (
@@ -40,6 +40,11 @@
 from pyoverkiz.exceptions import InvalidTokenError, NexityBadCredentialsError
 from pyoverkiz.models import ServerConfig
 
+HAS_NEXITY_DEPS = importlib.util.find_spec("boto3") is not None
+
+if HAS_NEXITY_DEPS:
+    from botocore.exceptions import ClientError
+
 
 class TestAuthContext:
     """Test AuthContext functionality."""
@@ -499,6 +504,28 @@ def test_boto3_not_imported_at_module_load(self):
                     sys.modules[mod] = value
 
     @pytest.mark.asyncio
+    async def test_login_raises_import_error_without_nexity_extra(self):
+        """Login raises ImportError with install hint when nexity extra is missing."""
+        server_config = ServerConfig(
+            server=Server.NEXITY,
+            name="Nexity",
+            endpoint="https://api.nexity.com",
+            manufacturer="Nexity",
+            api_type=APIType.CLOUD,
+        )
+        credentials = UsernamePasswordCredentials("user", "pass")
+        session = AsyncMock(spec=ClientSession)
+
+        strategy = NexityAuthStrategy(credentials, session, server_config, True)
+
+        with (
+            patch.dict(sys.modules, {"boto3": None}),
+            pytest.raises(ImportError, match="pyoverkiz\\[nexity\\]"),
+        ):
+            await strategy.login()
+
+    @pytest.mark.asyncio
+    @pytest.mark.skipif(not HAS_NEXITY_DEPS, reason="nexity extra not installed")
     async def test_login_maps_invalid_credentials_client_error(self):
         """Map Cognito bad-credential errors to NexityBadCredentialsError."""
         server_config = ServerConfig(
@@ -527,6 +554,7 @@ async def test_login_maps_invalid_credentials_client_error(self):
                 await strategy.login()
 
     @pytest.mark.asyncio
+    @pytest.mark.skipif(not HAS_NEXITY_DEPS, reason="nexity extra not installed")
     async def test_login_propagates_non_auth_client_error(self):
         """Propagate non-auth Cognito errors to preserve failure context."""
         server_config = ServerConfig(