uns-kit 0.1.2__tar.gz → 0.1.3__tar.gz

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.
Files changed (62) hide show
  1. {uns_kit-0.1.2 → uns_kit-0.1.3}/PKG-INFO +67 -1
  2. {uns_kit-0.1.2 → uns_kit-0.1.3}/README.md +269 -203
  3. {uns_kit-0.1.2 → uns_kit-0.1.3}/pyproject.toml +42 -42
  4. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/api/proxy.py +638 -638
  5. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/cli.py +1224 -1224
  6. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/client.py +350 -350
  7. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/config_file.py +58 -58
  8. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/datahub_client.py +117 -117
  9. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/events.py +23 -23
  10. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/logger.py +215 -215
  11. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/packet.py +302 -302
  12. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/proxy.py +87 -87
  13. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/proxy_process.py +315 -315
  14. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/runtime_metadata.py +45 -45
  15. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/secret_resolver.py +482 -482
  16. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/status_monitor.py +88 -88
  17. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/topic_builder.py +71 -71
  18. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/topic_matcher.py +18 -18
  19. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/uns_mqtt_proxy.py +292 -258
  20. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/uns_path.py +17 -17
  21. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/cron/proxy.py +137 -137
  22. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/service_bundle.py +373 -373
  23. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/azure-pipelines.yml +21 -21
  24. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/cron/src/cron_example.py +61 -61
  25. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/default/.gitignore +47 -47
  26. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/default/README.md +52 -52
  27. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/default/pyproject.toml +14 -14
  28. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/default/runtime.json +3 -3
  29. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/vscode/extensions.json +6 -6
  30. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/vscode/launch.json +13 -13
  31. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/vscode/settings.json +5 -5
  32. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/workspace/workspace.json +10 -10
  33. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/version.py +19 -19
  34. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/__init__.py +0 -0
  35. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/api/__init__.py +0 -0
  36. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/api/data_catalog.py +0 -0
  37. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/api/event_routing.py +0 -0
  38. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/api/interfaces.py +0 -0
  39. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/__init__.py +0 -0
  40. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/auth_client.py +0 -0
  41. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/config_schema.py +0 -0
  42. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/core/secure_store.py +0 -0
  43. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/cron/__init__.py +0 -0
  44. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/database/__init__.py +0 -0
  45. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/database/client.py +0 -0
  46. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/database/params.py +0 -0
  47. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/database/schema.py +0 -0
  48. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/database/sql.py +0 -0
  49. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/database/types.py +0 -0
  50. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/api/src/api_routes.py +0 -0
  51. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/api/src/main.py +0 -0
  52. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/data-offer/src/api_routes.py +0 -0
  53. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/data-offer/src/data_offers/__init__.py +0 -0
  54. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/data-offer/src/data_offers/demo_coils.py +0 -0
  55. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/data-offer/src/data_offers/demo_export.py +0 -0
  56. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/data-offer/src/data_offers/sql/demo_coils.sql +0 -0
  57. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/data-offer/src/data_offers/sql/demo_export.sql +0 -0
  58. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/data-offer/src/main.py +0 -0
  59. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/default/package.json +0 -0
  60. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/default/src/config/project_config_extension.example.py +0 -0
  61. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/default/src/config/project_config_extension.py +0 -0
  62. {uns_kit-0.1.2 → uns_kit-0.1.3}/src/uns_kit/templates/default/src/main.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: uns-kit
3
- Version: 0.1.2
3
+ Version: 0.1.3
4
4
  Summary: Lightweight Python UNS MQTT client (pub/sub + infra topics)
5
5
  License: MIT
6
6
  Author: Aljoša Vister
@@ -135,6 +135,72 @@ await proxy.publish_mqtt_message({
135
135
  })
