piphi-runtime-kit-python 0.9.3__py3-none-any.whl → 0.10.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.
@@ -33,6 +33,11 @@ from .camera import (
33
33
  CameraSourceResolver,
34
34
  CameraWebRtcOffer,
35
35
  )
36
+ from .onboarding import (
37
+ OnboardingDeclaration,
38
+ OnboardingMode,
39
+ validate_onboarding_declaration,
40
+ )
36
41
  from .runtime.auth import (
37
42
  RUNTIME_CONTAINER_ID_HEADER_NAME,
38
43
  RUNTIME_INTERNAL_TOKEN_HEADER_NAME,
@@ -128,6 +133,7 @@ from .runtime.mqtt import (
128
133
  build_source_status_topic,
129
134
  build_source_topic_root,
130
135
  )
136
+ from .runtime.network import RUNTIME_PORT_ENV_NAME, runtime_port
131
137
  from .runtime.registry import RuntimeRegistry
132
138
  from .runtime.starter import (
133
139
  RuntimeStarter,
@@ -189,6 +195,7 @@ __all__ = [
189
195
  "RUNTIME_CONFIG_SNAPSHOT_PATH_ENV_NAME",
190
196
  "RUNTIME_CONTAINER_ID_HEADER_NAME",
191
197
  "RUNTIME_INTERNAL_TOKEN_HEADER_NAME",
198
+ "RUNTIME_PORT_ENV_NAME",
192
199
  "AutomationActionDefinition",
193
200
  "AutomationActionRequest",
194
201
  "AutomationActionResult",
@@ -233,6 +240,8 @@ __all__ = [
233
240
  "IntegrationEventRequest",
234
241
  "MqttBrokerConfig",
235
242
  "MqttJsonClient",
243
+ "OnboardingDeclaration",
244
+ "OnboardingMode",
236
245
  "RuntimeAuthContext",
237
246
  "RuntimeAuthHeaders",
238
247
  "RuntimeConfig",
@@ -311,10 +320,12 @@ __all__ = [
311
320
  "resolve_device_id",
312
321
  "resolve_runtime_config_snapshot_path",
313
322
  "runtime_lifespan",
323
+ "runtime_port",
314
324
  "schedule_event_delivery",
315
325
  "schedule_telemetry_delivery",
316
326
  "shutdown_background_tasks",
317
327
  "track_background_task",
318
328
  "validate_typed_config",
319
329
  "validate_typed_configs",
330
+ "validate_onboarding_declaration",
320
331
  ]
@@ -0,0 +1,34 @@
1
+ """Typed homeowner onboarding declarations for PiPhi manifests."""
2
+
3
+ from enum import Enum
4
+ from typing import Any, Mapping
5
+
6
+ from pydantic import BaseModel, ConfigDict
7
+
8
+
9
+ class OnboardingMode(str, Enum):
10
+ """The first homeowner-facing action after a package is installed."""
11
+
12
+ MANUAL = "manual"
13
+ DISCOVERY = "discovery"
14
+ ACCOUNT = "account"
15
+ SERVICE = "service"
16
+ NONE = "none"
17
+
18
+
19
+ class OnboardingDeclaration(BaseModel):
20
+ """Manifest declaration consumed by PiPhi Core's setup planner."""
21
+
22
+ model_config = ConfigDict(extra="forbid")
23
+
24
+ mode: OnboardingMode
25
+
26
+
27
+ def validate_onboarding_declaration(
28
+ value: OnboardingDeclaration | Mapping[str, Any],
29
+ ) -> OnboardingDeclaration:
30
+ """Validate and normalize a manifest ``onboarding`` object."""
31
+
32
+ if isinstance(value, OnboardingDeclaration):
33
+ return value
34
+ return OnboardingDeclaration.model_validate(dict(value))
@@ -0,0 +1,33 @@
1
+ """Managed runtime network configuration helpers."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ from collections.abc import Mapping
7
+
8
+ RUNTIME_PORT_ENV_NAME = "PORT"
9
+
10
+
11
+ def runtime_port(default: int, *, environ: Mapping[str, str] | None = None) -> int:
12
+ """Return the Core-assigned listener port, or ``default`` outside Core.
13
+
14
+ A present but invalid ``PORT`` is a contract error. Silently falling back in
15
+ that case can bind a managed runtime to a port owned by another service.
16
+ """
17
+
18
+ _validate_port(default, source="default")
19
+ environment = os.environ if environ is None else environ
20
+ raw = environment.get(RUNTIME_PORT_ENV_NAME)
21
+ if raw is None:
22
+ return default
23
+ try:
24
+ port = int(raw)
25
+ except ValueError as exc:
26
+ raise ValueError("PORT must be an integer between 1 and 65535") from exc
27
+ return _validate_port(port, source=RUNTIME_PORT_ENV_NAME)
28
+
29
+
30
+ def _validate_port(port: int, *, source: str) -> int:
31
+ if isinstance(port, bool) or not isinstance(port, int) or not 1 <= port <= 65535:
32
+ raise ValueError(f"{source} must be an integer between 1 and 65535")
33
+ return port
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: piphi-runtime-kit-python
3
- Version: 0.9.3
3
+ Version: 0.10.1
4
4
  Summary: PiPhi Network runtime integration helpers
5
5
  Keywords: piphi,runtime,integration,iot
6
6
  Author-Email: KelvinSan <support@piphi.network>
@@ -31,12 +31,31 @@ Description-Content-Type: text/markdown
31
31
 
32
32
  Small Python helpers for building PiPhi runtime integrations.
33
33
 
34
+ ## Managed listener port
35
+
36
+ Core assigns the primary listener through `PORT`. Use `runtime_port(default)` when starting the server. The default is only for unmanaged local development; an invalid managed assignment raises an error rather than risking a collision.
37
+
34
38
  This package is intentionally thin. It removes repetitive PiPhi runtime
35
39
  plumbing without hiding the HTTP contract behind a large framework. The goal
36
40
  is to help developers move faster while still understanding what their runtime
37
41
  is doing.
38
42
 
39
- Version `0.7.1` is the current documented baseline.
43
+ Version `0.10.0` is the current documented baseline.
44
+
45
+ ## Onboarding declarations
46
+
47
+ Runtime discovery and homeowner onboarding are separate contracts. Validate a
48
+ manifest's explicit first-use declaration without inferring it from `/discover`:
49
+
50
+ ```python
51
+ from piphi_runtime_kit_python import OnboardingMode, validate_onboarding_declaration
52
+
53
+ onboarding = validate_onboarding_declaration({"mode": OnboardingMode.MANUAL})
54
+ ```
55
+
56
+ The supported modes are `manual`, `discovery`, `account`, `service`, and
57
+ `none`. Runtime strategies such as `passive` or `mdns` belong in runtime
58
+ discovery metadata, not in `onboarding.mode`.
40
59
 
41
60
  > New to PiPhi? Start with [First 15 Minutes](#first-15-minutes), then read [The Golden Path](#the-golden-path), then compare your code to the example app.
42
61
 
@@ -1,13 +1,14 @@
1
- piphi_runtime_kit_python-0.9.3.dist-info/METADATA,sha256=TD_WPbfXv7OHX-XKS1On4MLFbi_qcpugLjNvZYcCur0,37596
2
- piphi_runtime_kit_python-0.9.3.dist-info/WHEEL,sha256=IuIk3wbaEnFH1cx75iM2R1CmliRI3dFLXTbRakgvgFQ,90
3
- piphi_runtime_kit_python-0.9.3.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
4
- piphi_runtime_kit_python-0.9.3.dist-info/licenses/LICENSE,sha256=pS6szQI4X7qAin1ODdoDp-XwZvsFy6ZZ28-JAwGHgzo,1070
5
- piphi_runtime_kit_python/__init__.py,sha256=Fzsg1KKJFp54Jif7eG7nwCHoJNMIJbus8wFTMkyHQnk,9286
1
+ piphi_runtime_kit_python-0.10.1.dist-info/METADATA,sha256=iMTDMhsDbFdtEw7GhGh50Rh2xkpqp8OMSSE2caCHS4o,38421
2
+ piphi_runtime_kit_python-0.10.1.dist-info/WHEEL,sha256=IuIk3wbaEnFH1cx75iM2R1CmliRI3dFLXTbRakgvgFQ,90
3
+ piphi_runtime_kit_python-0.10.1.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
4
+ piphi_runtime_kit_python-0.10.1.dist-info/licenses/LICENSE,sha256=pS6szQI4X7qAin1ODdoDp-XwZvsFy6ZZ28-JAwGHgzo,1070
5
+ piphi_runtime_kit_python/__init__.py,sha256=fNMpSEmmNfLk1eSjVHfIb0p3HPhbyHTvN0qXrczRbYI,9602
6
6
  piphi_runtime_kit_python/adapters/__init__.py,sha256=3jBhPZSBN3Qo7MKHlxAol2jPU3cK23BXHR2oTlircsw,361
7
7
  piphi_runtime_kit_python/adapters/fastapi.py,sha256=4BP_Ewm2K4NmyUvhgOzCUH7-fN3JwQFRwSUVxrHptQI,3099
8
8
  piphi_runtime_kit_python/automations.py,sha256=mDK62mo0hbsXGU48zEp-W7Q9MSzO9CsjnUEf75X6Yvw,20545
9
9
  piphi_runtime_kit_python/camera.py,sha256=37LCMzRvP1NxCWXa4Z7WmWWRLsw92MM3CZLNscTdMe8,9093
10
10
  piphi_runtime_kit_python/fastapi.py,sha256=xvHU19-CVDPKjmXW6nW72mpdbJEOLZzT8Twal7lCCkc,453
11
+ piphi_runtime_kit_python/onboarding.py,sha256=ZnCmQxb6hWp6L1RxbrqpziScnW9BONhXKapOiFu9kYo,898
11
12
  piphi_runtime_kit_python/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
12
13
  piphi_runtime_kit_python/runtime/__init__.py,sha256=giSFLVRYGZU8icAWAgThevj59oTAXRoKTe5zo3fEeiA,4081
13
14
  piphi_runtime_kit_python/runtime/auth.py,sha256=SDfQ1zSWR5zg3fGYMpr0Az9zkvDwgrrtcQVtyeFU0NI,4728
@@ -22,6 +23,7 @@ piphi_runtime_kit_python/runtime/health.py,sha256=D5aGvsuIHAFCEq6tw6o0qOuRhiC-Nx
22
23
  piphi_runtime_kit_python/runtime/identity.py,sha256=RyTIF8ZA7Kt-xmloYG9J6GuDZ_UcdPPoSA1TEqC6YKU,5098
23
24
  piphi_runtime_kit_python/runtime/lifespan.py,sha256=fHBwM9-2OskRwRIklK1PG0f_Y77guZoL1qJ7Y4jks7g,3037
24
25
  piphi_runtime_kit_python/runtime/mqtt.py,sha256=QC6C017stmmjD89tMFvrRyazpANuIBCN3KrYodjiTrE,6178
26
+ piphi_runtime_kit_python/runtime/network.py,sha256=pWQg_9VjprrDhQ5iSo7PhAW1kETFWpe7zxyj6zMg5jE,1138
25
27
  piphi_runtime_kit_python/runtime/registry.py,sha256=nO7qoc0JVBjUhqsvAubMN0DH5hNcZmWtnVY0l-G5KN8,3418
26
28
  piphi_runtime_kit_python/runtime/starter.py,sha256=0D54HeKHK1veb1F-DfgC46UkUp6B0DtJS97ga_EslJ8,7043
27
29
  piphi_runtime_kit_python/runtime/state.py,sha256=OIwVxAzX2ErsZ2XdrWlIP5r3GHHub5y9PDtoqNDlwkQ,952
@@ -29,4 +31,4 @@ piphi_runtime_kit_python/runtime/state_service.py,sha256=bWxQD9JJRJsOA2k1S_TttFx
29
31
  piphi_runtime_kit_python/runtime/tasks.py,sha256=E9WoE75NQiJp3buJYexysl3NuP8HJHJ3KfaGVKLdiw0,3238
30
32
  piphi_runtime_kit_python/runtime/telemetry.py,sha256=b08Faq0CBrTqc5MCDjRUnX0KVT-MN8n4Le_FE-b2BVo,6719
31
33
  piphi_runtime_kit_python/schemas.py,sha256=eXb_WEEGREGTRWkhShaof9N64vlrsHhVKAJECSia_to,10435
32
- piphi_runtime_kit_python-0.9.3.dist-info/RECORD,,
34
+ piphi_runtime_kit_python-0.10.1.dist-info/RECORD,,