Merge branch 'main-3.0-dev' into carl/3.0-announcement

Author: carl-adams-planet

CLAUDE.md

@@ -0,0 +1,83 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Testing
+- **Run all tests**: `nox` (runs lint, analyze, test, coverage, docs)
+- **Run tests only**: `nox -s test`
+- **Run tests on specific Python version**: `nox -s test-3.12`
+- **Run single test file**: `nox -s test-3.12 -- tests/unit/test_http.py`
+- **Run tests by keyword**: `nox -s test-3.12 -- -k test__Limiter`
+- **Fast rerun (reuse environments)**: `nox -r`
+
+### Linting and Code Quality
+- **Linting**: `nox -s lint`
+- **Type checking**: `nox -s analyze`
+- **Code coverage**: `nox -s coverage`
+- **Format code**: `yapf --in-place -r .`
+- **Check formatting**: `yapf --diff -r .`
+
+### Documentation
+- **Build docs**: `nox -s docs`
+- **Serve docs locally**: `nox -s watch`
+- **Test documentation examples**: `nox -s docs_test`
+
+### Example Testing
+- **Test all examples**: `nox -s examples`
+- **Test specific example**: `nox -s examples -- script_name.py`
+
+### Building and Publishing
+- **Build package**: `nox -s build`
+- **Clean build directories**: `nox -s clean`
+
+## Code Architecture
+
+### High-Level Structure
+The Planet SDK provides both a Python API and CLI for Planet's APIs (Data, Orders, Subscriptions, Features).
+
+### Core Components
+
+**API Clients** (`planet/clients/`):
+- `DataClient` - Search Planet's imagery catalog
+- `OrdersClient` - Process and download imagery
+- `SubscriptionsClient` - Auto-process and deliver imagery
+- `FeaturesClient` - Upload areas of interest
+
+**Sync Client** (`planet/sync/`):
+- `Planet` class - High-level synchronous interface combining all clients
+
+**CLI** (`planet/cli/`):
+- Entry point: `planet.cli.cli:main`
+- Command modules: `data.py`, `orders.py`, `subscriptions.py`, `features.py`
+
+**Core Infrastructure**:
+- `http.py` - HTTP session management and authentication
+- `auth.py` - Authentication handling
+- `models.py` - Data models and response objects
+- `exceptions.py` - Custom exception classes
+
+**Request Building**:
+- `data_filter.py` - Data API search filters
+- `order_request.py` - Orders API request construction
+- `subscription_request.py` - Subscriptions API request construction
+
+### Key Patterns
+- All API clients extend `base.py:BaseClient`
+- Async and sync versions available (clients vs sync modules)
+- CLI commands use Click framework with shared options in `options.py`
+- Request/response validation via `specs.py` and `models.py`
+
+## Testing Configuration
+- Uses pytest with configuration in `setup.cfg`
+- Supports Python 3.9-3.13
+- Coverage threshold: 90% (configured in setup.cfg)
+- Integration tests require Planet API credentials
+- Unit tests in `tests/unit/`, integration tests in `tests/integration/`
+
+## Code Style
+- Follows PEP8 via YAPF formatter
+- Type hints checked with mypy
+- Flake8 linting with specific ignores (see setup.cfg)
+- Docstrings in Google format for auto-generated API docs

docs/cli/cli-subscriptions.md

@@ -450,22 +450,21 @@ planet subscriptions request-catalog \
     --filter filter.json > request-catalog.json
 ```
 
-### Planetary Variable Request
-
-Subscribing to Planetary Variables is much like subscribing to imagery from
-Planet's catalog. The `planet subscriptions request-pv` command can construct the source
-part of a Planetary Variable request like `request-catalog` does for cataloged
-imagery. Planetary Variable subscriptions come in 4 types and are further
-subdivided within these types by an identifier. See [Subscribing to Planetary
-Variables](https://docs.planet.com/develop/apis/subscriptions/sources/#planetary-variable-and-analysis-ready-source-types)
-for details. To constrain data delivery by space and time, you will use the
+### Planetary Variable and Analysis-Ready Source Requests
+
+Subscribing to Planetary Variables and Analysis-Ready data is much like subscribing to imagery from
+Planet's catalog. The `planet subscriptions request-source` command can construct the source
+part of a Planetary Variable or Analysis-Ready source request like `request-catalog` does for cataloged
+imagery. See [Subscribing to Planetary
+Variables and Analysis Ready sources](https://docs.planet.com/develop/apis/subscriptions/sources/#planetary-variable-and-analysis-ready-source-types)
+for details about different product options. To constrain data delivery by space and time, you will use the
 `--geometry`, `start-time`, and `end-time` options described above.
 
 ```sh