136
136
  ```
137
137
 
138
+ ### Counter attributes
139
+
140
+ Publish cumulative counters as raw counter state. Do not use producer-side
141
+ delta modes for new code; `MessageMode.DELTA`, `MessageMode.BOTH`, and gRPC
142
+ `value_is_cumulative` are deprecated because producer memory is lost across
143
+ service restarts. Datahub history APIs should calculate delta/rate from
144
+ persisted rows.
145
+
146
+ For a `Data` attribute, mark the series directly:
147
+
148
+ ```python
149
+ await proxy.publish_mqtt_message({
150
+ "topic": "raw/data/",
151
+ "asset": "line-1",
152
+ "objectType": "energy-resource",
153
+ "objectId": "main",
154
+ "attributes": {
155
+ "attribute": "active-energy-total",
156
+ "description": "Cumulative active energy counter",
157
+ "valueType": "number",
158
+ "presentationKind": "counter",
159
+ "defaultAggregation": "last",
160
+ "counterResetPolicy": "new-value",
161
+ "data": {
162
+ "time": "2026-06-02T12:00:00.000Z",
163
+ "value": 12345.6,
164
+ "uom": "kWh",
165
+ "dataGroup": "metering",
166
+ },
167
+ },
168
+ })
169
+ ```
170
+
171
+ For a `Table` attribute, keep the table as the source row and mark chartable
172
+ counter columns with `tableColumns`:
173
+
174
+ ```python
175
+ await proxy.publish_mqtt_message({
176
+ "topic": "raw/data/",
177
+ "asset": "line-1",
178
+ "objectType": "energy-resource",
179
+ "objectId": "main",
180
+ "attributes": {
181
+ "attribute": "measurements",
182
+ "description": "Metering table",
183
+ "tableColumns": [
184
+ {
185
+ "name": "active_energy_total",
186
+ "valueType": "number",
187
+ "presentationKind": "counter",
188
+ "defaultAggregation": "last",
189
+ "counterResetPolicy": "new-value",
190
+ },
191
+ ],
192
+ "table": {
193
+ "time": "2026-06-02T12:00:00.000Z",
194
+ "dataGroup": "metering",
195
+ "columns": [
196
+ {"name": "active_energy_total", "type": "double", "value": 12345.6, "uom": "kWh"},
197
+ {"name": "power", "type": "double", "value": 42.1, "uom": "kW"},
198
+ ],
199
+ },
200
+ },
201
+ })
202
+ ```
203
+
138
204
  ### Datahub client (last value + history)
139
205
 
140
206
  `UnsClient` provides a minimal REST client for the UNS Datahub API, including batch last-value, single-topic catch-all history, and batch range endpoints. For service-to-service access, prefer passing a long-lived service token directly. Use `AuthClient` only when you need user-style login/refresh from `config.json`.
@@ -7,20 +7,20 @@ Python UNS SDK for runtime services, API/service exposure, and Datahub access. P
7
7
  - Minimal UNS packet builder/parser (data/table) aligned with TS core.
8
8
  - Service/API proxy support with Swagger and endpoint registry topics.
9
9
  - Datahub client support for last-value, single-topic history, and batch range queries.
10
-
11
- ## Install (editable)
12
- ```bash
13
- cd packages/uns-py
14
- poetry install
15
- ```
16
-
17
- ## CLI
18
- After `poetry install`, an `uns-kit-py` command is available (renamed to avoid clashing with the Node CLI):
19
- ```bash
20
- poetry run uns-kit-py publish --host localhost:1883 --topic raw/data/ --value 1
21
- poetry run uns-kit-py subscribe --host localhost:1883 --topic 'uns-infra/#'
22
- ```
23
-
10
+
11
+ ## Install (editable)
12
+ ```bash
13
+ cd packages/uns-py
14
+ poetry install
15
+ ```
16
+
17
+ ## CLI
18
+ After `poetry install`, an `uns-kit-py` command is available (renamed to avoid clashing with the Node CLI):
19
+ ```bash
20
+ poetry run uns-kit-py publish --host localhost:1883 --topic raw/data/ --value 1
21
+ poetry run uns-kit-py subscribe --host localhost:1883 --topic 'uns-infra/#'
22
+ ```
23
+
24
24
  Feature-specific dependencies are exposed as optional extras:
25
25
  ```bash
26
26
  pip install "uns-kit[api]"
