quilt-hp-python 0.1.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- quilt_hp/__init__.py +22 -0
- quilt_hp/_paths.py +26 -0
- quilt_hp/_proto/__init__.py +0 -0
- quilt_hp/_proto/quilt_device_pairing_pb2.py +56 -0
- quilt_hp/_proto/quilt_device_pairing_pb2.pyi +317 -0
- quilt_hp/_proto/quilt_device_pairing_pb2_grpc.py +24 -0
- quilt_hp/_proto/quilt_hds_pb2.py +292 -0
- quilt_hp/_proto/quilt_hds_pb2.pyi +3947 -0
- quilt_hp/_proto/quilt_hds_pb2_grpc.py +1732 -0
- quilt_hp/_proto/quilt_notifier_pb2.py +55 -0
- quilt_hp/_proto/quilt_notifier_pb2.pyi +258 -0
- quilt_hp/_proto/quilt_notifier_pb2_grpc.py +97 -0
- quilt_hp/_proto/quilt_services_pb2.py +171 -0
- quilt_hp/_proto/quilt_services_pb2.pyi +1320 -0
- quilt_hp/_proto/quilt_services_pb2_grpc.py +1188 -0
- quilt_hp/_proto/quilt_system_pb2.py +53 -0
- quilt_hp/_proto/quilt_system_pb2.pyi +164 -0
- quilt_hp/_proto/quilt_system_pb2_grpc.py +270 -0
- quilt_hp/auth.py +244 -0
- quilt_hp/cli/__init__.py +1 -0
- quilt_hp/cli/main.py +770 -0
- quilt_hp/cli/settings.py +123 -0
- quilt_hp/cli/store.py +105 -0
- quilt_hp/cli/tui.py +2677 -0
- quilt_hp/client.py +616 -0
- quilt_hp/const.py +57 -0
- quilt_hp/exceptions.py +23 -0
- quilt_hp/models/__init__.py +85 -0
- quilt_hp/models/comfort.py +47 -0
- quilt_hp/models/controller.py +135 -0
- quilt_hp/models/energy.py +31 -0
- quilt_hp/models/enums.py +298 -0
- quilt_hp/models/indoor_unit.py +412 -0
- quilt_hp/models/outdoor_unit.py +71 -0
- quilt_hp/models/qsm.py +105 -0
- quilt_hp/models/schedule.py +98 -0
- quilt_hp/models/sensor.py +92 -0
- quilt_hp/models/software_update.py +74 -0
- quilt_hp/models/space.py +177 -0
- quilt_hp/models/system.py +451 -0
- quilt_hp/py.typed +1 -0
- quilt_hp/services/__init__.py +1 -0
- quilt_hp/services/hds.py +480 -0
- quilt_hp/services/streaming.py +561 -0
- quilt_hp/services/system.py +95 -0
- quilt_hp/services/user.py +143 -0
- quilt_hp/tokens.py +119 -0
- quilt_hp/transport.py +192 -0
- quilt_hp_python-0.1.1.dist-info/METADATA +172 -0
- quilt_hp_python-0.1.1.dist-info/RECORD +53 -0
- quilt_hp_python-0.1.1.dist-info/WHEEL +4 -0
- quilt_hp_python-0.1.1.dist-info/entry_points.txt +2 -0
- quilt_hp_python-0.1.1.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
"""UserService — current user info."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Callable
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
from enum import IntEnum
|
|
8
|
+
from typing import Any, Protocol, cast
|
|
9
|
+
|
|
10
|
+
import grpc.aio
|
|
11
|
+
|
|
12
|
+
from quilt_hp._proto import quilt_services_pb2 as svc
|
|
13
|
+
from quilt_hp._proto import quilt_services_pb2_grpc as svc_grpc
|
|
14
|
+
from quilt_hp.exceptions import QuiltError
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class DeclaredUserType(IntEnum):
|
|
18
|
+
"""Declared user type used by UserAttributes."""
|
|
19
|
+
|
|
20
|
+
UNSPECIFIED = int(svc.DECLARED_USER_TYPE_UNSPECIFIED)
|
|
21
|
+
HOMEOWNER = int(svc.DECLARED_USER_TYPE_HOMEOWNER)
|
|
22
|
+
PARTNER = int(svc.DECLARED_USER_TYPE_PARTNER)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
@dataclass(slots=True)
|
|
26
|
+
class User:
|
|
27
|
+
"""Quilt user account."""
|
|
28
|
+
|
|
29
|
+
id: str
|
|
30
|
+
first_name: str
|
|
31
|
+
last_name: str
|
|
32
|
+
email: str
|
|
33
|
+
phone_number: str
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
@dataclass(slots=True)
|
|
37
|
+
class UserAttributes:
|
|
38
|
+
"""Additional user attributes exposed by UserService."""
|
|
39
|
+
|
|
40
|
+
declared_user_type: DeclaredUserType
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class _UserServiceStub(Protocol):
|
|
44
|
+
async def GetLoggedInUser(self, request: svc.GetLoggedInUserRequest) -> object: ...
|
|
45
|
+
async def UpdateLoggedInUser(self, request: svc.UpdateLoggedInUserRequest) -> object: ...
|
|
46
|
+
async def GetUserAttributes(self, request: svc.GetUserAttributesRequest) -> object: ...
|
|
47
|
+
async def PatchUserAttributes(self, request: svc.PatchUserAttributesRequest) -> object: ...
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _to_user(response: Any) -> User:
|
|
51
|
+
user = response.user if hasattr(response, "user") else response
|
|
52
|
+
return User(
|
|
53
|
+
id=user.quilt_user_id,
|
|
54
|
+
first_name=user.first_name,
|
|
55
|
+
last_name=user.last_name,
|
|
56
|
+
email=user.email,
|
|
57
|
+
phone_number=user.phone_number,
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def _to_user_attributes(response: Any) -> UserAttributes:
|
|
62
|
+
try:
|
|
63
|
+
declared_user_type = DeclaredUserType(response.declared_user_type)
|
|
64
|
+
except ValueError:
|
|
65
|
+
declared_user_type = DeclaredUserType.UNSPECIFIED
|
|
66
|
+
return UserAttributes(declared_user_type=declared_user_type)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
class UserService:
|
|
70
|
+
"""Async wrapper for UserService gRPC methods."""
|
|
71
|
+
|
|
72
|
+
def __init__(self, channel: grpc.aio.Channel) -> None:
|
|
73
|
+
factory = cast("Callable[[grpc.aio.Channel], _UserServiceStub]", svc_grpc.UserServiceStub)
|
|
74
|
+
self._stub: _UserServiceStub = factory(channel)
|
|
75
|
+
|
|
76
|
+
async def get_current_user(self) -> User:
|
|
77
|
+
"""Get the currently authenticated user."""
|
|
78
|
+
try:
|
|
79
|
+
response = cast(
|
|
80
|
+
"Any",
|
|
81
|
+
await self._stub.GetLoggedInUser(svc.GetLoggedInUserRequest()),
|
|
82
|
+
)
|
|
83
|
+
except grpc.aio.AioRpcError as exc:
|
|
84
|
+
raise QuiltError(f"GetLoggedInUser failed: {exc.details()}") from exc
|
|
85
|
+
return _to_user(response)
|
|
86
|
+
|
|
87
|
+
async def update_current_user(
|
|
88
|
+
self,
|
|
89
|
+
*,
|
|
90
|
+
first_name: str,
|
|
91
|
+
last_name: str,
|
|
92
|
+
phone_number: str | None = None,
|
|
93
|
+
) -> User:
|
|
94
|
+
"""Update first/last name and optional phone number for current user."""
|
|
95
|
+
try:
|
|
96
|
+
response = cast(
|
|
97
|
+
"Any",
|
|
98
|
+
await self._stub.UpdateLoggedInUser(
|
|
99
|
+
svc.UpdateLoggedInUserRequest(
|
|
100
|
+
first_name=first_name,
|
|
101
|
+
last_name=last_name,
|
|
102
|
+
phone_number=phone_number or "",
|
|
103
|
+
)
|
|
104
|
+
),
|
|
105
|
+
)
|
|
106
|
+
except grpc.aio.AioRpcError as exc:
|
|
107
|
+
raise QuiltError(f"UpdateLoggedInUser failed: {exc.details()}") from exc
|
|
108
|
+
return _to_user(response)
|
|
109
|
+
|
|
110
|
+
async def get_user_attributes(self) -> UserAttributes:
|
|
111
|
+
"""Get current user's additional attributes."""
|
|
112
|
+
try:
|
|
113
|
+
response = cast(
|
|
114
|
+
"Any",
|
|
115
|
+
await self._stub.GetUserAttributes(svc.GetUserAttributesRequest()),
|
|
116
|
+
)
|
|
117
|
+
except grpc.aio.AioRpcError as exc:
|
|
118
|
+
raise QuiltError(f"GetUserAttributes failed: {exc.details()}") from exc
|
|
119
|
+
return _to_user_attributes(response)
|
|
120
|
+
|
|
121
|
+
async def patch_user_attributes(
|
|
122
|
+
self,
|
|
123
|
+
*,
|
|
124
|
+
declared_user_type: DeclaredUserType,
|
|
125
|
+
) -> UserAttributes:
|
|
126
|
+
"""Patch user attributes for the current user."""
|
|
127
|
+
try:
|
|
128
|
+
response = cast(
|
|
129
|
+
"Any",
|
|
130
|
+
await self._stub.PatchUserAttributes(
|
|
131
|
+
svc.PatchUserAttributesRequest(
|
|
132
|
+
user_attributes=svc.UserAttributes(
|
|
133
|
+
declared_user_type=cast(
|
|
134
|
+
"svc.DeclaredUserType.ValueType",
|
|
135
|
+
int(declared_user_type),
|
|
136
|
+
),
|
|
137
|
+
)
|
|
138
|
+
)
|
|
139
|
+
),
|
|
140
|
+
)
|
|
141
|
+
except grpc.aio.AioRpcError as exc:
|
|
142
|
+
raise QuiltError(f"PatchUserAttributes failed: {exc.details()}") from exc
|
|
143
|
+
return _to_user_attributes(response)
|
quilt_hp/tokens.py
ADDED
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
"""Token types and storage protocols for Quilt authentication.
|
|
2
|
+
|
|
3
|
+
The core library defines the data types and an async-first ``TokenStore``
|
|
4
|
+
protocol. Persistence is the caller's responsibility — the CLI provides
|
|
5
|
+
``FileStore`` in ``quilt_hp.cli.store``.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import time
|
|
11
|
+
from dataclasses import dataclass
|
|
12
|
+
from enum import StrEnum
|
|
13
|
+
from typing import Protocol
|
|
14
|
+
|
|
15
|
+
_TOKEN_BUFFER_S = 300 # treat tokens as expired 5 min before actual expiry
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
@dataclass(slots=True)
|
|
19
|
+
class CachedTokens:
|
|
20
|
+
"""A Cognito IdToken plus its refresh token and expiry timestamp."""
|
|
21
|
+
|
|
22
|
+
id_token: str
|
|
23
|
+
refresh_token: str
|
|
24
|
+
expires_at: float # unix timestamp
|
|
25
|
+
|
|
26
|
+
@property
|
|
27
|
+
def is_expired(self) -> bool:
|
|
28
|
+
"""True if the IdToken has expired (with a 5-minute safety buffer)."""
|
|
29
|
+
return time.time() > self.expires_at - _TOKEN_BUFFER_S
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class TokenStore(Protocol):
|
|
33
|
+
"""Async-first protocol for token persistence.
|
|
34
|
+
|
|
35
|
+
Implement this to integrate with any storage backend
|
|
36
|
+
(filesystem, HA secure storage, database, keychain, …).
|
|
37
|
+
"""
|
|
38
|
+
|
|
39
|
+
async def load(self, email: str) -> CachedTokens | None:
|
|
40
|
+
"""Return cached tokens for *email*, or None if absent / invalid."""
|
|
41
|
+
...
|
|
42
|
+
|
|
43
|
+
async def save(self, email: str, tokens: CachedTokens) -> None:
|
|
44
|
+
"""Persist *tokens* for *email*."""
|
|
45
|
+
...
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class LegacyTokenStore(Protocol):
|
|
49
|
+
"""Compatibility protocol for existing synchronous token stores."""
|
|
50
|
+
|
|
51
|
+
def load(self, email: str) -> CachedTokens | None:
|
|
52
|
+
"""Return cached tokens for *email*, or None if absent / invalid."""
|
|
53
|
+
...
|
|
54
|
+
|
|
55
|
+
def save(self, email: str, tokens: CachedTokens) -> None:
|
|
56
|
+
"""Persist *tokens* for *email*."""
|
|
57
|
+
...
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
type TokenStoreLike = TokenStore | LegacyTokenStore
|
|
61
|
+
type TokenPersistenceBackend = TokenStoreLike
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class CurrentTokenProvider(Protocol):
|
|
65
|
+
"""Protocol for objects that can provide the current auth token."""
|
|
66
|
+
|
|
67
|
+
def get_current_token(self) -> str:
|
|
68
|
+
"""Return the current authorization token."""
|
|
69
|
+
...
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
class TokenRefreshReason(StrEnum):
|
|
73
|
+
"""Why a token refresh is being attempted."""
|
|
74
|
+
|
|
75
|
+
EXPIRED_CACHED_TOKEN = "expired_cached_token"
|
|
76
|
+
TRANSPORT_UNAUTHENTICATED = "transport_unauthenticated"
|
|
77
|
+
STREAM_UNAUTHENTICATED = "stream_unauthenticated"
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
@dataclass(slots=True, frozen=True)
|
|
81
|
+
class TokenRefreshContext:
|
|
82
|
+
"""Context describing a token refresh attempt."""
|
|
83
|
+
|
|
84
|
+
reason: TokenRefreshReason
|
|
85
|
+
source: str
|
|
86
|
+
attempt: int = 1
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
class RefreshFailureAction(StrEnum):
|
|
90
|
+
"""Policy decision for handling refresh failures."""
|
|
91
|
+
|
|
92
|
+
FALLBACK_TO_OTP = "fallback_to_otp"
|
|
93
|
+
RAISE = "raise"
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
class TokenRefreshHooks(Protocol):
|
|
97
|
+
"""Optional lifecycle hooks invoked around token refresh attempts."""
|
|
98
|
+
|
|
99
|
+
async def on_refresh_start(self, context: TokenRefreshContext) -> None:
|
|
100
|
+
"""Called before attempting token refresh."""
|
|
101
|
+
...
|
|
102
|
+
|
|
103
|
+
async def on_refresh_success(self, context: TokenRefreshContext, tokens: CachedTokens) -> None:
|
|
104
|
+
"""Called when refresh succeeds and new tokens are produced."""
|
|
105
|
+
...
|
|
106
|
+
|
|
107
|
+
async def on_refresh_failure(self, context: TokenRefreshContext, error: Exception) -> None:
|
|
108
|
+
"""Called when refresh fails."""
|
|
109
|
+
...
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
class TokenRefreshPolicy(Protocol):
|
|
113
|
+
"""Host-defined policy for deciding what to do after refresh failure."""
|
|
114
|
+
|
|
115
|
+
def on_refresh_failure(
|
|
116
|
+
self, context: TokenRefreshContext, error: Exception
|
|
117
|
+
) -> RefreshFailureAction:
|
|
118
|
+
"""Return fallback strategy when refresh fails."""
|
|
119
|
+
...
|
quilt_hp/transport.py
ADDED
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
"""Async gRPC transport — channel creation and auth interceptor."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import inspect
|
|
6
|
+
from collections.abc import Awaitable, Callable
|
|
7
|
+
from typing import cast
|
|
8
|
+
|
|
9
|
+
import grpc
|
|
10
|
+
import grpc.aio
|
|
11
|
+
|
|
12
|
+
from quilt_hp.const import (
|
|
13
|
+
APP_VERSION,
|
|
14
|
+
GRPC_CHANNEL_OPTIONS,
|
|
15
|
+
Environment,
|
|
16
|
+
grpc_host,
|
|
17
|
+
)
|
|
18
|
+
from quilt_hp.tokens import CurrentTokenProvider, TokenRefreshContext, TokenRefreshReason
|
|
19
|
+
|
|
20
|
+
type RefreshCallback = (
|
|
21
|
+
Callable[[], Awaitable[None]] | Callable[[TokenRefreshContext], Awaitable[None]]
|
|
22
|
+
)
|
|
23
|
+
type TokenProviderLike = Callable[[], str] | CurrentTokenProvider
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def _resolve_token_provider(token_provider: TokenProviderLike) -> Callable[[], str]:
|
|
27
|
+
if callable(token_provider):
|
|
28
|
+
return token_provider
|
|
29
|
+
return token_provider.get_current_token
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
async def _invoke_refresh_callback(
|
|
33
|
+
refresh_callback: RefreshCallback, context: TokenRefreshContext
|
|
34
|
+
) -> None:
|
|
35
|
+
try:
|
|
36
|
+
has_params = bool(inspect.signature(refresh_callback).parameters)
|
|
37
|
+
except TypeError:
|
|
38
|
+
has_params = False
|
|
39
|
+
except ValueError:
|
|
40
|
+
has_params = False
|
|
41
|
+
if has_params:
|
|
42
|
+
await cast("Callable[[TokenRefreshContext], Awaitable[None]]", refresh_callback)(context)
|
|
43
|
+
return
|
|
44
|
+
await cast("Callable[[], Awaitable[None]]", refresh_callback)()
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
class _AuthInterceptor(
|
|
48
|
+
grpc.aio.UnaryUnaryClientInterceptor, # type: ignore[misc]
|
|
49
|
+
grpc.aio.UnaryStreamClientInterceptor, # type: ignore[misc]
|
|
50
|
+
grpc.aio.StreamUnaryClientInterceptor, # type: ignore[misc]
|
|
51
|
+
grpc.aio.StreamStreamClientInterceptor, # type: ignore[misc]
|
|
52
|
+
):
|
|
53
|
+
"""Injects authorization and app-version metadata into every gRPC call.
|
|
54
|
+
|
|
55
|
+
If ``refresh_callback`` is provided, it is awaited once on
|
|
56
|
+
``UNAUTHENTICATED`` and the call is retried with fresh credentials.
|
|
57
|
+
"""
|
|
58
|
+
|
|
59
|
+
def __init__(
|
|
60
|
+
self,
|
|
61
|
+
token_provider: TokenProviderLike,
|
|
62
|
+
refresh_callback: RefreshCallback | None = None,
|
|
63
|
+
) -> None:
|
|
64
|
+
self._token_provider = _resolve_token_provider(token_provider)
|
|
65
|
+
self._refresh_callback = refresh_callback
|
|
66
|
+
|
|
67
|
+
def _metadata(self) -> list[tuple[str, str]]:
|
|
68
|
+
return [
|
|
69
|
+
("authorization", self._token_provider()),
|
|
70
|
+
("x-quilt-app-version", APP_VERSION),
|
|
71
|
+
]
|
|
72
|
+
|
|
73
|
+
def _patch(
|
|
74
|
+
self, client_call_details: grpc.aio.ClientCallDetails
|
|
75
|
+
) -> grpc.aio.ClientCallDetails:
|
|
76
|
+
return grpc.aio.ClientCallDetails(
|
|
77
|
+
method=client_call_details.method,
|
|
78
|
+
timeout=client_call_details.timeout,
|
|
79
|
+
metadata=list(client_call_details.metadata or []) + self._metadata(),
|
|
80
|
+
credentials=client_call_details.credentials,
|
|
81
|
+
wait_for_ready=client_call_details.wait_for_ready,
|
|
82
|
+
)
|
|
83
|
+
|
|
84
|
+
async def _refresh_and_retry(
|
|
85
|
+
self,
|
|
86
|
+
continuation: Callable[..., Awaitable[object]],
|
|
87
|
+
client_call_details: grpc.aio.ClientCallDetails,
|
|
88
|
+
*args: object,
|
|
89
|
+
) -> object:
|
|
90
|
+
"""Refresh the token and retry the call once."""
|
|
91
|
+
if self._refresh_callback is not None:
|
|
92
|
+
await _invoke_refresh_callback(
|
|
93
|
+
self._refresh_callback,
|
|
94
|
+
TokenRefreshContext(
|
|
95
|
+
reason=TokenRefreshReason.TRANSPORT_UNAUTHENTICATED,
|
|
96
|
+
source="transport",
|
|
97
|
+
),
|
|
98
|
+
)
|
|
99
|
+
return await continuation(self._patch(client_call_details), *args)
|
|
100
|
+
|
|
101
|
+
async def intercept_unary_unary(
|
|
102
|
+
self,
|
|
103
|
+
continuation: Callable[
|
|
104
|
+
[grpc.aio.ClientCallDetails, object],
|
|
105
|
+
Awaitable[object],
|
|
106
|
+
],
|
|
107
|
+
client_call_details: grpc.aio.ClientCallDetails,
|
|
108
|
+
request: object,
|
|
109
|
+
) -> object:
|
|
110
|
+
try:
|
|
111
|
+
return await continuation(self._patch(client_call_details), request)
|
|
112
|
+
except grpc.aio.AioRpcError as exc:
|
|
113
|
+
if exc.code() == grpc.StatusCode.UNAUTHENTICATED and self._refresh_callback:
|
|
114
|
+
return await self._refresh_and_retry(continuation, client_call_details, request)
|
|
115
|
+
raise
|
|
116
|
+
|
|
117
|
+
async def intercept_unary_stream(
|
|
118
|
+
self,
|
|
119
|
+
continuation: Callable[
|
|
120
|
+
[grpc.aio.ClientCallDetails, object],
|
|
121
|
+
Awaitable[object],
|
|
122
|
+
],
|
|
123
|
+
client_call_details: grpc.aio.ClientCallDetails,
|
|
124
|
+
request: object,
|
|
125
|
+
) -> object:
|
|
126
|
+
try:
|
|
127
|
+
return await continuation(self._patch(client_call_details), request)
|
|
128
|
+
except grpc.aio.AioRpcError as exc:
|
|
129
|
+
if exc.code() == grpc.StatusCode.UNAUTHENTICATED and self._refresh_callback:
|
|
130
|
+
return await self._refresh_and_retry(continuation, client_call_details, request)
|
|
131
|
+
raise
|
|
132
|
+
|
|
133
|
+
async def intercept_stream_unary(
|
|
134
|
+
self,
|
|
135
|
+
continuation: Callable[
|
|
136
|
+
[grpc.aio.ClientCallDetails, object],
|
|
137
|
+
Awaitable[object],
|
|
138
|
+
],
|
|
139
|
+
client_call_details: grpc.aio.ClientCallDetails,
|
|
140
|
+
request_iterator: object,
|
|
141
|
+
) -> object:
|
|
142
|
+
return await continuation(self._patch(client_call_details), request_iterator)
|
|
143
|
+
|
|
144
|
+
async def intercept_stream_stream(
|
|
145
|
+
self,
|
|
146
|
+
continuation: Callable[
|
|
147
|
+
[grpc.aio.ClientCallDetails, object],
|
|
148
|
+
Awaitable[object],
|
|
149
|
+
],
|
|
150
|
+
client_call_details: grpc.aio.ClientCallDetails,
|
|
151
|
+
request_iterator: object,
|
|
152
|
+
) -> object:
|
|
153
|
+
return await continuation(self._patch(client_call_details), request_iterator)
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def create_channel(
|
|
157
|
+
token_provider: TokenProviderLike,
|
|
158
|
+
environment: Environment = Environment.PROD,
|
|
159
|
+
refresh_callback: RefreshCallback | None = None,
|
|
160
|
+
) -> grpc.aio.Channel:
|
|
161
|
+
"""Create an authenticated async gRPC channel.
|
|
162
|
+
|
|
163
|
+
Args:
|
|
164
|
+
token_provider: A callable that returns the current JWT token.
|
|
165
|
+
environment: Which Quilt API environment to connect to.
|
|
166
|
+
refresh_callback: Optional async callable invoked once on
|
|
167
|
+
UNAUTHENTICATED to refresh the token before retrying.
|
|
168
|
+
|
|
169
|
+
Returns:
|
|
170
|
+
An async gRPC channel with TLS and auth interceptor.
|
|
171
|
+
"""
|
|
172
|
+
host = grpc_host(environment)
|
|
173
|
+
creds = grpc.ssl_channel_credentials()
|
|
174
|
+
interceptors = [_AuthInterceptor(token_provider, refresh_callback)]
|
|
175
|
+
return grpc.aio.secure_channel(
|
|
176
|
+
host,
|
|
177
|
+
creds,
|
|
178
|
+
options=GRPC_CHANNEL_OPTIONS,
|
|
179
|
+
interceptors=interceptors,
|
|
180
|
+
)
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def auth_metadata(token_provider: TokenProviderLike) -> list[tuple[str, str]]:
|
|
184
|
+
"""Build gRPC metadata with auth headers.
|
|
185
|
+
|
|
186
|
+
Useful for stream-stream RPCs where the channel interceptor may not fire.
|
|
187
|
+
"""
|
|
188
|
+
resolved_provider = _resolve_token_provider(token_provider)
|
|
189
|
+
return [
|
|
190
|
+
("authorization", resolved_provider()),
|
|
191
|
+
("x-quilt-app-version", APP_VERSION),
|
|
192
|
+
]
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: quilt-hp-python
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: Async Python client for Quilt mini-split HVAC systems
|
|
5
|
+
Project-URL: Repository, https://github.com/eman/quilt-hp-python
|
|
6
|
+
Project-URL: Issues, https://github.com/eman/quilt-hp-python/issues
|
|
7
|
+
Project-URL: Changelog, https://github.com/eman/quilt-hp-python/blob/main/CHANGELOG.md
|
|
8
|
+
Author: Emmanuel
|
|
9
|
+
License: MIT License
|
|
10
|
+
|
|
11
|
+
Copyright (c) 2026
|
|
12
|
+
|
|
13
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
14
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
15
|
+
in the Software without restriction, including without limitation the rights
|
|
16
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
17
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
18
|
+
furnished to do so, subject to the following conditions:
|
|
19
|
+
|
|
20
|
+
The above copyright notice and this permission notice shall be included in all
|
|
21
|
+
copies or substantial portions of the Software.
|
|
22
|
+
|
|
23
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
24
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
25
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
26
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
27
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
28
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
29
|
+
SOFTWARE.
|
|
30
|
+
License-File: LICENSE
|
|
31
|
+
Keywords: grpc,home-automation,hvac,mini-split,quilt
|
|
32
|
+
Classifier: Development Status :: 3 - Alpha
|
|
33
|
+
Classifier: Framework :: AsyncIO
|
|
34
|
+
Classifier: Intended Audience :: Developers
|
|
35
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
36
|
+
Classifier: Programming Language :: Python :: 3
|
|
37
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
38
|
+
Classifier: Topic :: Home Automation
|
|
39
|
+
Classifier: Typing :: Typed
|
|
40
|
+
Requires-Python: >=3.14
|
|
41
|
+
Requires-Dist: boto3>=1.35
|
|
42
|
+
Requires-Dist: grpcio>=1.70
|
|
43
|
+
Requires-Dist: platformdirs>=4.0
|
|
44
|
+
Requires-Dist: protobuf>=5.0
|
|
45
|
+
Provides-Extra: cli
|
|
46
|
+
Requires-Dist: rich>=13.0; extra == 'cli'
|
|
47
|
+
Requires-Dist: textual>=0.80; extra == 'cli'
|
|
48
|
+
Requires-Dist: typer>=0.12; extra == 'cli'
|
|
49
|
+
Provides-Extra: dev
|
|
50
|
+
Requires-Dist: boto3-stubs[cognito-idp]; extra == 'dev'
|
|
51
|
+
Requires-Dist: build>=1.2; extra == 'dev'
|
|
52
|
+
Requires-Dist: grpcio-tools>=1.70; extra == 'dev'
|
|
53
|
+
Requires-Dist: mypy-protobuf>=3.6; extra == 'dev'
|
|
54
|
+
Requires-Dist: mypy>=1.15; extra == 'dev'
|
|
55
|
+
Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
|
|
56
|
+
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
|
|
57
|
+
Requires-Dist: pytest>=8.0; extra == 'dev'
|
|
58
|
+
Requires-Dist: ruff>=0.11; extra == 'dev'
|
|
59
|
+
Requires-Dist: twine>=6.0; extra == 'dev'
|
|
60
|
+
Provides-Extra: docs
|
|
61
|
+
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
|
|
62
|
+
Requires-Dist: mkdocs>=1.6; extra == 'docs'
|
|
63
|
+
Requires-Dist: mkdocstrings[python]>=0.29; extra == 'docs'
|
|
64
|
+
Description-Content-Type: text/markdown
|
|
65
|
+
|
|
66
|
+
# quilt-hp-python
|
|
67
|
+
|
|
68
|
+
Async Python client library for [Quilt](https://www.quilt.com/) mini-split HVAC systems.
|
|
69
|
+
|
|
70
|
+
Communicates with the Quilt cloud API via gRPC to control spaces (rooms), indoor units,
|
|
71
|
+
comfort presets, schedules, and stream real-time updates.
|
|
72
|
+
|
|
73
|
+
## Installation
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
pip install quilt-hp-python
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
With the optional CLI:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
pip install "quilt-hp-python[cli]"
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Quick Start
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
import asyncio
|
|
89
|
+
from quilt_hp import QuiltClient
|
|
90
|
+
|
|
91
|
+
async def main():
|
|
92
|
+
async with QuiltClient("user@example.com") as client:
|
|
93
|
+
await client.login(otp_callback=lambda email: input(f"OTP for {email}: "))
|
|
94
|
+
|
|
95
|
+
# List spaces
|
|
96
|
+
for space in await client.list_spaces():
|
|
97
|
+
print(f"{space.name}: {space.state.ambient_temperature_c}°C")
|
|
98
|
+
|
|
99
|
+
# Set a room to COOL at 22°C
|
|
100
|
+
from quilt_hp.models.enums import HVACMode
|
|
101
|
+
spaces = await client.list_spaces()
|
|
102
|
+
await client.set_space(spaces[0].id, mode=HVACMode.COOL, cool_setpoint_c=22.0)
|
|
103
|
+
|
|
104
|
+
# Stream real-time updates
|
|
105
|
+
spaces = await client.list_spaces()
|
|
106
|
+
topics = [f"hds/space/{s.id}" for s in spaces]
|
|
107
|
+
async with client.stream(topics) as stream:
|
|
108
|
+
stream.on_space_update(lambda s: print(f"{s.name}: {s.state.ambient_temperature_c}°C"))
|
|
109
|
+
await asyncio.sleep(60)
|
|
110
|
+
|
|
111
|
+
asyncio.run(main())
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## CLI
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
# Authenticate (caches tokens for subsequent commands)
|
|
118
|
+
quilt login --email user@example.com
|
|
119
|
+
|
|
120
|
+
# Full system inventory + telemetry (summary)
|
|
121
|
+
quilt info
|
|
122
|
+
|
|
123
|
+
# Full system snapshot as JSON for automation
|
|
124
|
+
quilt info --output json
|
|
125
|
+
|
|
126
|
+
# All device/entity IDs (includes update entities)
|
|
127
|
+
quilt devices
|
|
128
|
+
|
|
129
|
+
# Current sensor values + setpoints
|
|
130
|
+
quilt values
|
|
131
|
+
|
|
132
|
+
# Machine-readable values for scripting
|
|
133
|
+
quilt values --output json
|
|
134
|
+
|
|
135
|
+
# Energy usage
|
|
136
|
+
quilt energy --period week
|
|
137
|
+
|
|
138
|
+
# Set a room to cooling mode
|
|
139
|
+
quilt set "Living Room" --mode cool --cool 22
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Development
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
git clone https://github.com/eman/quilt-hp-python.git
|
|
146
|
+
cd quilt-hp-python
|
|
147
|
+
python -m venv .venv
|
|
148
|
+
source .venv/bin/activate
|
|
149
|
+
pip install -e ".[dev,cli]"
|
|
150
|
+
|
|
151
|
+
# Run checks
|
|
152
|
+
ruff check src/ tests/
|
|
153
|
+
ruff format --check src/ tests/
|
|
154
|
+
mypy src/quilt_hp/
|
|
155
|
+
pytest
|
|
156
|
+
python -m build
|
|
157
|
+
twine check dist/*
|
|
158
|
+
|
|
159
|
+
# Recompile protobuf stubs (requires grpcio-tools)
|
|
160
|
+
# Proto sources are vendored in ./proto/cleaned for standalone use.
|
|
161
|
+
# Optional but recommended: install protobuf includes (e.g. `brew install protobuf`)
|
|
162
|
+
./scripts/regen_protos.sh
|
|
163
|
+
|
|
164
|
+
# Build project docs (MkDocs Material)
|
|
165
|
+
pip install -e ".[docs]"
|
|
166
|
+
python scripts/check_docs_nav.py
|
|
167
|
+
mkdocs build --strict
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
## License
|
|
171
|
+
|
|
172
|
+
MIT
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
quilt_hp/__init__.py,sha256=kNmiou9vOsvN8Sg_6kXTeQmXqG1vr210yeKWt5GiO_s,465
|
|
2
|
+
quilt_hp/_paths.py,sha256=3IX2Fsv4gU48jM6ypsAiHJr_y4yyTAizM0cDLjL8r9o,691
|
|
3
|
+
quilt_hp/auth.py,sha256=vMd2eZMfRcfUf5xLoxsVxumURXUB0y5ABV53fKMQGKY,8642
|
|
4
|
+
quilt_hp/client.py,sha256=J60DjZTDzSdQyi3aKA9FskC42cDWFe2ea7HqnrhwASs,22126
|
|
5
|
+
quilt_hp/const.py,sha256=GdmBwkxIxo0dPEf5ITxDHTmqKGOhOuQ3_EtmNW9_6aY,1423
|
|
6
|
+
quilt_hp/exceptions.py,sha256=atgwk3aEmNyC69A1MOZKiu9hbl661ip-zGPCWRhOvgw,570
|
|
7
|
+
quilt_hp/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
|
|
8
|
+
quilt_hp/tokens.py,sha256=njju8FoJI4q574J_yjWTdfTapq5kH_a5mJ0q-zXuKYM,3530
|
|
9
|
+
quilt_hp/transport.py,sha256=uVJ6SYmJyF5yuPuYzK3O-1T06kAKYHybFwiW8S59QkQ,6628
|
|
10
|
+
quilt_hp/_proto/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
11
|
+
quilt_hp/_proto/quilt_device_pairing_pb2.py,sha256=L7Cznr5ZdkWQkeywwu48EVBntoUMXwgCrqIhsULqRa4,5208
|
|
12
|
+
quilt_hp/_proto/quilt_device_pairing_pb2.pyi,sha256=bE6bLf0KSxuxB2ZBR6x9LP81dt0ZIL2PWJEfVfiR7oM,14432
|
|
13
|
+
quilt_hp/_proto/quilt_device_pairing_pb2_grpc.py,sha256=hwZfEd_JyPoSmvGNs8oWNFrKQVTNkqIp6Ow_gu8HEBo,900
|
|
14
|
+
quilt_hp/_proto/quilt_hds_pb2.py,sha256=AbyE_UkPDgEj2xKN8974BPttnuqGBrs5rjcNf9u2Mp0,56965
|
|
15
|
+
quilt_hp/_proto/quilt_hds_pb2.pyi,sha256=9AltfIubzJYFUmhmLCGDLXFZs7AtvREvvRn8oAcSoIU,184746
|
|
16
|
+
quilt_hp/_proto/quilt_hds_pb2_grpc.py,sha256=i1A_YrWb1jGTYHouJuwYnUGz-zTVDd8dhpSaRWrdhbM,73293
|
|
17
|
+
quilt_hp/_proto/quilt_notifier_pb2.py,sha256=PTmm2PidkThgoHqLtTTGfBMGOGdQUz9an8l2p_6QvxY,4006
|
|
18
|
+
quilt_hp/_proto/quilt_notifier_pb2.pyi,sha256=hNuiMk94cEHL0vWwSSBeqsGbYqtGu6cgzvQ5yC9wce8,12133
|
|
19
|
+
quilt_hp/_proto/quilt_notifier_pb2_grpc.py,sha256=vnhGBxxpUnk_-RBa_S5RZCXWybUQh7NwLPfArcQ93Ho,3610
|
|
20
|
+
quilt_hp/_proto/quilt_services_pb2.py,sha256=2NFjxOIaeI_AItpF3yvTZY6ygJcI5O031qng_gsg4hg,20644
|
|
21
|
+
quilt_hp/_proto/quilt_services_pb2.pyi,sha256=Sl-0t0YfreU860BADDJAR5gh26Gk756GDsjsdKIFXj0,55650
|
|
22
|
+
quilt_hp/_proto/quilt_services_pb2_grpc.py,sha256=ur45Zvr21aNnx4PssSoopuXQMTcGrUP_3XAAKiY54Ko,49470
|
|
23
|
+
quilt_hp/_proto/quilt_system_pb2.py,sha256=veOHtkK31bcilruYl_jNOxT8AnQpZSvfuP1N3wlnO5o,3428
|
|
24
|
+
quilt_hp/_proto/quilt_system_pb2.pyi,sha256=bnyzhp-oGUGhTQSrjAffADM4wzs5hY_RSrbQ1pnl5JA,5877
|
|
25
|
+
quilt_hp/_proto/quilt_system_pb2_grpc.py,sha256=NzgPa-lCbWxLF_DcDZ_wWM56wjFYW6OFa6cTQWeP2CE,10588
|
|
26
|
+
quilt_hp/cli/__init__.py,sha256=C63yWifzpA0IV7YWDatpAdrhoV8zjqxAKv0xMf09VdM,19
|
|
27
|
+
quilt_hp/cli/main.py,sha256=OYDGixJ0GxCiLE_LCMKbkXW0BFL3iyQdqqypAfFYGxQ,30807
|
|
28
|
+
quilt_hp/cli/settings.py,sha256=yncVe0wuMrhy2E4NTZGBsxc1AAP1afnwCwa3jQmAZnU,4040
|
|
29
|
+
quilt_hp/cli/store.py,sha256=IcVEo7eXicpgBdr0V1S6yGtHnykDKqjc5WpAGZoV0bc,3923
|
|
30
|
+
quilt_hp/cli/tui.py,sha256=3eAg_4Omr0BT7_oO5V2Lh3YaVY3QI4JxzZ68nbekJ6M,100955
|
|
31
|
+
quilt_hp/models/__init__.py,sha256=R3n809_nmAo5dH8JM75NvGTiCvPgpSKQwnUwqXJBPQQ,2077
|
|
32
|
+
quilt_hp/models/comfort.py,sha256=QgszDMYioPk0v6D-TFZrpH75UCPg6zU7vBr0rNHGMGo,1600
|
|
33
|
+
quilt_hp/models/controller.py,sha256=ryeEKdWispuYAXeqn9IHYvMi7ogCjuhLKTnHuMbolpc,5759
|
|
34
|
+
quilt_hp/models/energy.py,sha256=heC0HTHjbMD-znHBMfrUobo4SJbpuDl0a2AHz77nkvM,702
|
|
35
|
+
quilt_hp/models/enums.py,sha256=SlFbYPj58MTTGscFGJQkuYKMUKZLwLYo3S8w3tj2lZk,6436
|
|
36
|
+
quilt_hp/models/indoor_unit.py,sha256=TkocuwtssPo8kYMPJZGc2T8PJIN044DUmFn0t2c53ts,15190
|
|
37
|
+
quilt_hp/models/outdoor_unit.py,sha256=HH6sxr0wE08zgpPiNxfsdBk7x3zUZgcb-_QwX6p1YTc,2861
|
|
38
|
+
quilt_hp/models/qsm.py,sha256=1P9l0rA2OmHT1SpfVe79yIzBryrePcS9MgUauHKxKLg,3788
|
|
39
|
+
quilt_hp/models/schedule.py,sha256=a-ZG4-7jbAipxShaLeHDfj3vVfoOnG9DR3bHfQytews,2741
|
|
40
|
+
quilt_hp/models/sensor.py,sha256=RPIeTZ_F49a9ZEvQtJAOERiGMNqNjxUTPmKuQEb7AHM,3607
|
|
41
|
+
quilt_hp/models/software_update.py,sha256=F1XpQr7vgNXkrNoQk78-vb2skFicPRd7EkJkKDTa8kU,2561
|
|
42
|
+
quilt_hp/models/space.py,sha256=n5AXZddFQgFjxsMRKt-iMuCbIsFdc4XWiAxImzNV9h4,6498
|
|
43
|
+
quilt_hp/models/system.py,sha256=aDCgFhAQsihT9qTFiC_9hjT-YvtmEQgzOGleIIyMJyQ,20453
|
|
44
|
+
quilt_hp/services/__init__.py,sha256=LcsLtnzXqkhaiCIlNNKnmzlY0TAJ3vUwL0nkV8oI1gQ,63
|
|
45
|
+
quilt_hp/services/hds.py,sha256=xPlYvhvHYKUCBTl48B83an8aJl_3ZT4yg6YJFBsjhYw,19781
|
|
46
|
+
quilt_hp/services/streaming.py,sha256=boga8QGacc-mxEfSePvLDXeeKYPHA_lECot21SG8J-w,22707
|
|
47
|
+
quilt_hp/services/system.py,sha256=WIXEfCcifhXlwd2yr8Uc0Qom98NatNrNm1wwWvYo9WU,3203
|
|
48
|
+
quilt_hp/services/user.py,sha256=KpRD5V7aZqMXZ0CHGmeZfNl9vLA0bZBnCSNX_XCBlxo,4771
|
|
49
|
+
quilt_hp_python-0.1.1.dist-info/METADATA,sha256=d2y3x8Fmu47GjZiFEmcemQaGgRziMFNbiHf6L4E43q0,5547
|
|
50
|
+
quilt_hp_python-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
|
|
51
|
+
quilt_hp_python-0.1.1.dist-info/entry_points.txt,sha256=9kOMlIRUGPx1WCxpM-QG4YPXnhee5DBlmWWaunlwrNk,48
|
|
52
|
+
quilt_hp_python-0.1.1.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
|
|
53
|
+
quilt_hp_python-0.1.1.dist-info/RECORD,,
|