initial mosaics cli + async client

Author: ischneider

docs/python/sdk-reference.md

@@ -10,6 +10,10 @@ title: Python SDK API Reference
     rendering:
       show_root_full_path: false
 
+## ::: planet.MosaicsClient
+    rendering:
+      show_root_full_path: false
+
 ## ::: planet.OrdersClient
     rendering:
       show_root_full_path: false
@@ -37,5 +41,3 @@ title: Python SDK API Reference
 ## ::: planet.reporting
     rendering:
       show_root_full_path: false
-
-

examples/mosaics-cli.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+echo -e "Global Basemap Series"
+planet mosaics series list --name-contains=Global | jq .[].name
+
+echo -e "\nLatest Global Monthly"
+planet mosaics series list-mosaics "Global Monthly" --latest --pretty
+
+echo -e "\nHow Many Quads?"
+planet mosaics search 09462e5a-2af0-4de3-a710-e9010d8d4e58 --bbox=-100,40,-100,40.1
+
+echo -e "\nWhat Scenes Contributed to Quad?"
+planet mosaics contributions 09462e5a-2af0-4de3-a710-e9010d8d4e58 455-1273
+
+echo -e "\nDownload Them!"
+planet mosaics download 09462e5a-2af0-4de3-a710-e9010d8d4e58 --bbox=-100,40,-100,40.1 --output-dir=quads

planet/__init__.py

@@ -16,7 +16,7 @@
 from . import data_filter, order_request, reporting, subscription_request
 from .__version__ import __version__  # NOQA
 from .auth import Auth
-from .clients import DataClient, FeaturesClient, OrdersClient, SubscriptionsClient  # NOQA
+from .clients import DataClient, FeaturesClient, MosaicsClient, OrdersClient, SubscriptionsClient  # NOQA
 from .io import collect
 from .sync import Planet
 
@@ -26,6 +26,7 @@
     'DataClient',
     'data_filter',
     'FeaturesClient',
+    'MosaicsClient',
     'OrdersClient',
     'order_request',
     'Planet',

planet/cli/cli.py

@@ -19,6 +19,7 @@
 import click
 
 import planet
+from planet.cli import mosaics
 
 from . import auth, collect, data, orders, subscriptions, features
 
@@ -79,3 +80,4 @@ def _configure_logging(verbosity):
 main.add_command(subscriptions.subscriptions)  # type: ignore
 main.add_command(collect.collect)  # type: ignore
 main.add_command(features.features)
+main.add_command(mosaics.mosaics)

planet/cli/mosaics.py