@@ -42,72 +42,138 @@ Public namespaces are organized by capability:
42
42
  - `uns_kit.api` - API proxy and data-catalog/service-api helpers
43
43
  - `uns_kit.cron` - cron proxy
44
44
  - `uns_kit.database` - config-driven database access
45
-
46
- ## Quick start
47
- ```python
48
- import asyncio
49
- from pathlib import Path
45
+
46
+ ## Quick start
47
+ ```python
48
+ import asyncio
49
+ from pathlib import Path
50
50
  from uns_kit.core import ConfigFile, UnsPacket, UnsProcessParameters, UnsProxyProcess
51
-
52
- async def main():
53
- config = ConfigFile.load_config(Path("config.json"))
54
- infra = config["infra"]
55
- uns = config["uns"]
56
- process = UnsProxyProcess(
57
- infra["host"],
58
- UnsProcessParameters(process_name=uns.get("processName", "uns-process")),
59
- )
60
- await process.start()
61
- mqtt = await process.create_mqtt_proxy("py")
62
-
63
- # Subscribe
64
- async with mqtt.client.messages("uns-infra/#") as messages:
65
- await mqtt.publish_packet("raw/data/", UnsPacket.data(value=1, uom="count"))
66
- msg = await messages.__anext__()
67
- print(msg.topic, msg.payload.decode())
68
-
69
- await mqtt.close()
70
- await process.stop()
71
-
72
- asyncio.run(main())
73
- ```
74
-
75
- ### Recommended publishing pattern
76
- If your service publishes UNS topics, prefer:
77
- - `UnsProxyProcess`
78
- - `await process.create_mqtt_proxy(...)`
79
- - `await proxy.publish_mqtt_message(...)`
80
-
81
- That is the default application pattern for generated Python services and the path that also maintains the retained `.../topics` registry used for discovery. Direct `UnsMqttClient` publishing is lower-level and should not be the default service pattern unless you have a specific reason.
82
-
83
- ### Validity / Liveliness
84
-
85
- UNS attributes can declare how the controller decides whether they are live or stale; in most apps this is primarily used to drive UI liveliness/activity indicators. In app-level modeling we use two modes only:
86
-
87
- - `interval`: continuously refreshed values (stale after ~2× `expectedIntervalMs`)
88
- - `lifecycle`: event-driven activity that stays active until a defined end value (`lifecycleEndValue`)
89
-
90
- ```python
91
- await proxy.publish_mqtt_message({
92
- "topic": "raw/data/",
93
- "asset": "line-1",
94
- "objectType": "motor",
95
- "objectId": "main",
96
- "attributes": {
97
- "attribute": "status",
98
- "data": {"time": "2025-01-01T00:00:00Z", "value": "RUNNING"},
99
- "validityMode": "lifecycle",
100
- "lifecycleEndValue": "STOPPED",
101
- },
102
- })
103
- ```
104
-
51
+
52
+ async def main():
53
+ config = ConfigFile.load_config(Path("config.json"))
54
+ infra = config["infra"]
55
+ uns = config["uns"]
56
+ process = UnsProxyProcess(
57
+ infra["host"],
58
+ UnsProcessParameters(process_name=uns.get("processName", "uns-process")),
59
+ )
60
+ await process.start()
61
+ mqtt = await process.create_mqtt_proxy("py")
62
+
63
+ # Subscribe
64
+ async with mqtt.client.messages("uns-infra/#") as messages:
65
+ await mqtt.publish_packet("raw/data/", UnsPacket.data(value=1, uom="count"))
66
+ msg = await messages.__anext__()
67
+ print(msg.topic, msg.payload.decode())
68
+
69
+ await mqtt.close()
70
+ await process.stop()
71
+
72
+ asyncio.run(main())
73
+ ```
74
+
75
+ ### Recommended publishing pattern
76
+ If your service publishes UNS topics, prefer:
77
+ - `UnsProxyProcess`
78
+ - `await process.create_mqtt_proxy(...)`
79
+ - `await proxy.publish_mqtt_message(...)`
80
+
81
+ That is the default application pattern for generated Python services and the path that also maintains the retained `.../topics` registry used for discovery. Direct `UnsMqttClient` publishing is lower-level and should not be the default service pattern unless you have a specific reason.
82
+
83
+ ### Validity / Liveliness
84
+
85
+ UNS attributes can declare how the controller decides whether they are live or stale; in most apps this is primarily used to drive UI liveliness/activity indicators. In app-level modeling we use two modes only:
86
+
87
+ - `interval`: continuously refreshed values (stale after ~2× `expectedIntervalMs`)
88
+ - `lifecycle`: event-driven activity that stays active until a defined end value (`lifecycleEndValue`)
89
+
90
+ ```python
91
+ await proxy.publish_mqtt_message({
92
+ "topic": "raw/data/",
93
+ "asset": "line-1",
94
+ "objectType": "motor",
95
+ "objectId": "main",
96
+ "attributes": {
97
+ "attribute": "status",
98
+ "data": {"time": "2025-01-01T00:00:00Z", "value": "RUNNING"},
99
+ "validityMode": "lifecycle",
100
+ "lifecycleEndValue": "STOPPED",
101
+ },
102
+ })
103
+ ```
104
+
105
+ ### Counter attributes
106
+
107
+ Publish cumulative counters as raw counter state. Do not use producer-side
108
+ delta modes for new code; `MessageMode.DELTA`, `MessageMode.BOTH`, and gRPC
109
+ `value_is_cumulative` are deprecated because producer memory is lost across
110
+ service restarts. Datahub history APIs should calculate delta/rate from
111
+ persisted rows.
112
+
113
+ For a `Data` attribute, mark the series directly:
114
+
115
+ ```python
116
+ await proxy.publish_mqtt_message({
117
+ "topic": "raw/data/",
118
+ "asset": "line-1",
119
+ "objectType": "energy-resource",
120
+ "objectId": "main",
121
+ "attributes": {
122
+ "attribute": "active-energy-total",
123
+ "description": "Cumulative active energy counter",
124
+ "valueType": "number",
125
+ "presentationKind": "counter",
126
+ "defaultAggregation": "last",
127
+ "counterResetPolicy": "new-value",
128
+ "data": {
129
+ "time": "2026-06-02T12:00:00.000Z",
130
+ "value": 12345.6,
131
+ "uom": "kWh",
132
+ "dataGroup": "metering",
133
+ },
134
+ },
135
+ })
136
+ ```
137
+
138
+ For a `Table` attribute, keep the table as the source row and mark chartable
139
+ counter columns with `tableColumns`:
140
+
141
+ ```python
142
+ await proxy.publish_mqtt_message({
143
+ "topic": "raw/data/",
144
+ "asset": "line-1",
145
+ "objectType": "energy-resource",
146
+ "objectId": "main",
147
+ "attributes": {
148
+ "attribute": "measurements",
149
+ "description": "Metering table",
150
+ "tableColumns": [
151
+ {
152
+ "name": "active_energy_total",
153
+ "valueType": "number",
154
+ "presentationKind": "counter",
155
+ "defaultAggregation": "last",
156
+ "counterResetPolicy": "new-value",
157
+ },
158
+ ],
159
+ "table": {
160
+ "time": "2026-06-02T12:00:00.000Z",
161
+ "dataGroup": "metering",
162
+ "columns": [
163
+ {"name": "active_energy_total", "type": "double", "value": 12345.6, "uom": "kWh"},
164
+ {"name": "power", "type": "double", "value": 42.1, "uom": "kW"},
165
+ ],
166
+ },
167
+ },
168
+ })
169
+ ```
170
+
105
171
  ### Datahub client (last value + history)
