earthscope-sdk 1.0.0b1__py3-none-any.whl → 1.2.0b0__py3-none-any.whl

earthscope_sdk/client/data_access/_service.py

@@ -0,0 +1,114 @@
+import datetime as dt
+from typing import TYPE_CHECKING, Optional
+
+from earthscope_sdk.client.data_access._base import DataAccessBaseService
+from earthscope_sdk.client.data_access._query_plan._gnss_observations import (
+    AsyncGnssObservationsQueryPlan,
+    GnssObservationField,
+    GnssObservationsMetaField,
+    GnssObservationsQueryPlan,
+    SatelliteSystem,
+)
+from earthscope_sdk.util._types import ListOrItem
+
+if TYPE_CHECKING:
+    from earthscope_sdk.client._client import AsyncEarthScopeClient
+
+
+class _DataAccessService(DataAccessBaseService):
+    """
+    L2 data access service functionality
+    """
+
+    def __init__(self, client: "AsyncEarthScopeClient"):
+        super().__init__(client._ctx)
+        self._client = client
+
+    def _gnss_observations(
+        self,
+        *,
+        # observation parameters
+        start_datetime: dt.datetime,
+        end_datetime: dt.datetime,
+        system: ListOrItem[SatelliteSystem] = [],
+        satellite: ListOrItem[str] = [],
+        obs_code: ListOrItem[str] = [],
+        field: ListOrItem[GnssObservationField] = [],
+        # session parameters
+        network_name: ListOrItem[str] = [],
+        network_edid: ListOrItem[str] = [],
+        station_name: ListOrItem[str] = [],
+        station_edid: ListOrItem[str] = [],
+        session_name: ListOrItem[str] = [],
+        session_edid: ListOrItem[str] = [],
+        roll: Optional[dt.timedelta] = None,
+        sample_interval: Optional[dt.timedelta] = None,
+        # metadata parameters
+        meta_fields: ListOrItem[GnssObservationsMetaField] = ["igs"],
+    ):
+        """
+        Retrieve GNSS observations.
+
+        Args:
+            start_datetime: The start datetime to retrieve observations for.
+            end_datetime: The end datetime to retrieve observations for.
+            system: The system(s) to retrieve observations for.
+            satellite: The satellite(s) to retrieve observations for.
+            obs_code: The observation code(s) to retrieve observations for.
+            field: The observation field(s) to retrieve.
+            network_name: The network name to retrieve observations for.
+            network_edid: The network edid to retrieve observations for.
+            station_name: The station name to retrieve observations for.
+            station_edid: The station edid to retrieve observations for.
+            session_name: The session name to retrieve observations for.
+            session_edid: The session edid to retrieve observations for.
+            roll: The session roll to retrieve observations for.
+            sample_interval: The session sample interval to retrieve observations for.
+            meta_fields: Metadata fields to add to the table.
+
+        Returns:
+            A query plan for GNSS observations.
+        """
+
+        return AsyncGnssObservationsQueryPlan(
+            client=self._client,
+            start_datetime=start_datetime,
+            end_datetime=end_datetime,
+            system=system,
+            satellite=satellite,
+            obs_code=obs_code,
+            field=field,
+            network_name=network_name,
+            network_edid=network_edid,
+            station_name=station_name,
+            station_edid=station_edid,
+            session_name=session_name,
+            session_edid=session_edid,
+            roll=roll,
+            sample_interval=sample_interval,
+            meta_fields=meta_fields,
+        )
+
+
+class AsyncDataAccessService(_DataAccessService):
+    """
+    Data access functionality
+    """
+
+    def __init__(self, client: "AsyncEarthScopeClient"):
+        super().__init__(client)
+
+        self.gnss_observations = self._gnss_observations
+
+
+class DataAccessService(_DataAccessService):
+    """
+    Data access functionality
+    """
+
+    def __init__(self, client: "AsyncEarthScopeClient"):
+        super().__init__(client)
+
+        self.gnss_observations = GnssObservationsQueryPlan._syncify_query_plan(
+            self._gnss_observations
+        )

earthscope_sdk/client/discovery/_base.py