@@ -0,0 +1,279 @@
+import asyncio
+from contextlib import asynccontextmanager
+
+import click
+
+from planet.cli.cmds import command
+from planet.cli.io import echo_json
+from planet.cli.session import CliSession
+from planet.cli.types import BoundingBox, DateTime, Geometry
+from planet.cli.validators import check_geom
+from planet.clients.mosaics import MosaicsClient
+
+
+@asynccontextmanager
+async def client(ctx):
+    async with CliSession() as sess:
+        cl = MosaicsClient(sess, base_url=ctx.obj['BASE_URL'])
+        yield cl
+
+
+include_links = click.option("--links",
+                             is_flag=True,
+                             help=("If enabled, include API links"))
+
+name_contains = click.option(
+    "--name-contains",
+    type=str,
+    help=("Match if the name contains text, case-insensitive"))
+
+bbox = click.option('--bbox',
+                    type=BoundingBox(),
+                    help=("Region to download as comma-delimited strings: "
+                          " lon_min,lat_min,lon_max,lat_max"))
+
+interval = click.option("--interval",
+                        type=str,
+                        help=("Match this interval, e.g. 1 mon"))
+
+acquired_gt = click.option("--acquired_gt",
+                           type=DateTime(),
+                           help=("Imagery acquisition after than this date"))
+
+acquired_lt = click.option("--acquired_lt",
+                           type=DateTime(),
+                           help=("Imagery acquisition before than this date"))
+
+geometry = click.option('--geometry',
+                        type=Geometry(),
+                        callback=check_geom,
+                        help=("A geojson geometry to search with. "
+                              "Can be a string, filename, or - for stdin."))
+
+
+def _strip_links(resource):
+    if isinstance(resource, dict):
+        resource.pop("_links", None)
+    return resource
+
+
+async def _output(result, pretty, include_links=False):
+    if asyncio.iscoroutine(result):
+        result = await result
+        if result is None:
+            raise click.ClickException("not found")
+        if not include_links:
+            _strip_links(result)
+        echo_json(result, pretty)
+    else:
+        results = [_strip_links(r) async for r in result]
+        echo_json(results, pretty)
+
+
+@click.group()  # type: ignore
+@click.pass_context
+@click.option('-u',
+              '--base-url',
+              default=None,
+              help='Assign custom base Mosaics API URL.')
+def mosaics(ctx, base_url):
+    """Commands for interacting with the Mosaics API"""
+    ctx.obj['BASE_URL'] = base_url
+
+
+@mosaics.group()  # type: ignore
+def series():
+    """Commands for interacting with Mosaic Series through the Mosaics API"""
+
+
+@command(mosaics, name="contributions")
+@click.argument("name")
+@click.argument("quad")
+async def quad_contributions(ctx, name, quad, pretty):
+    '''Get contributing scenes for a mosaic quad
+
+    Example:
+
+    planet mosaics contribution global_monthly_2025_04_mosaic 575-1300
+    '''
+    async with client(ctx) as cl:
+        item = await cl.get_quad(name, quad)
+        await _output(cl.get_quad_contributions(item), pretty)
+
+
+@command(mosaics, name="info")
+@click.argument("name", required=True)
+@include_links
+async def mosaic_info(ctx, name, pretty, links):
+    """Get information for a specific mosaic
+
+    Example:
+
+    planet mosaics info global_monthly_2025_04_mosaic
+    """
+    async with client(ctx) as cl:
+        await _output(cl.get_mosaic(name), pretty, links)
+
+
+@command(mosaics, name="list")
+@name_contains
+@interval
+@acquired_gt
+@acquired_lt
+@include_links
+async def mosaics_list(ctx,
+                       name_contains,
+                       interval,
+                       acquired_gt,
+                       acquired_lt,
+                       pretty,
+                       links):
+    """List all mosaics
+
+    Example:
+
+    planet mosaics info global_monthly_2025_04_mosaic
+    """
+    async with client(ctx) as cl:
+        await _output(
+            cl.list_mosaics(name_contains=name_contains,
+                            interval=interval,
+                            acquired_gt=acquired_gt,
+                            acquired_lt=acquired_lt),
+            pretty,
+            links)
+
+
+@command(series, name="info")
+@click.argument("name", required=True)
+@include_links
+async def series_info(ctx, name, pretty, links):
+    """Get information for a specific series
+
+    Example:
+
+    planet series info "Global Quarterly"
+    """
+    async with client(ctx) as cl:
+        await _output(cl.get_series(name), pretty, links)
+
+
+@command(series, name="list")
+@name_contains
+@interval
+@acquired_gt
+@acquired_lt
+@include_links
+async def series_list(ctx,
+                      name_contains,
+                      interval,
+                      acquired_gt,
+                      acquired_lt,
+                      pretty,
+                      links):
+    """List series
+
+    Example:
+
+    planet mosaics series list --name-contains=Global
+    """
+    async with client(ctx) as cl:
+        await _output(
+            cl.list_series(
+                name_contains,
+                interval,
+                acquired_gt,
+                acquired_lt,
+            ),
+            pretty,
+            links)
+
+
+@command(series, name="list-mosaics")
+@click.argument("name", required=True)
+@click.option("--latest",
+              is_flag=True,
+              help=("Get the latest mosaic in the series"))
+@acquired_gt
+@acquired_lt
+@include_links
+async def list_series_mosaics(ctx,
+                              name,
+                              acquired_gt,
+                              acquired_lt,
+                              latest,
+                              links,
+                              pretty):
+    """List mosaics in a series
+
+    Example:
+
+    planet mosaics series list-mosaics global_monthly_2025_04_mosaic
+    """
+    async with client(ctx) as cl:
+        await _output(
+            cl.list_series_mosaics(name,
+                                   acquired_gt=acquired_gt,
+                                   acquired_lt=acquired_lt,
+                                   latest=latest),
+            pretty,
+            links)
+
+
+@command(mosaics, name="search")
+@click.argument("name", required=True)
+@bbox
+@geometry
+@click.option("--summary",
+              is_flag=True,
+              help=("Get a count of how many quads would be returned"))
+@include_links
+async def list_quads(ctx, name, bbox, geometry, summary, links, pretty):
+    """Search quads
+
+    Example:
+
+    planet mosaics search global_monthly_2025_04_mosaic --bbox -100,40,-100,41
+    """
+    async with client(ctx) as cl:
+        mosaic = await cl.get_mosaic(name)
+        if mosaic is None:
+            raise click.ClickException("No mosaic named " + name)
+        await _output(
+            cl.list_quads(mosaic,
+                          minimal=False,
+                          bbox=bbox,
+                          geometry=geometry,
+                          summary=summary),
+            pretty,
+            links)
+
+
+@command(mosaics, name="download")
+@click.argument("name", required=True)
+@click.option('--output-dir',
+              default='.',
+              help=('Directory for file download.'),
+              type=click.Path(exists=True,
+                              resolve_path=True,
+                              writable=True,
+                              file_okay=False))
+@bbox
+@geometry
+async def download(ctx, name, output_dir, bbox, geometry, **kwargs):
+    """Download quads from a mosaic
+
+    Example:
+
+    planet mosaics search global_monthly_2025_04_mosaic --bbox -100,40,-100,41
+    """
+    quiet = ctx.obj['QUIET']
+    async with client(ctx) as cl:
+        mosaic = await cl.get_mosaic(name)
+        if mosaic is None:
+            raise click.ClickException("No mosaic named " + name)
+        await cl.download_quads(mosaic,
+                                bbox=bbox,
+                                geometry=geometry,
+                                directory=output_dir,
+                                progress_bar=not quiet)