106
-
172
+
107
173
  `UnsClient` provides a minimal REST client for the UNS Datahub API, including batch last-value, single-topic catch-all history, and batch range endpoints. For service-to-service access, prefer passing a long-lived service token directly. Use `AuthClient` only when you need user-style login/refresh from `config.json`.
108
-
109
- ```python
110
- import pandas as pd
174
+
175
+ ```python
176
+ import pandas as pd
111
177
  from pathlib import Path
112
178
  from uns_kit.core import ConfigFile, UnsClient
113
179
  import io
@@ -118,44 +184,44 @@ client = UnsClient(
118
184
  api_base_path="/api",
119
185
  token=cfg["uns"].get("token"),
120
186
  )
121
-
122
- values = client.last_value([
123
- "raw/data/line-1/motor/main/temperature",
124
- "raw/data/line-1/motor/main/status",
125
- ])
126
- print(values)
127
-
128
- history = client.get_attribute_data(
129
- "sij/acroni/vv/hrm-furnace/equipment/pusher/output-quantity",
130
- **{
131
- "from": "2026-05-07T11:17:01.157Z",
132
- "to": "2026-05-07T11:22:01.157Z",
133
- "table": "uns_sij_hrm_furnace_data",
134
- "aggregate": "last",
135
- "dedupe": False,
136
- }
137
- )
138
- print(history.records())
139
-
140
- custom_data = client.get_data(
141
- "/projects/project-name/path-to-data/data",
142
- params={"fromDate": "20260325"},
143
- )
144
- print(custom_data.json())
145
-
146
- df = pd.read_parquet(io.BytesIO(data.content))
147
- print(df)
148
-
187
+
188
+ values = client.last_value([
189
+ "raw/data/line-1/motor/main/temperature",
190
+ "raw/data/line-1/motor/main/status",
191
+ ])
192
+ print(values)
193
+
194
+ history = client.get_attribute_data(
195
+ "sij/acroni/vv/hrm-furnace/equipment/pusher/output-quantity",
196
+ **{
197
+ "from": "2026-05-07T11:17:01.157Z",
198
+ "to": "2026-05-07T11:22:01.157Z",
199
+ "table": "uns_sij_hrm_furnace_data",
200
+ "aggregate": "last",
201
+ "dedupe": False,
202
+ }
203
+ )
204
+ print(history.records())
205
+
206
+ custom_data = client.get_data(
207
+ "/projects/project-name/path-to-data/data",
208
+ params={"fromDate": "20260325"},
209
+ )
210
+ print(custom_data.json())
211
+
212
+ df = pd.read_parquet(io.BytesIO(data.content))
213
+ print(df)
214
+
149
215
  batch_history = client.history(
150
- [
151
- "sij/acroni/vv/hrm-furnace/equipment/zone-1/temperature",
152
- "sij/acroni/vv/hrm-furnace/equipment/zone-2/temperature",
153
- ],
154
- **{
155
- "from": "2026-04-09T06:00:00Z",
156
- "to": "2026-04-09T07:00:00Z",
157
- "limit": 500,
158
- }
216
+ [
217
+ "sij/acroni/vv/hrm-furnace/equipment/zone-1/temperature",
218
+ "sij/acroni/vv/hrm-furnace/equipment/zone-2/temperature",
219
+ ],
220
+ **{
221
+ "from": "2026-04-09T06:00:00Z",
222
+ "to": "2026-04-09T07:00:00Z",
223
+ "limit": 500,
224
+ }
159
225
  )
