gpp-client 26.7.3__tar.gz → 26.7.3.dev2__tar.gz

{gpp_client-26.7.3 → gpp_client-26.7.3.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gpp-client
-Version: 26.7.3
+Version: 26.7.3.dev2
 Summary: Gemini Program Platform client.
 Project-URL: Homepage, https://github.com/gemini-hlsw/gpp-client
 Project-URL: Source, https://github.com/gemini-hlsw/gpp-client

{gpp_client-26.7.3 → gpp_client-26.7.3.dev2}/src/gpp_client/domains/scheduler.py

@@ -8,6 +8,7 @@ from datetime import datetime
 from typing import Any, AsyncIterator
 
 from gpp_client.domains.base import BaseDomain
+from gpp_client.rest.models import VisibilityChanges, parse_visibility_changes
 from gpp_client.generated import SchedulerObservationsUpdates
 from gpp_client.generated.get_scheduler_all_programs_id import (
     GetSchedulerAllProgramsId,
@@ -252,7 +253,7 @@ class SchedulerDomain(BaseDomain):
         if observations:
             async with self._rest as client:
                 atom_digest_response = (
-                    await client._get_atom_digests(observations)
+                    await client.get_atom_digests(observations)
                 ).split("\n")
             obs_atoms_mapping = self._parse_atom_digest(atom_digest_response)
         else:
@@ -288,6 +289,35 @@ class SchedulerDomain(BaseDomain):
         response = await self.get_program_ids(today=today)
         return [(p.reference.label, p.id) for p in response.programs.matches]
 
+    async def get_visibility_changes(self, since: datetime) -> VisibilityChanges:
+        """
+        Get observations and targets with visibility changes since a time.
+
+        Queries the ODB ``/scheduler/visibility-changes`` REST endpoint, which
+        reports entities whose visibility-relevant inputs changed at or after
+        ``since``.
+
+        Parameters
+        ----------
+        since : datetime
+            Return entities changed at or after this time. Naive datetimes are
+            assumed to be UTC.
+
+        Returns
+        -------
+        VisibilityChanges
+            Changed observation and target GIDs plus the latest change
+            timestamp reported by the endpoint.
+
+        Raises
+        ------
+        aiohttp.ClientError
+            For HTTP errors, connection failures, or timeouts.
+        """
+        async with self._rest as client:
+            body = await client.get_visibility_changes(since)
+            return parse_visibility_changes(body)
+
     async def subscribe_to_calculation_updates(
         self,
     ) -> AsyncIterator[SchedulerObservationsUpdates]:

{gpp_client-26.7.3 → gpp_client-26.7.3.dev2}/src/gpp_client/generated/package_environment.py

@@ -2,4 +2,4 @@
 Package-level environment constant for generated client code.
 """
 
-PACKAGE_ENVIRONMENT = "PRODUCTION"
+PACKAGE_ENVIRONMENT = "DEVELOPMENT"

gpp_client-26.7.3.dev2/src/gpp_client/rest/__init__.py

@@ -0,0 +1,8 @@
+"""
+REST API client for non-GraphQL requests.
+"""
+
+from .client import RESTClient
+from .models import VisibilityChanges, parse_visibility_changes
+
+__all__ = ["RESTClient", "VisibilityChanges", "parse_visibility_changes"]

{gpp_client-26.7.3 → gpp_client-26.7.3.dev2}/src/gpp_client/rest/client.py

@@ -8,6 +8,7 @@ import asyncio
 import gzip
 import logging
 import ssl
+from datetime import datetime, timezone
 
 import aiohttp
 import certifi
@@ -102,11 +103,32 @@ class RESTClient:
     async def __aexit__(self, exc_type, exc_val, exc_tb):
         await self.close()
 
-    async def _get_atom_digests(
+    async def get_atom_digests(
         self, observation_ids: list[str], accept_gzip: bool = True
     ) -> str:
         """
         Request atom digests for the given observation IDs.
+
+        Parameters
+        ----------
+        observation_ids : list[str]
+            (internal) IDs of the observation to request.
+
+        accept_gzip : bool
+            Endpoint allows to return a gzip-compressed representation of the
+            complete atoms digest in the case of being too big.
+
+        Returns
+        -------
+        str
+            TSV data as string, one row per line.
+
+        Raises
+        ------
+        aiohttp.ClientResponseError
+            For HTTP error responses.
+        aiohttp.ClientError
+            For connection or timeout failures.
         """
         headers = {}
         if accept_gzip:
@@ -145,3 +167,37 @@ class RESTClient:
                     return await response.text()
             else:
                 return await response.text()
+
+    async def get_visibility_changes(self, since: datetime) -> str:
+        """
+        Request observations and targets with visibility changes since a time.
+
+        Parameters
+        ----------
+        since : datetime
+            Return entities whose visibility-relevant inputs changed at or
+            after this time. Naive datetimes are assumed to be UTC.
+
+        Returns
+        -------
+        str
+            TSV data as string, one ``<gid>\\t<iso8601-timestamp>`` per line.
+
+        Raises
+        ------
+        aiohttp.ClientResponseError
+            For HTTP error responses.
+        aiohttp.ClientError
+            For connection or timeout failures.
+        """
+        if since.tzinfo is None:
+            since = since.replace(tzinfo=timezone.utc)
+
+        session = await self.get_session()
+
+        async with session.get(
+            "/scheduler/visibility-changes",
+            params={"since": since.astimezone(timezone.utc).isoformat()},
+        ) as response:
+            response.raise_for_status()
+            return await response.text()

gpp_client-26.7.3.dev2/src/gpp_client/rest/models.py

@@ -0,0 +1,89 @@
+"""
+Models and parsers for REST API responses.
+"""
+
+__all__ = ["VisibilityChanges", "parse_visibility_changes"]
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class VisibilityChanges:
+    """
+    Observations and targets whose visibility-relevant inputs changed.
+
+    Attributes
+    ----------
+    observation_ids : frozenset[str]
+        Observation GIDs (``o-`` prefix) with visibility changes.
+    target_ids : frozenset[str]
+        Target GIDs (``t-`` prefix) with visibility changes.
+    max_timestamp : datetime | None
+        Latest change timestamp reported by the endpoint, or None when no
+        parseable timestamps were returned.
+    """
+
+    observation_ids: frozenset[str] = field(default_factory=frozenset)
+    target_ids: frozenset[str] = field(default_factory=frozenset)
+    max_timestamp: datetime | None = None
+
+
+def parse_visibility_changes(body: str) -> VisibilityChanges:
+    """
+    Parse the TSV body of ``/scheduler/visibility-changes``.
+
+    Each line is ``<gid>\\t<iso8601-timestamp>`` where the GID prefix
+    disambiguate the entity: ``o-`` for observations, ``t-`` for targets.
+    Malformed lines and unknown prefixes are skipped with a warning; a bad
+    timestamp keeps the GID but does not contribute to ``max_timestamp``.
+
+    Parameters
+    ----------
+    body : str
+        Raw TSV response body.
+
+    Returns
+    -------
+    VisibilityChanges
+        Parsed observation/target GIDs and the latest change timestamp.
+    """
+    observation_ids: set[str] = set()
+    target_ids: set[str] = set()
+    max_timestamp: datetime | None = None
+
+    for line in body.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        gid, _, raw_timestamp = line.partition("\t")
+        gid = gid.strip()
+
+        if gid.startswith("o-"):
+            observation_ids.add(gid)
+        elif gid.startswith("t-"):
+            target_ids.add(gid)
+        else:
+            logger.warning(
+                "Skipping visibility-changes line with unknown GID: %r", line
+            )
+            continue
+
+        try:
+            timestamp = datetime.fromisoformat(
+                raw_timestamp.strip().replace("Z", "+00:00")
+            )
+        except ValueError:
+            logger.warning("Unparseable timestamp in visibility-changes line: %r", line)
+            continue
+        if max_timestamp is None or timestamp > max_timestamp:
+            max_timestamp = timestamp
+
+    return VisibilityChanges(
+        observation_ids=frozenset(observation_ids),
+        target_ids=frozenset(target_ids),
+        max_timestamp=max_timestamp,
+    )

gpp_client-26.7.3/src/gpp_client/rest/__init__.py

@@ -1,7 +0,0 @@
-"""
-REST API client for non-GraphQL requests.
-"""
-
-from .client import RESTClient
-
-__all__ = ["RESTClient"]