planet/cli/types.py

@@ -140,3 +140,14 @@ def convert(self, value, param, ctx) -> datetime:
                 self.fail(str(e))
 
         return value
+
+
+class BoundingBox(click.ParamType):
+    name = 'bbox'
+
+    def convert(self, val, param, ctx):
+        try:
+            xmin, ymin, xmax, ymax = map(float, val.split(','))
+        except (TypeError, ValueError):
+            raise click.BadParameter('Invalid bounding box')
+        return (xmin, ymin, xmax, ymax)

planet/clients/__init__.py

@@ -14,17 +14,23 @@
 # limitations under the License.
 from .data import DataClient
 from .features import FeaturesClient
+from .mosaics import MosaicsClient
 from .orders import OrdersClient
 from .subscriptions import SubscriptionsClient
 
 __all__ = [
-    'DataClient', 'FeaturesClient', 'OrdersClient', 'SubscriptionsClient'
+    'DataClient',
+    'FeaturesClient',
+    'MosaicsClient',
+    'OrdersClient',
+    'SubscriptionsClient'
 ]
 
 # Organize client classes by their module name to allow lookup.
 _client_directory = {
     'data': DataClient,
     'features': FeaturesClient,
+    'mosaics': MosaicsClient,
     'orders': OrdersClient,
     'subscriptions': SubscriptionsClient
 }

planet/clients/mosaics.py