160
226
  print(batch_history.by_topic)
161
227
  ```
@@ -173,16 +239,16 @@ client = UnsClient(
173
239
  ```
174
240
 
175
241
  For larger service API and data-offer examples, use `configure-data-offer`. The scaffold uses `await register_api_catalog(...)` in `src/main.py`, while `src/api_routes.py` holds the `service_apis` and `data_offer_sources` definitions together with their handlers.
176
-
177
- ## Config placeholders (env + Infisical)
178
- `uns-py` now resolves config placeholders in the same style as `uns-core`.
179
- For Infisical placeholders, install the optional extra:
180
- ```bash
181
- pip install "uns-kit[infisical]"
182
- ```
183
-
184
- Example `config.json`:
185
- ```json
242
+
243
+ ## Config placeholders (env + Infisical)
244
+ `uns-py` now resolves config placeholders in the same style as `uns-core`.
245
+ For Infisical placeholders, install the optional extra:
246
+ ```bash
247
+ pip install "uns-kit[infisical]"
248
+ ```
249
+
250
+ Example `config.json`:
251
+ ```json
186
252
  {
187
253
  "uns": {
188
254
  "graphql": "https://example/graphql",
@@ -191,55 +257,55 @@ Example `config.json`:
191
257
  "password": { "provider": "env", "key": "UNS_PASSWORD" },
192
258
  "processName": "my-process"
193
259
  },
194
- "infra": {
195
- "host": "mqtt.example.local",
196
- "port": 1883,
197
- "username": "mqtt-user",
198
- "password": {
199
- "provider": "infisical",
200
- "path": "/mqtt",
201
- "key": "password",
202
- "environment": "dev"
203
- }
204
- }
205
- }
206
- ```
207
-
208
- Load resolved config with cache semantics:
209
- ```python
260
+ "infra": {
261
+ "host": "mqtt.example.local",
262
+ "port": 1883,
263
+ "username": "mqtt-user",
264
+ "password": {
265
+ "provider": "infisical",
266
+ "path": "/mqtt",
267
+ "key": "password",
268
+ "environment": "dev"
269
+ }
270
+ }
271
+ }
272
+ ```
273
+
274
+ Load resolved config with cache semantics:
275
+ ```python
210
276
  from uns_kit.core import ConfigFile, InfisicalResolverOptions, SecretResolverOptions
