omixom-data 0.3.0__tar.gz

omixom_data-0.3.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# Virtualenvs
+.venv/
+venv/
+
+# Tox
+.tox/
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Env files locales
+.env
+.env.local

omixom_data-0.3.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.3.0](https://github.com/omixom/dataapi/compare/omixom-data-v0.2.0...omixom-data-v0.3.0) (2026-08-31)
+
+
+### Features
+
+* **client:** agrega Feed.add_modules para sumar sensores a un feed existente ([0734267](https://github.com/omixom/dataapi/commit/07342674cfdfce0f2c00d0a5517ac8cd7e274c3a))
+
+## [0.2.0](https://github.com/omixom/dataapi/compare/omixom-data-v0.1.0...omixom-data-v0.2.0) (2026-08-31)
+
+
+### Features
+
+* **client:** agrega el cliente python omixom-data ([2b31484](https://github.com/omixom/dataapi/commit/2b31484c51981202ad15ffebdb26f67825910c1e))
+
+## Changelog

omixom_data-0.3.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: omixom-data
+Version: 0.3.0
+Summary: Cliente Python de la Omixom Data API v3: lectura de series y réplica incremental de mediciones.
+Author: Omixom
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# omixom-data
+
+Cliente Python de la [Omixom Data API v3](https://clima.omixom.com/api/v3/docs): lectura de
+series de mediciones y réplica incremental para mantener una copia siempre al día.
+
+```bash
+pip install omixom-data
+```
+
+Requiere Python 3.11+ y un token de acceso de la red Omixom.
+
+## Mantener una copia al día
+
+El caso típico es replicar las mediciones de un grupo de equipos y seguirlas en el tiempo. El
+`Feed` encapsula todo el protocolo (bootstrap paginado, cursores, coherencia del snapshot) y lo
+entrega en **batches**: cada batch es una página de trabajo acotado que trae sus eventos y el
+estado que la deja atrás.
+
+```python
+from omixom_data import Client, MeasurementDeleted
+
+with Client(token="...") as client:
+    feed = client.feed([30125, 30126])  # toda la historia de cada equipo
+
+    for batch in feed.batches():  # bootstrap + cambios, hasta estar al día
+        for event in batch.events:
+            if isinstance(event, MeasurementDeleted):
+                store.delete(event.station, event.module, event.time)
+            else:
+                store.upsert(event.station, event.module, event.time, event.value)
+        save(batch.state.model_dump_json())  # checkpoint alineado a la página
+```
+
+El contrato es **aplicar primero, guardar después** (idealmente ambos en una transacción del
+store propio). Con ese orden, cortar el proceso en cualquier punto (incluso a mitad de un
+backfill de días) deja como peor caso una página re-aplicada, y aplicar eventos es idempotente
+por diseño: `MeasurementUpserted` deja la copia en ese valor, `MeasurementDeleted` la quita,
+re-aplicar no cambia nada. Cada batch persistido es progreso ganado; `break` entre batches es
+siempre seguro.
+
+Para volver a sincronizar (el próximo poll o la próxima corrida del proceso):
+
+```python
+from omixom_data import Client, FeedState
+
+with Client(token="...") as client:
+    feed = client.resume(FeedState.model_validate_json(saved))
+    for batch in feed.batches():  # solo lo que falta desde el checkpoint
+        apply_all(batch.events)
+        save(batch.state.model_dump_json())
+```
+
+`batches()` es re-llamable: cada llamada avanza hasta quedar al día y la siguiente retoma desde
+ahí, así que el loop de un daemon es `batches()` + esperar el intervalo deseado. El avance es
+por módulo (el estado guarda un cursor por serie) y los requests van por estación: el bootstrap
+de varios equipos avanza round-robin para solapar sus límites de uso.
+
+## Acotar el rango
+
+```python
+from datetime import UTC, datetime
+
+feed = client.feed([30125], date_from=datetime(2023, 1, 1, tzinfo=UTC))  # desde 2023
+feed = client.feed(
+    [30125],
+    date_from=datetime(2023, 1, 1, tzinfo=UTC),
+    date_to=datetime(2024, 1, 1, tzinfo=UTC),  # 2023 completo
+)
+```
+
+Sin fechas, cada equipo se replica desde su fecha de instalación. Con `date_from` solo, la
+réplica sigue recibiendo lo nuevo; con ambas, la ventana queda cerrada pero las correcciones a
+datos de esa ventana siguen llegando. `modules` acota a esos módulos, de cualquiera de las
+estaciones dadas (una estación sin módulos seleccionados no genera requests); el conjunto
+replicado queda fijado al crear el feed, así que un sensor instalado después no se suma solo
+(ver abajo).
+`categories` filtra qué tipo de dato replicar; con ese filtro, un punto corregido hacia una
+categoría no seleccionada llega como borrado (salió de la vista replicada).
+
+## Sumar módulos a un feed existente
+
+Un sensor instalado después de crear el feed se suma con `add_modules`, sobre un feed nuevo o
+retomado; sin lista de módulos entran todos los del equipo que falten:
+
+```python
+feed = client.resume(FeedState.model_validate_json(saved))
+feed.add_modules(30125)  # o add_modules(30125, [4812]) para uno puntual
+
+for batch in feed.batches():  # el nuevo hace su bootstrap; el resto sigue donde estaba
+    apply_all(batch.events)
+    save(batch.state.model_dump_json())
+```
+
+Devuelve los ids agregados (los ya rastreados se omiten) y rechaza con `ValueError` un módulo
+que no pertenece al equipo. También sirve para sumar una estación nueva al feed. El alta queda
+persistida con el `state` del próximo batch, así que si el proceso corta antes, la próxima corrida
+tiene que volver a llamarlo.
+
+## Lecturas puntuales
+
+Para consultas de una sola vez, sin réplica:
+
+```python
+client.stations()  # equipos accesibles con el token
+client.station(30125)  # fecha de instalación y módulos
+
+for point in client.series(  # la serie completa de una ventana, en streaming
+    30125,
+    date_from=datetime(2024, 1, 1, tzinfo=UTC),
+    date_to=datetime(2024, 2, 1, tzinfo=UTC),
+):
+    print(point.module, point.time, point.value)
+```
+
+`series` camina todas las páginas por adentro repitiendo el cursor de la primera, así el
+resultado entero es un corte coherente de la base aunque haya escrituras concurrentes. Para
+materializar la serie, `list(client.series(...))`.
+
+Debajo de eso está el acceso crudo página por página (`series_page`, `changes_page`), donde el
+manejo del cursor queda a cargo del caller: para paginar de forma coherente hay que repetir el
+request con `date_from` igual al `next_from` recibido y `cursor` igual al `cursor` recibido.
+
+## Errores y límites de uso
+
+Los errores de la API llegan como excepciones tipadas bajo `OmixomDataError`:
+`AuthenticationError`, `NotFoundError`, `InvalidRequestError`, `RateLimitedError` y
+`ServerError`. Ante un 429 el cliente espera lo que indique `Retry-After` y reintenta solo;
+`Client(..., wait_on_rate_limit=False)` desactiva la espera y levanta `RateLimitedError` con el
+tiempo sugerido en `retry_after`.
+
+## Desarrollo
+
+```bash
+uv sync
+uv run tox        # style + tests + cobertura
+```

omixom_data-0.3.0/README.md

@@ -0,0 +1,136 @@
+# omixom-data
+
+Cliente Python de la [Omixom Data API v3](https://clima.omixom.com/api/v3/docs): lectura de
+series de mediciones y réplica incremental para mantener una copia siempre al día.
+
+```bash
+pip install omixom-data
+```
+
+Requiere Python 3.11+ y un token de acceso de la red Omixom.
+
+## Mantener una copia al día
+
+El caso típico es replicar las mediciones de un grupo de equipos y seguirlas en el tiempo. El
+`Feed` encapsula todo el protocolo (bootstrap paginado, cursores, coherencia del snapshot) y lo
+entrega en **batches**: cada batch es una página de trabajo acotado que trae sus eventos y el
+estado que la deja atrás.
+
+```python
+from omixom_data import Client, MeasurementDeleted
+
+with Client(token="...") as client:
+    feed = client.feed([30125, 30126])  # toda la historia de cada equipo
+
+    for batch in feed.batches():  # bootstrap + cambios, hasta estar al día
+        for event in batch.events:
+            if isinstance(event, MeasurementDeleted):
+                store.delete(event.station, event.module, event.time)
+            else:
+                store.upsert(event.station, event.module, event.time, event.value)
+        save(batch.state.model_dump_json())  # checkpoint alineado a la página
+```
+
+El contrato es **aplicar primero, guardar después** (idealmente ambos en una transacción del
+store propio). Con ese orden, cortar el proceso en cualquier punto (incluso a mitad de un
+backfill de días) deja como peor caso una página re-aplicada, y aplicar eventos es idempotente
+por diseño: `MeasurementUpserted` deja la copia en ese valor, `MeasurementDeleted` la quita,
+re-aplicar no cambia nada. Cada batch persistido es progreso ganado; `break` entre batches es
+siempre seguro.
+
+Para volver a sincronizar (el próximo poll o la próxima corrida del proceso):
+
+```python
+from omixom_data import Client, FeedState
+
+with Client(token="...") as client:
+    feed = client.resume(FeedState.model_validate_json(saved))
+    for batch in feed.batches():  # solo lo que falta desde el checkpoint
+        apply_all(batch.events)
+        save(batch.state.model_dump_json())
+```
+
+`batches()` es re-llamable: cada llamada avanza hasta quedar al día y la siguiente retoma desde
+ahí, así que el loop de un daemon es `batches()` + esperar el intervalo deseado. El avance es
+por módulo (el estado guarda un cursor por serie) y los requests van por estación: el bootstrap
+de varios equipos avanza round-robin para solapar sus límites de uso.
+
+## Acotar el rango
+
+```python
+from datetime import UTC, datetime
+
+feed = client.feed([30125], date_from=datetime(2023, 1, 1, tzinfo=UTC))  # desde 2023
+feed = client.feed(
+    [30125],
+    date_from=datetime(2023, 1, 1, tzinfo=UTC),
+    date_to=datetime(2024, 1, 1, tzinfo=UTC),  # 2023 completo
+)
+```
+
+Sin fechas, cada equipo se replica desde su fecha de instalación. Con `date_from` solo, la
+réplica sigue recibiendo lo nuevo; con ambas, la ventana queda cerrada pero las correcciones a
+datos de esa ventana siguen llegando. `modules` acota a esos módulos, de cualquiera de las
+estaciones dadas (una estación sin módulos seleccionados no genera requests); el conjunto
+replicado queda fijado al crear el feed, así que un sensor instalado después no se suma solo
+(ver abajo).
+`categories` filtra qué tipo de dato replicar; con ese filtro, un punto corregido hacia una
+categoría no seleccionada llega como borrado (salió de la vista replicada).
+
+## Sumar módulos a un feed existente
+
+Un sensor instalado después de crear el feed se suma con `add_modules`, sobre un feed nuevo o
+retomado; sin lista de módulos entran todos los del equipo que falten:
+
+```python
+feed = client.resume(FeedState.model_validate_json(saved))
+feed.add_modules(30125)  # o add_modules(30125, [4812]) para uno puntual
+
+for batch in feed.batches():  # el nuevo hace su bootstrap; el resto sigue donde estaba
+    apply_all(batch.events)
+    save(batch.state.model_dump_json())
+```
+
+Devuelve los ids agregados (los ya rastreados se omiten) y rechaza con `ValueError` un módulo
+que no pertenece al equipo. También sirve para sumar una estación nueva al feed. El alta queda
+persistida con el `state` del próximo batch, así que si el proceso corta antes, la próxima corrida
+tiene que volver a llamarlo.
+
+## Lecturas puntuales
+
+Para consultas de una sola vez, sin réplica:
+
+```python
+client.stations()  # equipos accesibles con el token
+client.station(30125)  # fecha de instalación y módulos
+
+for point in client.series(  # la serie completa de una ventana, en streaming
+    30125,
+    date_from=datetime(2024, 1, 1, tzinfo=UTC),
+    date_to=datetime(2024, 2, 1, tzinfo=UTC),
+):
+    print(point.module, point.time, point.value)
+```
+
+`series` camina todas las páginas por adentro repitiendo el cursor de la primera, así el
+resultado entero es un corte coherente de la base aunque haya escrituras concurrentes. Para
+materializar la serie, `list(client.series(...))`.
+
+Debajo de eso está el acceso crudo página por página (`series_page`, `changes_page`), donde el
+manejo del cursor queda a cargo del caller: para paginar de forma coherente hay que repetir el
+request con `date_from` igual al `next_from` recibido y `cursor` igual al `cursor` recibido.
+
+## Errores y límites de uso
+
+Los errores de la API llegan como excepciones tipadas bajo `OmixomDataError`:
+`AuthenticationError`, `NotFoundError`, `InvalidRequestError`, `RateLimitedError` y
+`ServerError`. Ante un 429 el cliente espera lo que indique `Retry-After` y reintenta solo;
+`Client(..., wait_on_rate_limit=False)` desactiva la espera y levanta `RateLimitedError` con el
+tiempo sugerido en `retry_after`.
+
+## Desarrollo
+
+```bash
+uv sync
+uv run tox        # style + tests + cobertura
+```

omixom_data-0.3.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "omixom-data"
+version = "0.3.0"
+description = "Cliente Python de la Omixom Data API v3: lectura de series y réplica incremental de mediciones."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Omixom" }]
+dependencies = ["httpx>=0.27", "pydantic>=2.7"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.6",
+    "ty>=0.0.1a1",
+    "tox>=4.21",
+    "tox-uv>=1.13",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/omixom_data"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF", "T20", "D"]
+ignore = ["D105", "D107"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D", "S101"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.ty.environment]
+python-version = "3.11"
+root = ["src", "."]
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["--strict-markers", "--strict-config", "--import-mode=importlib", "-ra"]
+
+[tool.coverage.run]
+source = ["omixom_data"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 95
+show_missing = true

omixom_data-0.3.0/src/omixom_data/__init__.py

@@ -0,0 +1,68 @@
+"""Cliente Python de la Omixom Data API v3.
+
+El camino recomendado es el feed de réplica en batches: cada batch es una página de trabajo
+acotado que trae sus eventos y el estado que la deja atrás.
+
+    from omixom_data import Client
+
+    with Client(token="...") as client:
+        feed = client.feed([30125, 30126])
+        for batch in feed.batches():
+            apply_all(batch.events)               # aplicar primero
+            save(batch.state.model_dump_json())   # persistir después
+
+Y para continuar en la próxima corrida, `client.resume(FeedState.model_validate_json(saved))`.
+"""
+
+from omixom_data.client import DEFAULT_BASE_URL, Client
+from omixom_data.errors import (
+    AuthenticationError,
+    InvalidRequestError,
+    NotFoundError,
+    OmixomDataError,
+    RateLimitedError,
+    ServerError,
+    StateError,
+)
+from omixom_data.events import FeedEvent, MeasurementDeleted, MeasurementUpserted
+from omixom_data.feed import Batch, Feed
+from omixom_data.schemas import (
+    Category,
+    Change,
+    ChangesPage,
+    Measurement,
+    ModuleDetail,
+    SeriesModule,
+    SeriesPage,
+    StationDetail,
+    StationSummary,
+)
+from omixom_data.state import FeedState, ModuleState
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "AuthenticationError",
+    "Batch",
+    "Category",
+    "Change",
+    "ChangesPage",
+    "Client",
+    "Feed",
+    "FeedEvent",
+    "FeedState",
+    "InvalidRequestError",
+    "Measurement",
+    "MeasurementDeleted",
+    "MeasurementUpserted",
+    "ModuleDetail",
+    "ModuleState",
+    "NotFoundError",
+    "OmixomDataError",
+    "RateLimitedError",
+    "SeriesModule",
+    "SeriesPage",
+    "ServerError",
+    "StateError",
+    "StationDetail",
+    "StationSummary",
+]