omixom-data 0.3.0__py3-none-any.whl

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",
+]

omixom_data/client.py

@@ -0,0 +1,277 @@
+"""Cliente HTTP de la Omixom Data API v3.
+
+Expone las lecturas crudas de la API (listado, detalle, página de serie, página de cambios) y
+la fábrica del flujo guiado (`feed`/`resume`), que es el camino recomendado para replicar
+mediciones. Maneja autenticación por token, errores en formato problem+json y los límites de
+uso: ante un 429 espera lo que indique `Retry-After` y reintenta, así un bootstrap largo avanza
+solo (desactivable con `wait_on_rate_limit=False`).
+"""
+
+import time
+from collections.abc import Callable, Iterator, Sequence
+from datetime import datetime
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from omixom_data.errors import (
+    AuthenticationError,
+    InvalidRequestError,
+    NotFoundError,
+    OmixomDataError,
+    RateLimitedError,
+    ServerError,
+)
+from omixom_data.feed import Feed, flatten_series_page
+from omixom_data.schemas import (
+    Category,
+    ChangesPage,
+    Measurement,
+    SeriesPage,
+    StationDetail,
+    StationSummary,
+)
+from omixom_data.state import FeedState, ModuleState
+
+DEFAULT_BASE_URL = "https://clima.omixom.com"
+# La forma de query params que httpx acepta como lista de pares.
+_Params = list[tuple[str, str | int | float | None]]
+# Cota de una espera individual por rate limit; un Retry-After mayor se considera anómalo.
+MAX_RATE_LIMIT_WAIT = 3600.0
+
+
+class Client:
+    """Acceso a la Omixom Data API v3 con un token de la red Omixom.
+
+    Uso típico:
+
+        with Client(token="...") as client:
+            feed = client.feed([30125, 30126])
+            for batch in feed.batches():
+                apply_all(batch.events)
+                save(batch.state.model_dump_json())
+
+    Las lecturas crudas (`stations`, `station`, `series_page`, `changes_page`) devuelven los
+    payloads tipados tal cual; el manejo del cursor queda a cargo del caller. Para replicar
+    series conviene `feed`/`resume`, que lo encapsulan.
+    """
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        wait_on_rate_limit: bool = True,
+        transport: httpx.BaseTransport | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self._http = httpx.Client(
+            base_url=f"{base_url.rstrip('/')}/api/v3",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=timeout,
+            transport=transport,
+        )
+        self._wait_on_rate_limit = wait_on_rate_limit
+        self._sleep = sleep
+
+    def stations(self) -> list[StationSummary]:
+        """Lista los equipos accesibles con el token."""
+        payload = self._get("/stations")
+        return [StationSummary.model_validate(row) for row in payload["stations"]]
+
+    def station(self, code: int) -> StationDetail:
+        """Detalle de un equipo: fecha de instalación y módulos."""
+        return StationDetail.model_validate(self._get(f"/stations/{code}"))
+
+    def series(
+        self,
+        code: int,
+        *,
+        date_from: datetime,
+        date_to: datetime,
+        modules: Sequence[int] | None = None,
+        categories: Sequence[Category] | None = None,
+    ) -> Iterator[Measurement]:
+        """Serie completa de la ventana `[date_from, date_to)`, en una sola lectura coherente.
+
+        Camina todas las páginas del snapshot repitiendo el cursor de la primera, así el
+        resultado entero es un corte de la base en un único instante aunque haya escrituras
+        concurrentes. Streamea de a una página: se consume iterando; para materializar,
+        `list(...)`. Dentro de cada página los módulos van ascendentes y sus tiempos ordenados;
+        páginas sucesivas avanzan en el tiempo. Para réplicas que se mantienen al día, `feed`.
+        """
+        requested = list(categories) if categories is not None else [Category.OK]
+        cursor: datetime | None = None
+        start = date_from
+        while True:
+            page = self.series_page(
+                code,
+                date_from=start,
+                date_to=date_to,
+                modules=modules,
+                categories=requested,
+                cursor=cursor,
+            )
+            yield from flatten_series_page(code, page, requested, into=Measurement)
+            if not page.has_more or page.next_from is None:
+                return
+            cursor = page.cursor
+            start = page.next_from
+
+    def series_page(
+        self,
+        code: int,
+        *,
+        date_from: datetime,
+        date_to: datetime,
+        modules: Sequence[int] | None = None,
+        categories: Sequence[Category] | None = None,
+        cursor: datetime | None = None,
+    ) -> SeriesPage:
+        """Una página del snapshot de la serie en `[date_from, date_to)`.
+
+        Para paginar de forma coherente, repetir el request con `date_from` igual al
+        `next_from` recibido y `cursor` igual al `cursor` recibido.
+        """
+        params: _Params = [
+            ("date_from", date_from.isoformat()),
+            ("date_to", date_to.isoformat()),
+        ]
+        params.extend(("modules", str(module)) for module in modules or ())
+        params.extend(("category", category.wire_name) for category in categories or ())
+        if cursor is not None:
+            params.append(("cursor", cursor.isoformat()))
+        return SeriesPage.model_validate(self._get(f"/stations/{code}/measurements/series", params))
+
+    def changes_page(
+        self,
+        code: int,
+        *,
+        cursor: datetime,
+        modules: Sequence[int] | None = None,
+        date_from: datetime | None = None,
+        date_to: datetime | None = None,
+    ) -> ChangesPage:
+        """Una página del feed de cambios registrados después de `cursor`."""
+        params: _Params = [("cursor", cursor.isoformat())]
+        params.extend(("modules", str(module)) for module in modules or ())
+        if date_from is not None:
+            params.append(("date_from", date_from.isoformat()))
+        if date_to is not None:
+            params.append(("date_to", date_to.isoformat()))
+        return ChangesPage.model_validate(
+            self._get(f"/stations/{code}/measurements/changes", params)
+        )
+
+    def feed(
+        self,
+        stations: Sequence[int],
+        *,
+        date_from: datetime | None = None,
+        date_to: datetime | None = None,
+        modules: Sequence[int] | None = None,
+        categories: Sequence[Category] | None = None,
+    ) -> Feed:
+        """Feed de réplica para un grupo de estaciones.
+
+        Sin fechas replica toda la historia de cada equipo (desde su fecha de instalación) y
+        sigue los cambios para siempre. `date_from` acota el inicio ("desde 2023 en adelante")
+        y `date_to` cierra la ventana ("de 2023 a 2024"); las fechas deben ser timezone-aware.
+
+        `modules` acota a esos módulos, de cualquiera de las estaciones dadas: una estación sin
+        módulos seleccionados no genera requests, y un módulo que no pertenece a ninguna es
+        `ValueError`. El conjunto replicado queda fijado acá: un módulo instalado en el equipo
+        después de crear el feed no se suma solo.
+        """
+        for bound, name in ((date_from, "date_from"), (date_to, "date_to")):
+            if bound is not None and bound.tzinfo is None:
+                raise ValueError(f"{name} debe ser timezone-aware")
+        if date_from is not None and date_to is not None and date_from > date_to:
+            raise ValueError("date_from debe ser menor o igual a date_to")
+        remaining = set(modules) if modules is not None else None
+        module_states: dict[int, ModuleState] = {}
+        for code in stations:
+            owned = [module.id for module in self.station(code).modules]
+            selected = owned if remaining is None else [m for m in owned if m in remaining]
+            if remaining is not None:
+                remaining.difference_update(selected)
+            for module in selected:
+                module_states[module] = ModuleState(station=code)
+        if remaining:
+            raise ValueError(
+                f"módulos que no pertenecen a las estaciones dadas: {sorted(remaining)}"
+            )
+        state = FeedState(
+            modules=module_states,
+            date_from=date_from,
+            date_to=date_to,
+            categories=[int(c) for c in categories] if categories is not None else None,
+        )
+        return Feed(self, state)
+
+    def resume(self, state: FeedState) -> Feed:
+        """Continúa un feed desde un estado persistido con `FeedState.model_dump_json()`."""
+        state.require_supported_version()
+        return Feed(self, state)
+
+    def close(self) -> None:
+        """Cierra la conexión HTTP subyacente."""
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def _get(self, path: str, params: _Params | None = None) -> dict[str, Any]:
+        while True:
+            response = self._http.get(path, params=params)
+            if response.status_code == 429 and self._wait_on_rate_limit:
+                self._sleep(min(_retry_after(response) or 1.0, MAX_RATE_LIMIT_WAIT))
+                continue
+            if response.is_success:
+                return response.json()
+            raise _to_error(response)
+
+
+def _retry_after(response: httpx.Response) -> float | None:
+    header = response.headers.get("Retry-After")
+    try:
+        return float(header) if header is not None else None
+    except ValueError:
+        return None
+
+
+def _to_error(response: httpx.Response) -> OmixomDataError:
+    detail = _problem_detail(response)
+    status = response.status_code
+    if status in (401, 403):
+        return AuthenticationError(detail)
+    if status == 404:
+        return NotFoundError(detail)
+    if status == 422:
+        return InvalidRequestError(detail)
+    if status == 429:
+        return RateLimitedError(detail, retry_after=_retry_after(response))
+    if status >= 500:
+        return ServerError(detail)
+    return OmixomDataError(detail)
+
+
+def _problem_detail(response: httpx.Response) -> str:
+    try:
+        problem = response.json()
+        return problem.get("detail") or problem.get("title") or response.text
+    except ValueError:
+        return f"HTTP {response.status_code}"
+
+
+__all__ = ["DEFAULT_BASE_URL", "MAX_RATE_LIMIT_WAIT", "Client"]