211
-
212
- resolved = ConfigFile.load_config(
213
- "config.json",
214
- SecretResolverOptions(
215
- infisical=InfisicalResolverOptions(
216
- environment="dev",
217
- project_id="your-project-id"
218
- )
219
- )
220
- )
221
- ```
222
-
223
- ## Extend the config schema
224
- Edit `src/config/project_config_extension.py` inside your Python project and run:
225
-
226
- ```bash
227
- poetry run uns-kit-py generate-config-schema
228
- ```
229
-
230
- This regenerates `config.schema.json` so editors can validate `config.json`, flag missing required fields, and offer completions for project-specific sections.
231
-
232
- ### Resilient subscriber
233
- ```python
234
- async for msg in client.resilient_messages("uns-infra/#"):
235
- print(msg.topic, msg.payload.decode())
236
- ```
237
-
238
- ### Examples
239
- - `examples/publish.py` — publish 5 data packets.
240
- - `examples/subscribe.py` — resilient subscription with auto-reconnect.
241
- - `examples/load_test.py` — interactive publish burst.
242
-
277
+
278
+ resolved = ConfigFile.load_config(
279
+ "config.json",
280
+ SecretResolverOptions(
281
+ infisical=InfisicalResolverOptions(
282
+ environment="dev",
283
+ project_id="your-project-id"
284
+ )
285
+ )
286
+ )
287
+ ```
288
+
289
+ ## Extend the config schema
290
+ Edit `src/config/project_config_extension.py` inside your Python project and run:
291
+
292
+ ```bash
293
+ poetry run uns-kit-py generate-config-schema
294
+ ```
295
+
296
+ This regenerates `config.schema.json` so editors can validate `config.json`, flag missing required fields, and offer completions for project-specific sections.
297
+
298
+ ### Resilient subscriber
299
+ ```python
300
+ async for msg in client.resilient_messages("uns-infra/#"):
301
+ print(msg.topic, msg.payload.decode())
302
+ ```
303
+
304
+ ### Examples
305
+ - `examples/publish.py` — publish 5 data packets.
306
+ - `examples/subscribe.py` — resilient subscription with auto-reconnect.
307
+ - `examples/load_test.py` — interactive publish burst.
308
+
243
309
  ### Create a new project