@@ -0,0 +1,303 @@
+import datetime as dt
+from typing import Optional, Union
+
+from earthscope_sdk.client.discovery.models import (
+    ListNetworkDatasourcesResult,
+    ListSessionDatasourcesResult,
+    ListStationDatasourcesResult,
+    ListStreamDatasourcesResult,
+    NetworkDatasource,
+    Page,
+    SessionDatasource,
+    StationDatasource,
+    StreamDatasource,
+    StreamType,
+)
+from earthscope_sdk.common.service import SdkService
+from earthscope_sdk.util._itertools import to_list
+from earthscope_sdk.util._types import ListOrItem
+
+
+class DiscoveryBaseService(SdkService):
+    """
+    Discovery service functionality
+    """
+
+    async def _list_network_datasources(
+        self,
+        *,
+        network_name: Optional[ListOrItem[str]] = None,
+        network_edid: Optional[ListOrItem[str]] = None,
+        with_edid_only=False,
+        limit=50,
+        offset=0,
+    ) -> Union[Page[NetworkDatasource], Page[str]]:
+        """
+        List network datasources
+
+        Args:
+            network_name: The name(s) of the network to list datasources for.
+            network_edid: The EDID(s) of the network to list datasources for.
+            with_edid_only: Whether to return only the EDIDs of the datasources.
+            limit: The maximum number of datasources to return.
+            offset: The offset to start the list from.
+
+        Returns:
+            A list of network datasources.
+        """
+        params = {
+            "with_edid_only": with_edid_only,
+            "limit": limit,
+            "offset": offset,
+        }
+
+        if network_name:
+            params["network_name"] = to_list(network_name)
+
+        if network_edid:
+            params["network_edid"] = to_list(network_edid)
+
+        req = self.ctx.httpx_client.build_request(
+            method="GET",
+            url=f"{self.resources.api_url}beta/discover/datasource/network",
+            params=params,
+        )
+
+        resp = await self._send_with_retries(req)
+
+        return ListNetworkDatasourcesResult.validate_json(resp.content)
+
+    async def _list_station_datasources(
+        self,
+        *,
+        network_name: Optional[ListOrItem[str]] = None,
+        network_edid: Optional[ListOrItem[str]] = None,
+        station_name: Optional[ListOrItem[str]] = None,
+        station_edid: Optional[ListOrItem[str]] = None,
+        with_edid_only=False,
+        with_parent_edids=False,
+        limit=50,
+        offset=0,
+    ) -> Union[Page[StationDatasource], Page[str]]:
+        """
+        List station datasources
+
+        Args:
+            network_name: The name(s) of the network to list datasources for.
+            network_edid: The EDID(s) of the network to list datasources for.
+            station_name: The name(s) of the station to list datasources for.
+            station_edid: The EDID(s) of the station to list datasources for.
+            with_edid_only: Whether to return only the EDIDs of the datasources.
+            with_parent_edids: Whether to return the parent EDIDs of the datasources.
+            limit: The maximum number of datasources to return.
+            offset: The offset to start the list from.
+
+        Returns:
+            A list of station datasources.
+        """
+        params = {
+            "with_edid_only": with_edid_only,
+            "with_parent_edids": with_parent_edids,
+            "limit": limit,
+            "offset": offset,
+        }
+
+        if network_name:
+            params["network_name"] = to_list(network_name)
+
+        if network_edid:
+            params["network_edid"] = to_list(network_edid)
+
+        if station_name:
+            params["station_name"] = to_list(station_name)
+
+        if station_edid:
+            params["station_edid"] = to_list(station_edid)
+
+        req = self.ctx.httpx_client.build_request(
+            method="GET",
+            url=f"{self.resources.api_url}beta/discover/datasource/station",
+            params=params,
+        )
+
+        resp = await self._send_with_retries(req)
+
+        return ListStationDatasourcesResult.validate_json(resp.content)
+
+    async def _list_session_datasources(
+        self,
+        *,
+        network_name: Optional[ListOrItem[str]] = None,
+        network_edid: Optional[ListOrItem[str]] = None,
+        station_name: Optional[ListOrItem[str]] = None,
+        station_edid: Optional[ListOrItem[str]] = None,
+        session_name: Optional[ListOrItem[str]] = None,
+        session_edid: Optional[ListOrItem[str]] = None,
+        sample_interval: Optional[dt.timedelta] = None,
+        roll: Optional[dt.timedelta] = None,
+        with_edid_only=False,
+        with_parents=False,
+        with_parent_edids=False,
+        limit=50,
+        offset=0,
+    ) -> Union[Page[SessionDatasource], Page[str]]:
+        """
+        List session datasources
+
+        Args:
+            network_name: The name(s) of the network to list datasources for.
+            network_edid: The EDID(s) of the network to list datasources for.
+            station_name: The name(s) of the station to list datasources for.
+            station_edid: The EDID(s) of the station to list datasources for.
+            session_name: The name(s) of the session to list datasources for.
+            session_edid: The EDID(s) of the session to list datasources for.
+            sample_interval: The sample interval to list datasources for.
+            roll: The roll to list datasources for.
+            with_edid_only: Whether to return only the EDIDs of the datasources.
+            with_parents: Whether to return the parent datasources.
+            with_parent_edids: Whether to return the parent EDIDs of the datasources.
+            limit: The maximum number of datasources to return.
+            offset: The offset to start the list from.
+
+        Returns:
+            A list of session datasources.
+        """
+        params = {
+            "with_edid_only": with_edid_only,
+            "with_parents": with_parents,
+            "with_parent_edids": with_parent_edids,
+            "limit": limit,
+            "offset": offset,
+        }
+
+        if network_name:
+            params["network_name"] = to_list(network_name)
+
+        if network_edid:
+            params["network_edid"] = to_list(network_edid)
+
+        if station_name:
+            params["station_name"] = to_list(station_name)
+
+        if station_edid:
+            params["station_edid"] = to_list(station_edid)
+
+        if session_name:
+            params["session_name"] = to_list(session_name)
+
+        if session_edid:
+            params["session_edid"] = to_list(session_edid)
+
+        if sample_interval:
+            # Convert to milliseconds
+            params["sample_interval"] = 1000 * sample_interval.total_seconds()
+
+        if roll:
+            # Convert to seconds
+            params["roll"] = roll.total_seconds()
+
+        req = self.ctx.httpx_client.build_request(
+            method="GET",
+            url=f"{self.resources.api_url}beta/discover/datasource/session",
+            params=params,
+        )
+
+        resp = await self._send_with_retries(req)
+
+        return ListSessionDatasourcesResult.validate_json(resp.content)
+
+    async def _list_stream_datasources(
+        self,
+        *,
+        network_name: Optional[ListOrItem[str]] = None,
+        network_edid: Optional[ListOrItem[str]] = None,
+        station_name: Optional[ListOrItem[str]] = None,
+        station_edid: Optional[ListOrItem[str]] = None,
+        stream_name: Optional[ListOrItem[str]] = None,
+        stream_edid: Optional[ListOrItem[str]] = None,
+        stream_type: Optional[StreamType] = None,
+        facility: Optional[str] = None,
+        software: Optional[str] = None,
+        label: Optional[str] = None,
+        sample_interval: Optional[dt.timedelta] = None,
+        with_edid_only=False,
+        with_parents=False,
+        with_parent_edids=False,
+        limit=50,
+        offset=0,
+    ) -> Union[Page[StreamDatasource], Page[str]]:
+        """
+        List stream datasources
+
+        Args:
+            network_name: The name(s) of the network to list datasources for.
+            network_edid: The EDID(s) of the network to list datasources for.
+            station_name: The name(s) of the station to list datasources for.
+            station_edid: The EDID(s) of the station to list datasources for.
+            stream_name: The name(s) of the stream to list datasources for.
+            stream_edid: The EDID(s) of the stream to list datasources for.
+            stream_type: The type of stream to list datasources for.
+            facility: The facility to list datasources for.
+            software: The software to list datasources for.
+            label: The label to list datasources for.
+            sample_interval: The sample interval to list datasources for.
+            with_edid_only: Whether to return only the EDIDs of the datasources.
+            with_parents: Whether to return the parent datasources.
+            with_parent_edids: Whether to return the parent EDIDs of the datasources.
+            limit: The maximum number of datasources to return.
+            offset: The offset to start the list from.
+
+        Returns:
+            A list of stream datasources.
+        """
+        params = {
+            "with_edid_only": with_edid_only,
+            "with_parents": with_parents,
+            "with_parent_edids": with_parent_edids,
+            "limit": limit,
+            "offset": offset,
+        }
+
+        if network_name:
+            params["network_name"] = to_list(network_name)
+
+        if network_edid:
+            params["network_edid"] = to_list(network_edid)
+
+        if station_name:
+            params["station_name"] = to_list(station_name)
+
+        if station_edid:
+            params["station_edid"] = to_list(station_edid)
+
+        if stream_name:
+            params["stream_name"] = to_list(stream_name)
+
+        if stream_edid:
+            params["stream_edid"] = to_list(stream_edid)
+
+        if stream_type is not None:
+            params["stream_type"] = stream_type.value
+
+        if facility is not None:
+            params["facility"] = facility
+
+        if software is not None:
+            params["software"] = software
+
+        if label is not None:
+            params["label"] = label
+
+        if sample_interval is not None:
+            # Convert to milliseconds
+            params["sample_interval"] = 1000 * sample_interval.total_seconds()
+
+        req = self.ctx.httpx_client.build_request(
+            method="GET",
+            url=f"{self.resources.api_url}beta/discover/datasource/stream",
+            params=params,
+        )
+
+        resp = await self._send_with_retries(req)
+
+        return ListStreamDatasourcesResult.validate_json(resp.content)