@@ -0,0 +1,397 @@
+import asyncio
+from pathlib import Path
+from typing import AsyncIterator, Awaitable, Optional, Tuple, Type, TypeVar, Union, cast
+from planet.constants import PLANET_BASE_URL
+from planet.http import Session
+from planet.models import Paged, Response, StreamingBody
+from uuid import UUID
+
+BASE_URL = f'{PLANET_BASE_URL}/basemaps/v1'
+
+T = TypeVar("T")
+
+Number = Union[int, float]
+
+BBox = Tuple[Number, Number, Number, Number]
+
+
+class Series(Paged):
+    ITEMS_KEY = 'series'
+    NEXT_KEY = '_next'
+
+
+class Mosaics(Paged):
+    ITEMS_KEY = 'mosaics'
+    NEXT_KEY = '_next'
+
+
+class MosaicQuads(Paged):
+    ITEMS_KEY = 'items'
+    NEXT_KEY = '_next'
+
+
+def _is_uuid(val: str) -> bool:
+    try:
+        UUID(val)
+        return True
+    except ValueError:
+        return False
+
+
+class MosaicsClient:
+    """High-level asynchronous access to Planet's Mosaics API.
+
+    Example:
+        ```python
+        >>> import asyncio
+        >>> from planet import Session
+        >>>
+        >>> async def main():
+        ...     async with Session() as sess:
+        ...         cl = sess.client('data')
+        ...         # use client here
+        ...
+        >>> asyncio.run(main())
+        ```
+    """
+
+    def __init__(self, session: Session, base_url: Optional[str] = None):
+        """
+        Parameters:
+            session: Open session connected to server.
+            base_url: The base URL to use. Defaults to production orders API
+                base url.
+        """
+        self._session = session
+
+        self._base_url = base_url or BASE_URL
+        if self._base_url.endswith('/'):
+            self._base_url = self._base_url[:-1]
+
+    def _call_sync(self, f: Awaitable[T]) -> T:
+        """block on an async function call, using the call_sync method of the session"""
+        return self._session._call_sync(f)
+
+    def _url(self, path: str) -> str:
+        return f"{BASE_URL}/{path}"
+
+    async def _get_by_name(self, path: str, pager: Type[Paged],
+                           name: str) -> Optional[dict]:
+        response = await self._session.request(
+            method='GET',
+            url=self._url(path),
+            params={
+                "name__is": name,
+            },
+        )
+        listing = response.json()[pager.ITEMS_KEY]
+        return listing[0] if listing else None
+
+    async def _get_by_id(self, path: str, id: str) -> dict:
+        response = await self._session.request(method="GET",
+                                               url=self._url(f"{path}/{id}"))
+        return response.json()
+
+    async def _get(self, name_or_id: str, path: str,
+                   pager: Type[Paged]) -> Optional[dict]:
+        if _is_uuid(name_or_id):
+            return await self._get_by_id(path, name_or_id)
+        return await self._get_by_name(path, pager, name_or_id)
+
+    async def get_mosaic(self, name_or_id: str) -> Optional[dict]:
+        """Get the API representation of a mosaic by name or id.
+
+        :param name str: The name or id of the mosaic
+        :returns: dict or None (if searching by name)
+        :raises planet.api.exceptions.APIException: On API error.
+        """
+        return await self._get(name_or_id, "mosaics", Mosaics)
+
+    async def get_series(self, name_or_id: str) -> Optional[dict]:
+        """Get the API representation of a series by name or id.
+
+        :param name str: The name or id of the series
+        :returns: dict or None (if searching by name)
+        :raises planet.api.exceptions.APIException: On API error.
+        """
+        return await self._get(name_or_id, "series", Series)
+
+    async def list_series(
+            self,
+            name_contains: Optional[str] = None,
+            interval: Optional[str] = None,
+            acquired_gt: Optional[str] = None,
+            acquired_lt: Optional[str] = None) -> AsyncIterator[dict]:
+        """
+        List the series you have access to.
+
+        Example:
+
+        ```
+        series = await client.list_series()
+        async for s in series:
+            print(s)
+        ```
+        """
+        params = {}
+        if name_contains:
+            params["name__contains"] = name_contains
+        if interval:
+            params["interval"] = interval
+        if acquired_gt:
+            params["acquired__gt"] = acquired_gt
+        if acquired_lt:
+            params["acquired__lt"] = acquired_lt
+        resp = await self._session.request(
+            method='GET',
+            url=self._url("series"),
+            params=params,
+        )
+        async for item in Series(resp, self._session.request):
+            yield item
+
+    async def list_mosaics(
+        self,
+        name_contains: Optional[str] = None,
+        interval: Optional[str] = None,
+        acquired_gt: Optional[str] = None,
+        acquired_lt: Optional[str] = None,
+        latest: bool = False,
+    ) -> AsyncIterator[dict]:
+        """
+        List the mosaics you have access to.
+
+        Example:
+
+        ```
+        mosaics = await client.list_mosacis()
+        async for m in mosaics:
+            print(m)
+        ```
+        """
+        params = {}
+        if name_contains:
+            params["name__contains"] = name_contains
+        if interval:
+            params["interval"] = interval
+        if acquired_gt:
+            params["acquired__gt"] = acquired_gt
+        if acquired_lt:
+            params["acquired__lt"] = acquired_lt
+        if latest:
+            params["latest"] = "yes"
+        resp = await self._session.request(
+            method='GET',
+            url=self._url("mosaics"),
+            params=params,
+        )
+        async for item in Mosaics(resp, self._session.request):
+            yield item
+
+    async def list_series_mosaics(
+        self,
+        name_or_id: str,
+        acquired_gt: Optional[str] = None,
+        acquired_lt: Optional[str] = None,
+        latest: bool = False,
+    ) -> AsyncIterator[dict]:
+        """
+        List the mosaics in a series.
+
+        Example:
+
+        ```
+        mosaics = await client.list_series_mosaics("d5098531-aa4f-4ff9-a9d5-74ad4a6301e5")
+        async for m in mosaics:
+            print(m)
+        ```
+        """
+        if not _is_uuid(name_or_id):
+            series = await self._get_by_name("series", Series, name_or_id)
+            if series is None:
+                return
+            name_or_id = series["id"]
+        params = {}
+        if acquired_gt:
+            params["acquired__gt"] = acquired_gt
+        if acquired_lt:
+            params["acquired__lt"] = acquired_lt
+        if latest:
+            params["latest"] = "yes"
+        resp = await self._session.request(
+            method="GET",
+            url=self._url(f"series/{name_or_id}/mosaics"),
+            params=params,
+        )
+        async for item in Mosaics(resp, self._session.request):
+            yield item
+
+    async def list_quads(self,
+                         mosaic: dict,
+                         minimal: bool = False,
+                         bbox: Optional[BBox] = None,
+                         geometry: Optional[dict] = None,
+                         summary: bool = False) -> AsyncIterator[dict]:
+        """
+        List the a mosaic's quads.
+
+        Example:
+
+        ```
+        mosaic = await client.get_mosaic("d5098531-aa4f-4ff9-a9d5-74ad4a6301e5")
+        quads = await client.list_quads(mosaic)
+        async for q in quads:
+            print(q)
+        ```
+        """
+        if geometry:
+            resp = await self._quads_geometry(mosaic,
+                                              geometry,
+                                              minimal,
+                                              summary)
+        else:
+            if bbox is None:
+                xmin, ymin, xmax, ymax = cast(BBox, mosaic['bbox'])
+                search = (max(-180, xmin),
+                          max(-85, ymin),
+                          min(180, xmax),
+                          min(85, ymax))
+            else:
+                search = bbox
+            resp = await self._quads_bbox(mosaic, search, minimal, summary)
+        # kinda yucky - yields a different "shaped" dict
+        if summary:
+            yield resp.json()["summary"]
+            return
+        async for item in MosaicQuads(resp, self._session.request):
+            yield item
+
+    async def _quads_geometry(self,
+                              mosaic: dict,
+                              geometry: dict,
+                              minimal: bool,
+                              summary: bool) -> Response:
+        params = {}
+        if minimal:
+            params["minimal"] = "true"
+        if summary:
+            params["summary"] = "true"
+        mosaic_id = mosaic["id"]
+        return await self._session.request(
+            method="POST",
+            url=self._url(f"mosaics/{mosaic_id}/quads/search"),
+            params=params,
+            json=geometry,
+        )
+
+    async def _quads_bbox(self,
+                          mosaic: dict,
+                          bbox: BBox,
+                          minimal: bool,
+                          summary: bool) -> Response:
+        quads_template = mosaic["_links"]["quads"]
+        # this is fully qualified URL, so don't use self._url
+        url = quads_template.replace("{lx},{ly},{ux},{uy}",
+                                     ",".join([str(f) for f in bbox]))
+        # params will overwrite the templated query
+        if minimal:
+            url += "&minimal=true"
+        if summary:
+            url += "&summary=true"
+        return await self._session.request(
+            method="GET",
+            url=url,
+        )
+
+    async def get_quad(self, name_or_id: str, quad_id: str) -> dict:
+        """
+        Get a mosaic's quad information.
+
+        Example:
+
+        ```
+        quad = await client.get_quad("d5098531-aa4f-4ff9-a9d5-74ad4a6301e5", "1234-5678")
+        print(quad)
+        ```
+        """
+        if not _is_uuid(name_or_id):
+            mosaic = await self.get_mosaic(name_or_id)
+            if mosaic is None:
+                return {}
+            name_or_id = cast(str, mosaic["id"])
+        resp = await self._session.request(
+            method="GET",
+            url=self._url(f"mosaics/{name_or_id}/quads/{quad_id}"),
+        )
+        return resp.json()
+
+    async def get_quad_contributions(self, quad: dict) -> list[dict]:
+        """
+        Get a mosaic's quad information.
+
+        Example:
+
+        ```
+        quad = await client.get_quad("d5098531-aa4f-4ff9-a9d5-74ad4a6301e5", "1234-5678")
+        contributions = await client.get_quad_contributions(quad)
+        print(contributions)
+        ```
+        """
+        resp = await self._session.request(
+            "GET",
+            quad["_links"]["items"],
+        )
+        return resp.json()["items"]
+
+    async def download_quad(self,
+                            quad: dict,
+                            directory,
+                            overwrite: bool = False,
+                            progress_bar=False):
+        url = quad["_links"]["download"]
+        Path(directory).mkdir(exist_ok=True, parents=True)
+        async with self._session.stream(method='GET', url=url) as resp:
+            body = StreamingBody(resp)
+            dest = Path(directory, body.name)
+            await body.write(dest,
+                             overwrite=overwrite,
+                             progress_bar=progress_bar)
+        """
+        Download a quad to a directory.
+
+        Example:
+
+        ```
+        quad = await client.get_quad("d5098531-aa4f-4ff9-a9d5-74ad4a6301e5", "1234-5678")
+        await client.download_quad(quad, ".")
+        ```
+        """
+
+    async def download_quads(self,
+                             mosaic: dict,
+                             directory: str,
+                             bbox: Optional[BBox] = None,
+                             geometry: Optional[dict] = None,
+                             progress_bar: bool = False,
+                             concurrency: int = 4):
+        """
+        Download a mosaics' quads to a directory.
+
+        Example:
+
+        ```
+        mosaic = await cl.get_mosaic(name)
+        client.download_quads(mosaic, '.', bbox=(-100, 40, -100, 41))
+        ```
+        """
+        jobs = []
+        async for q in self.list_quads(mosaic,
+                                       minimal=True,
+                                       bbox=bbox,
+                                       geometry=geometry):
+            jobs.append(
+                self.download_quad(q, directory, progress_bar=progress_bar))
+            if len(jobs) == concurrency:
+                await asyncio.gather(*jobs)
+                jobs = []
+        await asyncio.gather(*jobs)