add sync client and tests, minor fixups

Author: ischneider

planet/cli/mosaics.py

@@ -60,8 +60,6 @@ def _strip_links(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)
@@ -236,11 +234,8 @@ async def list_quads(ctx, name_or_id, bbox, geometry, summary, pretty, links):
     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_or_id)
-        if mosaic is None:
-            raise click.ClickException("No mosaic named " + name_or_id)
         await _output(
-            cl.list_quads(mosaic,
+            cl.list_quads(name_or_id,
                           minimal=False,
                           bbox=bbox,
                           geometry=geometry,
@@ -268,10 +263,7 @@ async def download(ctx, name_or_id, output_dir, bbox, geometry, **kwargs):
     """
     quiet = ctx.obj['QUIET']
     async with client(ctx) as cl:
-        mosaic = await cl.get_mosaic(name_or_id)
-        if mosaic is None:
-            raise click.ClickException("No mosaic named " + name_or_id)
-        await cl.download_quads(mosaic,
+        await cl.download_quads(name_or_id,
                                 bbox=bbox,
                                 geometry=geometry,
                                 directory=output_dir,

planet/clients/mosaics.py

@@ -1,10 +1,25 @@
+# Copyright 2025 Planet Labs PBC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
 import asyncio
 from pathlib import Path
-from typing import AsyncIterator, Awaitable, Optional, Tuple, Type, TypeVar, Union, cast
+from typing import AsyncIterator, Optional, Tuple, Type, TypeVar, Union, cast
+from planet.clients.base import _BaseClient
 from planet.constants import PLANET_BASE_URL
 from planet.exceptions import MissingResource
 from planet.http import Session
-from planet.models import Mosaic, Paged, Quad, Response, Series, StreamingBody
+from planet.models import GeoInterface, Mosaic, Paged, Quad, Response, Series, StreamingBody
 from uuid import UUID
 
 BASE_URL = f'{PLANET_BASE_URL}/basemaps/v1'
@@ -39,7 +54,7 @@ def _is_uuid(val: str) -> bool:
         return False
 
 
-class MosaicsClient:
+class MosaicsClient(_BaseClient):
     """High-level asynchronous access to Planet's Mosaics API.
 
     Example:
@@ -49,7 +64,7 @@ class MosaicsClient:
         >>>
         >>> async def main():
         ...     async with Session() as sess:
-        ...         cl = sess.client('data')
+        ...         cl = sess.client('mosaics')
         ...         # use client here
         ...
         >>> asyncio.run(main())
@@ -63,18 +78,10 @@ def __init__(self, session: Session, base_url: Optional[str] = None):
             base_url: The base URL to use. Defaults to production Mosaics
                 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)
+        super().__init__(session, base_url or BASE_URL)
 
     def _url(self, path: str) -> str:
-        return f"{BASE_URL}/{path}"
+        return f"{self._base_url}/{path}"
 
     async def _get_by_name(self, path: str, pager: Type[Paged],
                            name: str) -> dict:
@@ -88,7 +95,12 @@ async def _get_by_name(self, path: str, pager: Type[Paged],
         listing = response.json()[pager.ITEMS_KEY]
         if len(listing):
             return listing[0]
-        raise MissingResource(f"{name} not found")
+        # mimic the response for 404 when search is empty
+        resource = "Mosaic"
+        if path == "series":
+            resource = "Series"
+        raise MissingResource('{"message":"%s Not Found: %s"}' %
+                              (resource, name))
 
     async def _get_by_id(self, path: str, id: str) -> dict:
         response = await self._session.request(method="GET",
@@ -130,7 +142,7 @@ async def list_series(
             name_contains: Optional[str] = None,
             interval: Optional[str] = None,
             acquired_gt: Optional[str] = None,
-            acquired_lt: Optional[str] = None) -> AsyncIterator[dict]:
+            acquired_lt: Optional[str] = None) -> AsyncIterator[Series]:
         """
         List the series you have access to.
 
@@ -157,7 +169,7 @@ async def list_series(
             params=params,
         )
         async for item in _SeriesPage(resp, self._session.request):
-            yield item
+            yield Series(item)
 
     async def list_mosaics(
         self,
@@ -166,8 +178,7 @@ async def list_mosaics(
         interval: Optional[str] = None,
         acquired_gt: Optional[str] = None,
         acquired_lt: Optional[str] = None,
-        latest: bool = False,
-    ) -> AsyncIterator[dict]:
+    ) -> AsyncIterator[Mosaic]:
         """
         List the mosaics you have access to.
 
@@ -188,15 +199,13 @@ async def list_mosaics(
             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 _MosaicsPage(resp, self._session.request):
-            yield item
+            yield Mosaic(item)
 
     async def list_series_mosaics(
         self,
@@ -206,7 +215,7 @@ async def list_series_mosaics(
         acquired_gt: Optional[str] = None,
         acquired_lt: Optional[str] = None,
         latest: bool = False,
-    ) -> AsyncIterator[dict]:
+    ) -> AsyncIterator[Mosaic]:
         """
         List the mosaics in a series.
 
@@ -218,6 +227,7 @@ async def list_series_mosaics(
             print(m)
         ```
         """
+        series_id = series
         if isinstance(series, Series):
             series_id = series["id"]
         elif not _is_uuid(series):
@@ -238,15 +248,15 @@ async def list_series_mosaics(
             params=params,
         )
         async for item in _MosaicsPage(resp, self._session.request):
-            yield item
+            yield Mosaic(item)
 
     async def list_quads(self,
                          /,
                          mosaic: Union[Mosaic, str],
                          *,
                          minimal: bool = False,
                          bbox: Optional[BBox] = None,
-                         geometry: Optional[dict] = None,
+                         geometry: Optional[Union[dict, GeoInterface]] = None,
                          summary: bool = False) -> AsyncIterator[Quad]:
         """
         List the a mosaic's quads.
@@ -262,6 +272,8 @@ async def list_quads(self,
         """
         mosaic = await self._resolve_mosaic(mosaic)
         if geometry:
+            if isinstance(geometry, GeoInterface):
+                geometry = geometry.__geo_interface__
             resp = await self._quads_geometry(mosaic,
                                               geometry,
                                               minimal,
@@ -364,14 +376,6 @@ async def download_quad(self,
                             directory: str = ".",
                             overwrite: bool = False,
                             progress_bar: bool = 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.
 
@@ -382,6 +386,14 @@ async def download_quad(self,
         await client.download_quad(quad)
         ```
         """
+        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)
 
     async def download_quads(self,
                              /,
@@ -390,7 +402,8 @@ async def download_quads(self,
                              directory: Optional[str] = None,
                              overwrite: bool = False,
                              bbox: Optional[BBox] = None,
-                             geometry: Optional[dict] = None,
+                             geometry: Optional[Union[dict,
+                                                      GeoInterface]] = None,
                              progress_bar: bool = False,
                              concurrency: int = 4):
         """