earthscope_sdk/client/discovery/_service.py

@@ -0,0 +1,209 @@
+import datetime as dt
+from functools import partial
+from typing import Any, AsyncIterator, Coroutine, Optional, TypeVar, Union
+
+from earthscope_sdk.client.discovery._base import DiscoveryBaseService
+from earthscope_sdk.client.discovery.models import (
+    NetworkDatasource,
+    Page,
+    SessionDatasource,
+    StationDatasource,
+    StreamDatasource,
+    StreamType,
+)
+from earthscope_sdk.common.context import SdkContext
+from earthscope_sdk.util._types import ListOrItem
+
+P = TypeVar("P")
+
+
+class _DiscoveryService(DiscoveryBaseService):
+    """
+    L2 discovery service functionality
+    """
+
+    async def _iter_pages(
+        self,
+        fn: Coroutine[Any, Any, Page[P]],
+        limit: int,
+    ) -> AsyncIterator[Page[P]]:
+        """
+        Iterate over pages of results from a function.
+
+        Args:
+            fn: The function to call to get a page of results.
+            limit: The maximum number of results to return.
+
+        Returns:
+            An iterator over the pages of results.
+        """
+        offset = 0
+        page_size = 100
+        has_next = True
+        result_ct = 0
+
+        while has_next and result_ct < limit:
+            page_size = min(page_size, limit - result_ct)
+            page: Page[P] = await fn(offset=offset, limit=page_size)
+            yield page
+            has_next = page.has_next
+            offset += page_size
+            result_ct += len(page.items)
+
+    async def _load_all_pages(
+        self,
+        fn: Coroutine[Any, Any, Page[P]],
+        limit: int,
+    ) -> list[P]:
+        """
+        Load all pages of results from a function.
+        """
+        results: list[P] = []
+        async for p in self._iter_pages(fn=fn, limit=limit):
+            results.extend(p.items)
+
+        return results
+
+    async def _list_network_datasources(
+        self,
+        *,
+        network_name: Optional[ListOrItem[str]] = None,
+        network_edid: Optional[ListOrItem[str]] = None,
+        with_edid_only=False,
+        limit=1000,
+    ) -> Union[list[NetworkDatasource], list[str]]:
+        return await self._load_all_pages(
+            fn=partial(
+                super()._list_network_datasources,
+                network_name=network_name,
+                network_edid=network_edid,
+                with_edid_only=with_edid_only,
+            ),
+            limit=limit,
+        )
+
+    async def _list_station_datasources(
+        self,
+        *,
+        network_name: Optional[ListOrItem[str]] = None,
+        network_edid: Optional[ListOrItem[str]] = None,
+        station_name: Optional[ListOrItem[str]] = None,
+        station_edid: Optional[ListOrItem[str]] = None,
+        with_edid_only=False,
+        with_parent_edids=False,
+        limit=1000,
+    ) -> Union[list[StationDatasource], list[str]]:
+        return await self._load_all_pages(
+            fn=partial(
+                super()._list_station_datasources,
+                network_name=network_name,
+                network_edid=network_edid,
+                station_name=station_name,
+                station_edid=station_edid,
+                with_edid_only=with_edid_only,
+                with_parent_edids=with_parent_edids,
+            ),
+            limit=limit,
+        )
+
+    async def _list_session_datasources(
+        self,
+        *,
+        network_name: Optional[ListOrItem[str]] = None,
+        network_edid: Optional[ListOrItem[str]] = None,
+        station_name: Optional[ListOrItem[str]] = None,
+        station_edid: Optional[ListOrItem[str]] = None,
+        session_name: Optional[ListOrItem[str]] = None,
+        session_edid: Optional[ListOrItem[str]] = None,
+        sample_interval: Optional[dt.timedelta] = None,
+        roll: Optional[dt.timedelta] = None,
+        with_edid_only=False,
+        with_parents=False,
+        with_parent_edids=False,
+        limit=1000,
+    ) -> Union[list[SessionDatasource], list[str]]:
+        return await self._load_all_pages(
+            fn=partial(
+                super()._list_session_datasources,
+                network_name=network_name,
+                network_edid=network_edid,
+                station_name=station_name,
+                station_edid=station_edid,
+                session_name=session_name,
+                session_edid=session_edid,
+                sample_interval=sample_interval,
+                roll=roll,
+                with_edid_only=with_edid_only,
+                with_parents=with_parents,
+                with_parent_edids=with_parent_edids,
+            ),
+            limit=limit,
+        )
+
+    async def _list_stream_datasources(
+        self,
+        *,
+        network_name: Optional[ListOrItem[str]] = None,
+        network_edid: Optional[ListOrItem[str]] = None,
+        station_name: Optional[ListOrItem[str]] = None,
+        station_edid: Optional[ListOrItem[str]] = None,
+        stream_name: Optional[ListOrItem[str]] = None,
+        stream_edid: Optional[ListOrItem[str]] = None,
+        stream_type: Optional[StreamType] = None,
+        facility: Optional[str] = None,
+        software: Optional[str] = None,
+        label: Optional[str] = None,
+        sample_interval: Optional[dt.timedelta] = None,
+        with_edid_only=False,
+        with_parents=False,
+        with_parent_edids=False,
+        limit=1000,
+    ) -> Union[list[StreamDatasource], list[str]]:
+        return await self._load_all_pages(
+            fn=partial(
+                super()._list_stream_datasources,
+                network_name=network_name,
+                network_edid=network_edid,
+                station_name=station_name,
+                station_edid=station_edid,
+                stream_name=stream_name,
+                stream_edid=stream_edid,
+                stream_type=stream_type,
+                facility=facility,
+                software=software,
+                label=label,
+                sample_interval=sample_interval,
+                with_edid_only=with_edid_only,
+                with_parents=with_parents,
+                with_parent_edids=with_parent_edids,
+            ),
+            limit=limit,
+        )
+
+
+class AsyncDiscoveryService(_DiscoveryService):
+    """
+    Discovery service functionality
+    """
+
+    def __init__(self, ctx: SdkContext):
+        super().__init__(ctx)
+
+        self.list_network_datasources = self._list_network_datasources
+        self.list_station_datasources = self._list_station_datasources
+        self.list_session_datasources = self._list_session_datasources
+        self.list_stream_datasources = self._list_stream_datasources
+
+
+class DiscoveryService(_DiscoveryService):
+    """
+    Discovery service functionality
+    """
+
+    def __init__(self, ctx: SdkContext):
+        super().__init__(ctx)
+
+        self.list_network_datasources = ctx.syncify(self._list_network_datasources)
+        self.list_station_datasources = ctx.syncify(self._list_station_datasources)
+        self.list_session_datasources = ctx.syncify(self._list_session_datasources)
+        self.list_stream_datasources = ctx.syncify(self._list_stream_datasources)