-planet subscriptions request-pv \
-    --var-id BIOMASS-PROXY_V3.0_10 \
+planet subscriptions request-source \
+    --source-id BIOMASS-PROXY_V3.0_10 \
     --geometry geometry.geojson \
-    --start-time 2022-08-24T00:00:00-07:00 > request-pv.json
+    --start-time 2022-08-24T00:00:00-07:00 > request-source.json
 ```
 
 ### Subscription Tools

docs/get-started/upgrading-v3.md

@@ -92,4 +92,9 @@ Users developing new applications should consult the [Client Authentication Guid
 for a complete discussion of all OAuth2 based mechanisms.  OAuth2 mechanisms
 should be preferred to the use of Planet API keys.
 
+## Additional Breaking Changes
+
+* Deprecated `planet.subscription_request.clip_tool()` method for defining custom clip AOIs with requests to create subscriptions.  Subscriptions API no longer supports custom clip AOIs; instead users can opt-in to clip to their subscription source geometry by including kwarg `clip_to_source=True` when constructing requests via `planet.subscription_request.build_request()`.  See [PR #1169](https://github.com/planetlabs/planet-client-python/pull/1169) for implementation details.
+* Renamed `planet.cli.subscriptions.request_pv()` to `planet.cli.subscriptions.request_source()`, and removed `var_type` positional argument from the signature.  This change, in effect renames the CLI argument `planet subscriptions request-pv` to `planet subscriptions request-source`.  Also renamed `planet.subscription_request.planetary_variable_source()` to `planet.subscription_request.subscription_source()`.  Source type positional arguments are removed from these methods in favor of `source_id`.  See [PR #1170](https://github.com/planetlabs/planet-client-python/pull/1170) for implementation details.
+
 ----

docs/hooks/mkdocs_hooks.py

@@ -1,5 +1,6 @@
 from planet import __version__ as _pl_sdk_version
 
+
 def on_config(config):
     """
     This is for injecting the package version into mkdocs

docs/python/sdk-guide.md

@@ -225,7 +225,7 @@ You will need your ACCESS_KEY_ID, SECRET_ACCESS_KEY, bucket and region name.
 To subscribe to scenes that match a filter, use the `subscription_request` module to build a request, and
 pass it to the `subscriptions.create_subscription()` method of the client.
 
-By default, a request to create a subscription will not clip matching imagery which intersects the source geometry.  To clip to the subscription source geometry, set `planet.subscription_request.build_request()` keyword argument `clip_to_source = True` as in the example below.  To clip to a custom geometry, set `planet.subscription_request.build_request()`  keyword argument `clip_to_source = False` (or omit it entirely to fall back on the default value), and instead configure the custom clip AOI with `planet.subscription_request.clip_tool()`.
+By default, a request to create a subscription will not clip matching imagery which intersects the source geometry.  To clip to the subscription source geometry, set `planet.subscription_request.build_request()` keyword argument `clip_to_source = True` as in the example below.  Custom clip AOIs are no longer supported in subscriptions.
 
 Warning: the following code will create a subscription, consuming quota based on your plan.
 

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

examples/mosaics-cli.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+echo -e "List the mosaic series that have the word Global in their name"
+planet mosaics series list --name-contains=Global | jq .[].name
+
+echo -e "\nWhat is the latest mosaic in the series named Global Monthly, with output indented"
+planet mosaics series list-mosaics "Global Monthly" --latest --pretty
+
+echo -e "\nHow many quads are in the mosaic with this ID (name also accepted!)?"
+planet mosaics search 09462e5a-2af0-4de3-a710-e9010d8d4e58 --bbox=-100,40,-100,40.1 | jq .[].id
+
+echo -e "\nWhat scenes contributed to this quad in the mosaic with this ID (name also accepted)?"
+planet mosaics contributions 09462e5a-2af0-4de3-a710-e9010d8d4e58 455-1273
+
+echo -e "\nDownload them to a directory named quads!"
+planet mosaics download 09462e5a-2af0-4de3-a710-e9010d8d4e58 --bbox=-100,40,-100,40.1 --output-dir=quads

planet/__init__.py

@@ -17,7 +17,7 @@
 from .__version__ import __version__  # NOQA
 from .auth import Auth
 from .auth_builtins import PlanetOAuthScopes
-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
 
@@ -28,6 +28,7 @@
     'DataClient',
     'data_filter',
     'FeaturesClient',
+    'MosaicsClient',
     'OrdersClient',
     'order_request',
     'Planet',

planet/cli/cli.py

@@ -20,6 +20,7 @@
 
 import planet_auth_utils
 import planet
+from planet.cli import mosaics
 
 from . import auth, cmds, collect, data, orders, subscriptions, features
 
@@ -128,6 +129,7 @@ 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)
 
 if __name__ == "__main__":
     main()  # pylint: disable=E1120