omixom_data/errors.py

@@ -0,0 +1,51 @@
+"""Jerarquía de errores del cliente: cada respuesta de error de la API mapea a un tipo propio.
+
+La API responde errores en formato RFC 9457 (`application/problem+json`); el mensaje de cada
+excepción lleva el `detail` (o el `title`) del problem recibido.
+"""
+
+
+class OmixomDataError(Exception):
+    """Raíz de todo error del cliente. Capturarla atrapa cualquier falla de la API."""
+
+
+class AuthenticationError(OmixomDataError):
+    """El token falta, es inválido o no tiene acceso al recurso (401/403)."""
+
+
+class NotFoundError(OmixomDataError):
+    """El equipo pedido no existe o está fuera del alcance del token (404)."""
+
+
+class InvalidRequestError(OmixomDataError):
+    """La API rechazó los parámetros del request (422)."""
+
+
+class RateLimitedError(OmixomDataError):
+    """Límite de uso excedido (429) y el cliente está configurado para no esperar.
+
+    `retry_after` indica cuántos segundos esperar antes de reintentar.
+    """
+
+    def __init__(self, message: str, retry_after: float | None = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class ServerError(OmixomDataError):
+    """La API falló con un error interno (5xx)."""
+
+
+class StateError(OmixomDataError):
+    """El estado de feed provisto es inconsistente o de una versión desconocida."""
+
+
+__all__ = [
+    "AuthenticationError",
+    "InvalidRequestError",
+    "NotFoundError",
+    "OmixomDataError",
+    "RateLimitedError",
+    "ServerError",
+    "StateError",
+]

omixom_data/events.py

@@ -0,0 +1,30 @@
+"""Eventos que emite el feed: la interfaz única que el consumidor aplica a su copia.
+
+Tanto el bootstrap como los cambios posteriores llegan como estos dos eventos, así el consumidor
+escribe una sola función de aplicación: upsert de `(station, module, time) -> value` para
+`MeasurementUpserted`, eliminación para `MeasurementDeleted`. Aplicarlos es idempotente por
+diseño: re-aplicar un evento deja la copia igual.
+"""
+
+from datetime import datetime
+
+from pydantic import BaseModel
+
+from omixom_data.schemas import Measurement
+
+
+class MeasurementUpserted(Measurement):
+    """Una medición nueva o corregida: dejar la copia en este valor."""
+
+
+class MeasurementDeleted(BaseModel):
+    """Una medición que dejó de existir (o salió de la vista filtrada): quitarla de la copia."""
+
+    station: int
+    module: int
+    time: datetime
+
+
+FeedEvent = MeasurementUpserted | MeasurementDeleted
+
+__all__ = ["FeedEvent", "MeasurementDeleted", "MeasurementUpserted"]

omixom_data/feed.py

@@ -0,0 +1,290 @@
+"""Flujo guiado de réplica en batches: una página HTTP por batch, con checkpoint alineado.
+
+`Feed.batches()` emite la secuencia que mantiene una copia al día: primero el bootstrap de cada
+módulo (páginas de `/series` leídas as-of un mismo cursor) y después lo registrado desde cada
+cursor (`/changes`), hasta quedar al día. Cada `Batch` trae los eventos de una página y el
+estado ya avanzado más allá de ella: el contrato del consumidor es aplicar los eventos primero
+y persistir `batch.state` después (o ambos en una transacción de su store). Con ese orden, un
+corte en cualquier punto deja como peor caso una página re-aplicada, que el replay idempotente
+absorbe. `batches()` es re-llamable: cada llamada avanza hasta quedar al día y la siguiente
+retoma desde ahí.
+
+El estado es por módulo y los requests por estación: los módulos que comparten cursor viajan
+juntos en un mismo request (el caso común es todos los del equipo), el bootstrap avanza
+round-robin entre estaciones para solapar sus límites de uso, y un grupo con cursores
+desparejos se re-unifica pidiendo los cambios desde el mínimo: la re-entrega para los más
+avanzados la absorbe la idempotencia y todos salen con el mismo cursor. Con un filtro de
+categorías, un punto corregido hacia una categoría no seleccionada se emite como borrado:
+salió de la vista replicada.
+"""
+
+from collections.abc import Iterator, Sequence
+from datetime import UTC, datetime
+from typing import Literal, Protocol, TypeVar
+
+from pydantic import BaseModel
+
+from omixom_data.errors import StateError
+from omixom_data.events import FeedEvent, MeasurementDeleted, MeasurementUpserted
+from omixom_data.schemas import (
+    Category,
+    Change,
+    ChangesPage,
+    Measurement,
+    SeriesPage,
+    StationDetail,
+)
+from omixom_data.state import FeedState, ModuleState
+
+# Piso del bootstrap cuando el equipo no tiene fecha de instalación registrada.
+DEFAULT_START = datetime(2000, 1, 1, tzinfo=UTC)
+# Fin abierto: la API exige ventanas cerradas, así que "en adelante" se pide hasta acá.
+FAR_FUTURE = datetime(9999, 1, 1, tzinfo=UTC)
+
+_MeasurementT = TypeVar("_MeasurementT", bound=Measurement)
+
+
+def flatten_series_page(
+    code: int,
+    page: SeriesPage,
+    requested: Sequence[Category],
+    *,
+    into: type[_MeasurementT],
+) -> Iterator[_MeasurementT]:
+    """Aplana la página columnar a una medición por punto, módulos en orden ascendente.
+
+    Cuando el request filtró una sola categoría el wire omite `categories`; el valor se repone
+    con la categoría pedida. `meta` omitido es `None` por punto.
+    """
+    for module in sorted(page.modules):
+        series = page.modules[module]
+        count = len(series.times)
+        categories = series.categories or [int(requested[0])] * count
+        meta = series.meta or [None] * count
+        for i in range(count):
+            yield into(
+                station=code,
+                module=module,
+                time=series.times[i],
+                value=series.values[i],
+                category=categories[i],
+                meta=meta[i],
+            )
+
+
+class SeriesApi(Protocol):
+    """Lo que el feed necesita del cliente HTTP; `Client` lo satisface estructuralmente."""
+
+    def station(self, code: int) -> StationDetail:
+        """Detalle del equipo, para derivar el inicio del bootstrap."""
+        ...
+
+    def series_page(
+        self,
+        code: int,
+        *,
+        date_from: datetime,
+        date_to: datetime,
+        modules: Sequence[int] | None = None,
+        categories: Sequence[Category] | None = None,
+        cursor: datetime | None = None,
+    ) -> SeriesPage:
+        """Una página del snapshot as-of `cursor`."""
+        ...
+
+    def changes_page(
+        self,
+        code: int,
+        *,
+        cursor: datetime,
+        modules: Sequence[int] | None = None,
+        date_from: datetime | None = None,
+        date_to: datetime | None = None,
+    ) -> ChangesPage:
+        """Una página del feed de cambios posteriores a `cursor`."""
+        ...
+
+
+class Batch(BaseModel):
+    """Una página del sync: los eventos a aplicar y el estado que la deja atrás.
+
+    Aplicar `events` primero y persistir `state` después: `state` ya incluye el avance de este
+    batch, así que persistirlo sin haber aplicado puede perder eventos, mientras que aplicar
+    sin llegar a persistir solo repite la página en la próxima corrida.
+    """
+
+    station: int
+    modules: list[int]
+    phase: Literal["bootstrap", "changes"]
+    events: list[FeedEvent]
+    state: FeedState
+
+
+class Feed:
+    """Réplica incremental de un grupo de estaciones; se construye con `Client.feed`/`resume`."""
+
+    def __init__(self, api: SeriesApi, state: FeedState) -> None:
+        self._api = api
+        self._state = state
+        self._starts: dict[int, datetime] = {}
+
+    @property
+    def state(self) -> FeedState:
+        """Snapshot serializable del avance; para checkpoints alineados usar `batch.state`."""
+        return self._state.model_copy(deep=True)
+
+    def batches(self) -> Iterator[Batch]:
+        """Un batch por página hasta dejar la copia al día; re-llamable para re-sincronizar."""
+        yield from self._bootstrap_rounds()
+        yield from self._follow_rounds()
+
+    def add_modules(self, station: int, modules: Sequence[int] | None = None) -> list[int]:
+        """Suma módulos de `station` al feed; sin `modules`, todos los del equipo que falten.
+
+        Devuelve los ids agregados, omitiendo los ya rastreados; un id que no pertenece al
+        equipo es `ValueError`. Los nuevos hacen su bootstrap en el próximo `batches()` sin
+        tocar el avance del resto.
+        """
+        owned = [module.id for module in self._api.station(station).modules]
+        if modules is None:
+            selected = owned
+        else:
+            unknown = sorted(set(modules) - set(owned))
+            if unknown:
+                raise ValueError(f"módulos que no pertenecen a la estación {station}: {unknown}")
+            selected = list(modules)
+        added = sorted(module for module in selected if module not in self._state.modules)
+        for module in added:
+            self._state.modules[module] = ModuleState(station=station)
+        return added
+
+    def _bootstrap_rounds(self) -> Iterator[Batch]:
+        while True:
+            progressed = False
+            for station in self._stations():
+                group = self._pending_group(station)
+                if not group:
+                    continue
+                progressed = True
+                yield self._bootstrap_page(station, group)
+            if not progressed:
+                return
+
+    def _follow_rounds(self) -> Iterator[Batch]:
+        active = {station: self._station_modules(station) for station in self._stations()}
+        while active:
+            for station in sorted(active):
+                batch, exhausted = self._follow_page(station, active[station])
+                if exhausted:
+                    del active[station]
+                yield batch
+
+    def _pending_group(self, station: int) -> list[int]:
+        """Los módulos pendientes de la estación que comparten posición de bootstrap."""
+        pending = [
+            module
+            for module in self._station_modules(station)
+            if not self._state.modules[module].bootstrapped
+        ]
+        if not pending:
+            return []
+        first = self._state.modules[pending[0]]
+        return [
+            module
+            for module in pending
+            if (self._state.modules[module].cursor, self._state.modules[module].next_from)
+            == (first.cursor, first.next_from)
+        ]
+
+    def _bootstrap_page(self, station: int, group: list[int]) -> Batch:
+        first = self._state.modules[group[0]]
+        page = self._api.series_page(
+            station,
+            date_from=first.next_from or self._window_start(station),
+            date_to=self._state.date_to or FAR_FUTURE,
+            modules=group,
+            categories=self._categories(),
+            cursor=first.cursor,
+        )
+        events: list[FeedEvent] = list(
+            flatten_series_page(station, page, self._categories(), into=MeasurementUpserted)
+        )
+        for module in group:
+            module_state = self._state.modules[module]
+            module_state.cursor = page.cursor
+            module_state.next_from = page.next_from
+            module_state.bootstrapped = not page.has_more
+        return Batch(
+            station=station, modules=group, phase="bootstrap", events=events, state=self.state
+        )
+
+    def _follow_page(self, station: int, group: list[int]) -> tuple[Batch, bool]:
+        cursors: list[datetime] = []
+        for module in group:
+            cursor = self._state.modules[module].cursor
+            if cursor is None:
+                raise StateError(f"el módulo {module} no tiene cursor: estado corrupto")
+            cursors.append(cursor)
+        time_from, time_to = self._changes_window()
+        page = self._api.changes_page(
+            station,
+            cursor=min(cursors),
+            modules=group,
+            date_from=time_from,
+            date_to=time_to,
+        )
+        events = [self._change_event(station, change) for change in page.changes]
+        for module in group:
+            self._state.modules[module].cursor = page.cursor
+        batch = Batch(
+            station=station, modules=group, phase="changes", events=events, state=self.state
+        )
+        return batch, not page.has_more
+
+    def _stations(self) -> list[int]:
+        return sorted({module_state.station for module_state in self._state.modules.values()})
+
+    def _station_modules(self, station: int) -> list[int]:
+        return sorted(
+            module
+            for module, module_state in self._state.modules.items()
+            if module_state.station == station
+        )
+
+    def _window_start(self, station: int) -> datetime:
+        if self._state.date_from is not None:
+            return self._state.date_from
+        if station not in self._starts:
+            installed = self._api.station(station).installation_date
+            self._starts[station] = (
+                DEFAULT_START
+                if installed is None
+                else datetime(installed.year, installed.month, installed.day, tzinfo=UTC)
+            )
+        return self._starts[station]
+
+    def _changes_window(self) -> tuple[datetime | None, datetime | None]:
+        if self._state.date_from is None:
+            return None, None
+        return self._state.date_from, self._state.date_to or FAR_FUTURE
+
+    def _categories(self) -> list[Category]:
+        if self._state.categories is None:
+            return [Category.OK]
+        return [Category(value) for value in self._state.categories]
+
+    def _change_event(self, code: int, change: Change) -> FeedEvent:
+        in_view = change.category in {int(c) for c in self._categories()}
+        if change.operation == "deleted" or not in_view:
+            return MeasurementDeleted(station=code, module=change.module, time=change.time)
+        return MeasurementUpserted(
+            station=code,
+            module=change.module,
+            time=change.time,
+            value=change.value,
+            category=change.category,
+            meta=change.meta,
+        )
+
+
+__all__ = ["DEFAULT_START", "FAR_FUTURE", "Batch", "Feed", "SeriesApi", "flatten_series_page"]

omixom_data/schemas.py

@@ -0,0 +1,120 @@
+"""Formas de wire de la Omixom Data API v3, tipadas con Pydantic.
+
+Espejan los payloads de los endpoints tal cual llegan; el cliente las expone directamente en
+las lecturas de bajo nivel (`Client.series_page`/`Client.changes_page`) y las traduce a eventos
+en el flujo guiado (`Feed`).
+"""
+
+from datetime import date, datetime
+from enum import IntEnum
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+
+class Category(IntEnum):
+    """Categorías de dato de la API; el valor es el int de wire y el nombre el de query."""
+
+    ERROR = -1
+    OK = 0
+    TESTING = 1
+    NOT_CALCULATED = 2
+
+    @property
+    def wire_name(self) -> str:
+        """El nombre que la API acepta en el query param `category`."""
+        return self.name.lower()
+
+
+class Measurement(BaseModel):
+    """Una medición de la serie de un módulo, identificada por `(station, module, time)`."""
+
+    station: int
+    module: int
+    time: datetime
+    value: float
+    category: int
+    meta: dict[str, Any] | None = None
+
+
+class StationSummary(BaseModel):
+    """Equipo del listado de `GET /stations`."""
+
+    code: int
+    title: str
+    latitude: float
+    longitude: float
+
+
+class ModuleDetail(BaseModel):
+    """Módulo dentro del detalle de un equipo."""
+
+    id: int
+    title: str
+    type: str
+
+
+class StationDetail(BaseModel):
+    """Detalle de `GET /stations/{code}`: fecha de instalación y módulos."""
+
+    code: int
+    title: str
+    installation_date: date | None
+    modules: list[ModuleDetail]
+
+
+class SeriesModule(BaseModel):
+    """Serie columnar de un módulo: arrays paralelos alineados por índice.
+
+    `categories` viene `null` cuando el request filtró una sola categoría; `flags` y `meta`
+    vienen `null` cuando ningún punto los tiene.
+    """
+
+    times: list[datetime]
+    values: list[float]
+    categories: list[int] | None = None
+    flags: list[int | None] | None = None
+    meta: list[dict[str, Any] | None] | None = None
+
+
+class SeriesPage(BaseModel):
+    """Página de `GET /stations/{code}/measurements/series`."""
+
+    modules: dict[int, SeriesModule]
+    next_from: datetime | None
+    has_more: bool
+    cursor: datetime
+
+
+class Change(BaseModel):
+    """Cambio del feed de `GET /stations/{code}/measurements/changes`."""
+
+    module: int
+    time: datetime
+    value: float
+    category: int
+    meta: dict[str, Any] | None
+    operation: Literal["created", "updated", "deleted"]
+    revision: int
+    transaction_time: datetime
+
+
+class ChangesPage(BaseModel):
+    """Página de `GET /stations/{code}/measurements/changes`."""
+
+    changes: list[Change]
+    cursor: datetime
+    has_more: bool
+
+
+__all__ = [
+    "Category",
+    "Change",
+    "ChangesPage",
+    "Measurement",
+    "ModuleDetail",
+    "SeriesModule",
+    "SeriesPage",
+    "StationDetail",
+    "StationSummary",
+]

omixom_data/state.py

@@ -0,0 +1,45 @@
+"""Estado serializable de un feed: la configuración del alcance y el avance por módulo.
+
+Es lo único que un consumidor persiste entre corridas: `batch.state.model_dump_json()` tras
+aplicar cada batch, `FeedState.model_validate_json()` al arrancar y `Client.resume(state)` para
+continuar donde quedó. El avance es por módulo (el módulo es la serie; la estación solo agrupa
+los requests), y la configuración viaja adentro del estado porque el cursor solo vale para el
+alcance con el que se generó: retomar con otros filtros exige un feed nuevo.
+"""
+
+from datetime import datetime
+
+from pydantic import BaseModel
+
+from omixom_data.errors import StateError
+
+STATE_VERSION = 1
+
+
+class ModuleState(BaseModel):
+    """Avance de un módulo: su estación, el cursor del corte y la posición del bootstrap."""
+
+    station: int
+    cursor: datetime | None = None
+    next_from: datetime | None = None
+    bootstrapped: bool = False
+
+
+class FeedState(BaseModel):
+    """Estado completo de un feed: alcance y avance por módulo."""
+
+    version: int = STATE_VERSION
+    modules: dict[int, ModuleState]
+    date_from: datetime | None = None
+    date_to: datetime | None = None
+    categories: list[int] | None = None
+
+    def require_supported_version(self) -> None:
+        """Rechaza estados de una versión que este cliente no sabe interpretar."""
+        if self.version != STATE_VERSION:
+            raise StateError(
+                f"versión de estado {self.version} no soportada (esperada {STATE_VERSION})"
+            )
+
+
+__all__ = ["STATE_VERSION", "FeedState", "ModuleState"]

omixom_data-0.3.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+omixom_data/__init__.py,sha256=gQmmW7g5KJDdz_zYONWHRPUWT_BG7Fl5FYHHsE8j5Qg,1709
+omixom_data/client.py,sha256=NcB8kk1mdA-GGu8T499E9ycz3icHs315OC_CpzGSszw,10537
+omixom_data/errors.py,sha256=iQ3MFY7Se52Kyk0S2wzfwp9w4PfIjuxq7J2WVf6aBuc,1486
+omixom_data/events.py,sha256=jGzROGLGr0ofIsN8-BxT5-043FBYAEgAcdsfO6KWktc,965
+omixom_data/feed.py,sha256=6XQBMhYMDJkvVPXhTyiE3qaHlr_urs9Pnx4Whw72Jno,11423
+omixom_data/schemas.py,sha256=tINsT67dbQrO9lFGFGE7DHxkHrpS-C7VC4oOKjWaI60,2810
+omixom_data/state.py,sha256=EHbx-8hHT2YzZ7-dx0kvKe5Hl6b9vaLhatfTHjN9jXw,1584
+omixom_data-0.3.0.dist-info/METADATA,sha256=1F_UpVgLQC7PJdBRkBPwzsjDKCYYdIu5gjQ-m1O0h4E,6020
+omixom_data-0.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+omixom_data-0.3.0.dist-info/RECORD,,

omixom_data-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any