244
310
  ```bash
245
311
  uns-kit-py create my-uns-py-app
@@ -268,37 +334,37 @@ poetry run uns-kit-py configure-data-offer .
268
334
  The scaffold includes the same two offer styles as the TypeScript template:
269
335
  - one JSON offer (`demo_coils`)
270
336
  - one Parquet export offer (`demo_export`)
271
-
272
- ### Create a new project from a service bundle
273
- ```bash
274
- uns-kit-py create --bundle ./service.bundle.json
275
- uns-kit-py create --bundle ./service.bundle.json --dest ./my-dir
276
- uns-kit-py create --bundle ./service.bundle.json --dest . --allow-existing
277
- ```
278
-
279
- Bundle-driven create uses `service.bundle.json` as the source of truth. The Python CLI:
280
- - scaffolds the base Python app from the existing default template
281
- - copies the original bundle into the project root as `service.bundle.json`
282
- - generates `SERVICE_SPEC.md` and `AGENTS.md`
283
- - applies supported bundle features such as `vscode` and `devops`
284
-
285
- When `--bundle` is used, the default destination is `./<metadata.name>`. The Python CLI only accepts bundles with `scaffold.stack = "python"` and currently supports `scaffold.template = "default"` for this MVP. If the bundle targets TypeScript instead, use `uns-kit create --bundle ...`.
286
-
287
- ### Create a sandbox app in this repo
288
- From the monorepo root:
289
- ```bash
290
- pnpm run py:sandbox
291
- ```
292
- This creates `sandbox-app-py/` using the default Python template.
293
- When created inside this monorepo, `pyproject.toml` is automatically set to use local editable `uns-kit`:
294
- `uns-kit = { path = "../packages/uns-py", develop = true }`.
295
-
296
- ## Notes
297
- - Default QoS is 0.
298
- - Instance status topics are published every 10 seconds; stats every 60 seconds.
299
- - Packet shape mirrors the TypeScript core: `{"version":"1.3.0","message":{"data":{...}},"sequenceId":0}`.
300
- - Windows: the library sets `WindowsSelectorEventLoopPolicy()` to avoid `add_reader/add_writer` `NotImplementedError`.
301
-
337
+
338
+ ### Create a new project from a service bundle
339
+ ```bash
340
+ uns-kit-py create --bundle ./service.bundle.json
341
+ uns-kit-py create --bundle ./service.bundle.json --dest ./my-dir
342
+ uns-kit-py create --bundle ./service.bundle.json --dest . --allow-existing
343
+ ```
344
+
345
+ Bundle-driven create uses `service.bundle.json` as the source of truth. The Python CLI:
346
+ - scaffolds the base Python app from the existing default template
347
+ - copies the original bundle into the project root as `service.bundle.json`
348
+ - generates `SERVICE_SPEC.md` and `AGENTS.md`
349
+ - applies supported bundle features such as `vscode` and `devops`
350
+
351
+ When `--bundle` is used, the default destination is `./<metadata.name>`. The Python CLI only accepts bundles with `scaffold.stack = "python"` and currently supports `scaffold.template = "default"` for this MVP. If the bundle targets TypeScript instead, use `uns-kit create --bundle ...`.
352
+
353
+ ### Create a sandbox app in this repo
354
+ From the monorepo root:
355
+ ```bash
356
+ pnpm run py:sandbox
357
+ ```
358
+ This creates `sandbox-app-py/` using the default Python template.
359
+ When created inside this monorepo, `pyproject.toml` is automatically set to use local editable `uns-kit`:
360
+ `uns-kit = { path = "../packages/uns-py", develop = true }`.
361
+
362
+ ## Notes
363
+ - Default QoS is 0.
364
+ - Instance status topics are published every 10 seconds; stats every 60 seconds.
365
+ - Packet shape mirrors the TypeScript core: `{"version":"1.3.0","message":{"data":{...}},"sequenceId":0}`.
366
+ - Windows: the library sets `WindowsSelectorEventLoopPolicy()` to avoid `add_reader/add_writer` `NotImplementedError`.
367
+
302
368
  ## TODO (parity with TS core)
303
369
  - Handover manager parity: subscribe to wildcard `active` and `handover` topics, keep new instances passive until timeout or handover completion, and support `handover_intent`, `handover_request`, `handover_subscriber`, `handover_fin`, and `handover_ack`.
304
370
  - Publish throttling / queue parity: add buffered ordered publishing instead of direct proxy-path publish, plus publisher/subscriber active-passive controls and passive-drain behavior.