### Install Planet Python SDK

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/get-started/quick-start-guide.md

Installs the Planet SDK for Python from PyPI using pip. Requires Python 3.9 or greater.

```bash
pip install planet
```

--------------------------------

### Downloading and Validating an Asset

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/python/async-sdk-guide.md

Provides a comprehensive example of the asset download process: getting asset details, activating the asset, waiting for activation, downloading, and validating the checksum. Includes callback for progress reporting.

```python
async def download_and_validate():
    async with Session() as sess:
        cl = sess.client('data')

        # get asset description
        item_type_id = 'PSScene'
        item_id = '20221003_002705_38_2461'
        asset_type_id = 'ortho_analytic_4b'
        asset = await cl.get_asset(item_type_id, item_id, asset_type_id)

        # activate asset
        await cl.activate_asset(asset)

        # wait for asset to become active
        asset = await cl.wait_asset(asset, callback=print)

        # download asset
        path = await cl.download_asset(asset)

        # validate download file
        cl.validate_checksum(asset, path)
```

--------------------------------

### Install Planet Python SDK

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/python/sdk-guide.md

Installs the Planet Python SDK using pip, a package manager for Python.

```sh
pip install planet
```

--------------------------------

### Basic Data Client Usage

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/python/async-sdk-guide.md

Demonstrates the basic setup and usage of the Data Client within a session. It shows how to instantiate the client and prepare for data operations.

```python
async def main():
    async with Session() as sess:
        client = sess.client('data')
        # perform operations here

asyncio.run(main())
```

--------------------------------

### Install Planet Python SDK

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/python/async-sdk-guide.md

Installs the Planet Python SDK using pip, a package manager for Python. This is the first step to using the SDK in your project.

```sh
pip install planet
```

--------------------------------

### Install Planet SDK

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-guide.md

Installs the Planet SDK for Python using pip. This is the first step to using the Planet CLI.

```console
pip install planet
```

--------------------------------

### Running Example Scripts

Source: https://github.com/planetlabs/planet-client-python/blob/main/examples/README.md

Demonstrates how to execute example scripts from the command line. It also shows how to filter tests for a specific script using the `nox` command.

```console
> nox -s examples -- <script_name>.py
For a new script named 
`new_script.py`, this would be `nox -s examples -- new_script.py`
```

--------------------------------

### Run All Example Scripts

Source: https://github.com/planetlabs/planet-client-python/blob/main/CONTRIBUTING.md

Execute all Python scripts located in the `examples` directory using the Nox `examples` session. This verifies the functionality of provided SDK usage examples.

```console
nox -s examples
```

--------------------------------

### Orders API and Planet SDK Integration (Jupyter Notebook)

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/resources/index.md

This Python notebook demonstrates how to get started with the Planet SDK and the Orders API. It covers essential steps for integrating order management into Python applications.

```Python
# Example: Planet_SDK_Orders_demo.ipynb
# A Python notebook shows how to get started with Planet SDK and the Orders API.

# Placeholder for notebook content
print("Getting started with Planet SDK and Orders API...")
# from planet import orders_api
# orders_api.create_order(...) 

```

--------------------------------

### Run Specific Example Script

Source: https://github.com/planetlabs/planet-client-python/blob/main/CONTRIBUTING.md

Test a single Python script from the `examples` directory by specifying the script name with the Nox `examples` session. This allows for focused testing of individual examples.

```console
nox -s examples -- <script_name>.py
```

--------------------------------

### Planet Data API Introduction with Python Client (Jupyter Notebook)

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/resources/index.md

This Python notebook provides an introduction to Planet's Data API and the `planet` module. It serves as a guide for developers new to accessing Planet data programmatically.

```Python
# Example: planet_python_client_introduction.ipynb
# A Python notebook to introduce Planet’s Data API and the `planet` module.

# Placeholder for notebook content
print("Exploring Planet Data API with planet module...")
# from planet import data_api
# data_api.search(...) 

```

--------------------------------

### Install Planet SDK from Source

Source: https://github.com/planetlabs/planet-client-python/blob/main/README.md

Installs the Planet SDK for Python from its source code. This involves cloning the repository and running pip install from the root directory.

```console
pip install .
```

--------------------------------

### Installing and Using the Planet SDK

Source: https://github.com/planetlabs/planet-client-python/blob/main/README.md

Provides guidance on installing the Planet SDK via PyPI and how to specify version dependencies. It suggests using `planet == 2.*` for general use or `planet == 2.x.*` for specific features.

```bash
# Install Planet SDK from PyPI
pip install planet

# Specify version dependencies in requirements.txt or setup.py:
# planet == 2.*
# or for a specific minor version:
# planet == 2.x.*
```

--------------------------------

### Data Download and Order Management Examples (Python)

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/resources/index.md

This Python script demonstrates how to order, activate, and download multiple assets using the Planet SDK. It showcases practical usage for managing data acquisition workflows.

```Python
from planet import api

# Example: data_download_multiple_assets.py
# This script orders, activates, and downloads two assets.

# Placeholder for actual API calls and logic
print("Running data_download_multiple_assets.py example...")
# api.orders.create_order(...) 
# api.assets.download(...) 

```

--------------------------------

### Planet Client Python Docstring Examples

Source: https://github.com/planetlabs/planet-client-python/blob/main/CHANGES.txt

Updates example code syntax in docstrings for Order and Data clients and adds examples to the Subscriptions client docstring.

--------------------------------

### Install Nox

Source: https://github.com/planetlabs/planet-client-python/blob/main/CONTRIBUTING.md

Instructions for installing the Nox automation tool, which is used for testing, linting, and building documentation within the project.

```console
$ pip install nox
```

--------------------------------

### Bulk Create Order Example

Source: https://github.com/planetlabs/planet-client-python/blob/main/CHANGES.txt

Shows an updated example for bulk order creation, demonstrating the use of a dynamic list for creating orders.

```python
# Bulk create order example now demonstrates use of a dynamic list (#913).
```

--------------------------------

### Install Planet SDK via Pip

Source: https://github.com/planetlabs/planet-client-python/blob/main/README.md

Installs the Planet SDK for Python from PyPI using pip. This is the recommended method for most users.

```console
pip install planet
```

--------------------------------

### Toolchain Configuration Example

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-orders.md

An example of a `tools.json` file defining a toolchain for geospatial processing. This includes operations like TOAR correction, reprojection, and tiling with specific parameters for each tool.

```json
[
    {
        "toar": {
            "scale_factor": 10000
        }
    },
    {
        "reproject": {
            "projection": "WGS84",
            "kernel": "cubic"
        }
    },
    {
        "tile": {
            "tile_size": 1232,
            "origin_x": -180,
            "origin_y": -90,
            "pixel_size": 2.7056277056e-05,
            "name_template": "C1232_30_30_{tilex:04d}_{tiley:04d}"
        }
    }
]
```

--------------------------------

### Run All Doc Tests

Source: https://github.com/planetlabs/planet-client-python/blob/main/CONTRIBUTING.md

Execute all code examples embedded within Markdown documents using the Nox `docs_test` session. This ensures the accuracy of documentation examples.

```console
nox -s docs_test
```

--------------------------------

### Install Planet Python Client

Source: https://github.com/planetlabs/planet-client-python/blob/main/CHANGES.txt

Instructions for installing the Planet Python client library using pip. It notes the removal of `--pre` and `--user` flags for cleaner installation.

```bash
pip install planet
```

--------------------------------

### Install YAPF

Source: https://github.com/planetlabs/planet-client-python/blob/main/CONTRIBUTING.md

Instructions for installing YAPF, a Python code formatter used to enforce style guidelines in the project.

```console
$ pip install yapf
```

--------------------------------

### Install Python 3 using Homebrew

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/get-started/venv-tutorial.md

Installs Python 3 on macOS using Homebrew. This provides the `python3` command.

```console
 $ brew install python
```

--------------------------------

### Install Planet SDK v1

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/get-started/venv-tutorial.md

Installs version 1 of the Planet SDK using pip within an activated virtual environment.

```console
  $ pip install planet
```

--------------------------------

### Create Subscription with Sentinel Hub Hosting

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-subscriptions.md

Example of creating a subscription request that includes Sentinel Hub hosting. This demonstrates using the --hosting flag with a value or as a JSON file.

```sh
planet subscriptions request \
    --name 'First Subscription' \
    --source request-catalog.json \
    --tools tools.json \
    --hosting sentinel_hub \
    | planet subscriptions create -
```

--------------------------------

### Planet CLI 'auth login-key' Usage Example

Source: https://github.com/planetlabs/planet-client-python/blob/main/design-docs/CLI-Core.md

Provides an example of how to use the 'planet auth login-key' command to obtain and store API key credentials, including the expected interactive prompts for email and password.

```bash
$ planet auth login-key

email:
Password:
Authorized
```

--------------------------------

### Stats Command Output Example

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-data.md

Example JSON output from the `stats` command when binning by year, showing counts per year.

```json
{
  "buckets": [
    {
      "count": 5261,
      "start_time": "2014-01-01T00:00:00.000000Z"
    },
    {
      "count": 34377,
      "start_time": "2015-01-01T00:00:00.000000Z"
    },
    {
      "count": 112331,
      "start_time": "2016-01-01T00:00:00.000000Z"
    },
    {
      "count": 504377,
      "start_time": "2017-01-01T00:00:00.000000Z"
    },
    {
      "count": 807086,
      "start_time": "2018-01-01T00:00:00.000000Z"
    },
    {
      "count": 806945,
      "start_time": "2019-01-01T00:00:00.000000Z"
    },
    {
      "count": 776757,
      "start_time": "2020-01-01T00:00:00.000000Z"
    },
    {
      "count": 684095,
      "start_time": "2021-01-01T00:00:00.000000Z"
    },
    {
      "count": 323557,
      "start_time": "2022-01-01T00:00:00.000000Z"
    },
    {
      "count": 56733,
      "start_time": "2023-01-01T00:00:00.000000Z"
    }
  ],
  "interval": "year",
  "utc_offset": "+0h"
}
```

--------------------------------

### Install Planet SDK with Development Packages

Source: https://github.com/planetlabs/planet-client-python/blob/main/CONTRIBUTING.md

Installs the Planet SDK for Python and required development packages into a virtual environment using pip. This is an alternative to using Nox for local testing.

```console
pip install -e .'[dev]'
```

--------------------------------

### Planet CLI Data Asset Download Example

Source: https://github.com/planetlabs/planet-client-python/blob/main/design-docs/CLI-Data.md

Example of downloading a PSScene asset, specifying the download directory and enabling overwrite.

```bash
$ planet --quiet data asset-download \
--directory data \
--overwrite \
PSScene 20210819_162141_68_2276 basic_analytic_4b
data/<psscene_naming 20210819_162141_68_2276>.tif
```

--------------------------------

### Environment Variable for Downloads

Source: https://github.com/planetlabs/planet-client-python/blob/main/examples/README.md

Shows how to set a default download directory using an environment variable. If the variable is not set, it defaults to the current directory.

```python
DOWNLOAD_DIR = os.getenv('TEST_DOWNLOAD_DIR', '.')
```

--------------------------------

### Authenticate with Planet Services (Default Session)

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/python/async-sdk-guide.md

Demonstrates how to authenticate with Planet services using the default user session. It checks if authentication is initialized and guides the user to log in via the CLI if not. This snippet requires the `planet` library and `asyncio`.

```python
import asyncio
import sys
from planet import Auth, Session

auth = Auth.from_user_default_session()
async def main():
    if not auth.is_initialized():
        print("Login required. Execute the following command:\n\n\tplanet auth login\n")
        sys.exit(99)

    async with Session(auth=auth) as sess:
        # perform operations here
        pass

asyncio.run(main())
```

--------------------------------

### List All Orders (Bash Example)

Source: https://github.com/planetlabs/planet-client-python/blob/main/design-docs/CLI-Orders.md

Example of how to use the Planet CLI to list all orders by setting the limit to 0, outputting the results as JSON.

--------------------------------

### Download and Validate Asset

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/python/sdk-guide.md

Demonstrates downloading a single asset, activating it, waiting for activation, downloading, and validating the checksum. It includes a callback for progress reporting during the wait process.

```python
from planet import Planet

def download_and_validate():
    pl = Planet()

    # get asset description
    item_type_id = 'PSScene'
    item_id = '20221003_002705_38_2461'
    asset_type_id = 'ortho_analytic_4b'
    asset = pl.data.get_asset(item_type_id, item_id, asset_type_id)

    # activate asset
    pl.data.activate_asset(asset)

    # wait for asset to become active
    asset = pl.data.wait_asset(asset, callback=print)

    # download asset
    path = pl.data.download_asset(asset)

    # validate download file
    pl.data.validate_checksum(asset, path)
```

--------------------------------

### Get Specific Order (Bash Example)

Source: https://github.com/planetlabs/planet-client-python/blob/main/design-docs/CLI-Orders.md

Example of how to use the Planet CLI to get the details of a specific order using its ID.

--------------------------------

### Authenticate with Planet CLI

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/python/sdk-guide.md

Logs in to the Planet platform using the command-line interface to establish a saved user session for the SDK.

```sh
planet auth login
```

--------------------------------

### Order Creation Response

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-orders.md

This is an example of the JSON response received after creating a Planet order. It includes details like the order ID, creation timestamp, name, products, and current state.

```json
{
  "_links": {
    "_self": "https://api.planet.com/compute/ops/orders/v2/2887c43b-26be-4bec-8efe-cb9e94f0ef3d"
  },
  "created_on": "2022-11-29T22:49:24.478Z",
  "error_hints": [],
  "id": "2887c43b-26be-4bec-8efe-cb9e94f0ef3d",
  "last_message": "Preparing order",
  "last_modified": "2022-11-29T22:49:24.478Z",
  "metadata": {
    "stac": {}
  },
  "name": "My First Order",
  "products": [
    {
      "item_ids": [
        "20220605_124027_64_242b"
      ],
      "item_type": "PSScene",
      "product_bundle": "analytic_sr_udm2"
    }
  ],
  "state": "queued"
}
```

--------------------------------

### Get Item Example

Source: https://github.com/planetlabs/planet-client-python/blob/main/design-docs/CLI-Data.md

This example shows how to retrieve the details of a specific item using the `item-get` command in the Planet CLI.

```bash
$ planet data item-get PSScene 20210819_162141_68_2276

{"_links": {...}, ..., "type": "Feature"}
```

--------------------------------

### Listing Features API Collections

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/python/async-sdk-guide.md

Demonstrates how to list all existing collections in the Features API. It iterates through the collections asynchronously and prints each one.

```python
async with Session() as sess:
  client = FeaturesClient(sess)
  collections = client.list_collections()
  async for collection in collections:
    print(collection)
```

--------------------------------

### Development Commands

Source: https://github.com/planetlabs/planet-client-python/blob/main/CLAUDE.md

A collection of `nox` commands to manage the development workflow, including running tests, linting, checking code quality, building documentation, and testing examples.

```bash
# Testing
# Run all tests (lint, analyze, test, coverage, docs)
nox
# 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
```

--------------------------------

### Planet CLI Data Stats Example

Source: https://github.com/planetlabs/planet-client-python/blob/main/design-docs/CLI-Data.md

Example of getting statistics for multiple item types with a UTC offset, using a file for the filter.

```bash
$ planet data stats --utc-offset +1:00 \
PSScene,REOrthoTile day filter-desc.json

<unedited API response json>
```

--------------------------------

### Instantiate Planet Client

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/get-started/quick-start-guide.md

Creates an instance of the Planet client, which is the main entry point for the Planet SDK. It automatically detects authentication configured via `planet auth login`. The client provides access to Data, Orders, and Subscriptions APIs.

```python
from planet import Planet
pl = Planet()  # automatically detects authentication configured by `planet auth login`
```

--------------------------------

### Create GitHub Release (CLI)

Source: https://github.com/planetlabs/planet-client-python/blob/main/RELEASE.md

Creates a new GitHub release using the GitHub CLI. Requires the 'gh' CLI to be installed. Automatically tags from the default branch.

```console
gh release create {VERSION} --notes "{RELEASE NOTES}"
```

--------------------------------

### Basemaps Order Request

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-orders.md

Example JSON payload for requesting Planet basemaps, specifying mosaic name, geometry, and processing tools like merge and clip.

```json
{
   "name": "basemap order with geometry",
   "source_type": "basemaps",
   "order_type":"partial",
   "products": [
       {
           "mosaic_name": "global_monthly_2022_01_mosaic",
           "geometry":{
               "type": "Polygon",
               "coordinates":[
                   [
                       [4.607406, 52.353994],
                       [4.680005, 52.353994],
                       [4.680005, 52.395523],
                       [4.607406, 52.395523],
                       [4.607406, 52.353994]
                   ]
               ]
           }
      }
  ],
    "tools": [
      {"merge": {}},
      {"clip": {}}
  ]
}
```

--------------------------------

### Cloud Delivery Configuration (AWS S3)

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-orders.md

Example JSON configuration for delivering Planet order assets to an AWS S3 bucket. Requires AWS credentials and bucket details.

```json
{
    "amazon_s3": {
        "aws_access_key_id": "aws_access_key_id",
        "aws_secret_access_key": "aws_secret_access_key",
        "bucket": "bucket",
        "aws_region": "aws_region"
    },
    "archive_type": "zip"
}
```

--------------------------------

### Applying Multiple Subscription Tools

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-subscriptions.md

Provides an example of how to use multiple processing tools (e.g., toar, reproject, harmonize, file_format) in a single subscription request by defining them in a JSON array.

```json
[
    {
        "type": "toar",
        "parameters":
        {
            "scale_factor": 10000
        }
    },
    {
        "type": "reproject",
        "parameters":
        {
            "projection": "WGS84",
            "kernel": "cubic"
        }
    },
    {
        "type": "harmonize",
        "parameters":
        {
            "target_sensor": "Sentinel-2"
        }
    },
    {
        "type": "file_format",
        "parameters":
        {
            "format": "COG"
        }
    }
]
```

--------------------------------

### Check Planet SDK Version

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-guide.md

Checks the installed version of the Planet SDK for Python. Ensures you are using a compatible version.

```console
planet --version
```

--------------------------------

### Search by Geometry

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/python/sdk-guide.md

Filters search results by a specified polygonal geometry. This example searches for 'PSScene' items within a defined geographic area and limits the results to 5.

```python
from planet import Planet

geom = {
  "coordinates": [
    [
      [
        -125.41267816101056,
        46.38901501783491
      ],
      [
        -125.41267816101056,
        41.101114161051015
      ],
      [
        -115.51426167332103,
        41.101114161051015
      ],
      [
        -115.51426167332103,
        46.38901501783491
      ],
      [
        -125.41267816101056,
        46.38901501783491
      ]
    ]
  ],
  "type": "Polygon"
}
for item in pl.data.search(['PSScene'], geometry=geom, limit=5):
    print(item)
```

--------------------------------

### Azure Blob Storage Delivery Configuration

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-subscriptions.md

Example JSON configuration for delivering data to Azure Blob Storage. This includes account, container, SAS token, and storage endpoint suffix.

```json
{
    "type": "azure_blob_storage",
    "parameters":
    {
        "account": "accountname",
        "container": "containername",
        "sas_token": "sv=2017-04-17u0026si=writersr=cu0026sig=LGqc",
        "storage_endpoint_suffix": "core.windows.net"
    }
}
```

--------------------------------

### Create, Wait, and Download Order with Progress

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/python/async-sdk-guide.md

Demonstrates how to create an order, wait for its processing with progress updates using a state bar, and then download the assets. It utilizes the `planet.reporting` module for visual progress tracking.

```python
from planet import reporting
import asyncio

async def create_wait_and_download():
    async with Session() as sess:
        cl = sess.client('orders')
        with reporting.StateBar(state='creating') as bar:
            # create order
            order = await cl.create_order(request)
            bar.update(state='created', order_id=order['id'])

            # poll
            await cl.wait(order['id'], callback=bar.update_state)

        # download
        await cl.download_order(order['id'])

asyncio.run(create_wait_and_download())
```

--------------------------------

### Authenticate with Planet CLI

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/get-started/quick-start-guide.md

Logs in to establish a user session using the Planet CLI command. This session is saved to the user's home directory and automatically detected by SDK library functions.

```bash
planet auth login
```

--------------------------------

### Using Features as Geometries

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/python/async-sdk-guide.md

Illustrates how Features API items can be used directly as geometry inputs for other SDK methods, such as data searches. This example uses a feature as a geometry for a data search.

```python
async with Session() as sess:
  client = FeaturesClient(sess)
  items = client.list_items(collection_id)
  example_feature = await anext(items)

  data_client = DataClient(sess)
  results = data_client.search(["PSScene"], geometry=example_feature, limit=1)
  async for result in results:
    print(result)
```

--------------------------------

### Use CLI-Managed Auth Profile

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/auth/auth-dev-cli-managed.md

This example demonstrates how an application can select a specific CLI-managed authentication profile. It's useful for guiding user experience towards a distinct auth session separate from the CLI's default. Note that the profile 'my-app-profile' must exist and be created separately.

```python
from planet import auth

# Force the use of a specific CLI-managed auth profile
auth.set_session_name("my-app-profile")

# Now, any Planet API calls will use the 'my-app-profile' session
# For example:
# from planet.api import Sessions
# sessions_api = Sessions()
# print(sessions_api.get_current_session())

```

--------------------------------

### Install Homebrew on macOS

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/get-started/venv-tutorial.md

Installs Homebrew, a package manager for macOS, which is used to install Python 3.

```console
 $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

--------------------------------

### Check Planet SDK Version

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/get-started/venv-tutorial.md

Verifies the installed version of the Planet SDK after installation or activation.

```console
 $ planet --version
```

--------------------------------

### Place an Order for Assets

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/python/sdk-guide.md

Shows how to place an order for assets using the Orders API client. It involves building an order request with specified item IDs and product bundles, creating the order, waiting for it to be ready, and then downloading the assets.

```python
from planet import Planet, order_request

def main():
    pl = Planet()
    image_ids = ["20200925_161029_69_2223"]
    request = order_request.build_request(
        name='test_order',
        products=[
           order_request.product(
               item_ids=image_ids,
               product_bundle='analytic_8b_udm2',
               item_type='PSScene',
               fallback_bundle='analytic_udm2,analytic_3b_udm2')
       ]
    )

    order = pl.orders.create_order(request)

    # wait for the order to be ready
    # note: this may take several minutes.
    pl.orders.wait(order['id'])

    pl.orders.download_order(order['id'], overwrite=True)
```

--------------------------------

### Creating a Features API Collection

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/python/async-sdk-guide.md

Shows how to create a new collection in the Features API using the Python SDK. Requires a session and provides title and description for the new collection.

```python
async with Session() as sess:
  client = FeaturesClient(sess)
  new_collection = await client.create_collection(title="my collection", description="a new collection")
```

--------------------------------

### Cancel Specific Order (Bash Example)

Source: https://github.com/planetlabs/planet-client-python/blob/main/design-docs/CLI-Orders.md

Example of how to use the Planet CLI to cancel a specific order using its ID.

--------------------------------

### Build and Serve Documentation Locally with Nox

Source: https://github.com/planetlabs/planet-client-python/blob/main/CONTRIBUTING.md

Executes the Nox session named 'watch' to build and serve the project documentation locally with automatic updates, facilitating documentation development.

```console
nox -s watch
```

--------------------------------

### Requesting Planetary Variables and Analysis-Ready Source Data

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-subscriptions.md

Demonstrates the use of `planet subscriptions request-source` to construct source requests for Planetary Variables and Analysis-Ready data, similar to how `request-catalog` works for imagery.

```sh
planet subscriptions request-source \
    --source-id BIOMASS-PROXY_V3.0_10 \
    --geometry geometry.geojson \
    --start-time 2022-08-24T00:00:00-07:00 > request-source.json
```

--------------------------------

### List Available Assets for an Item

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-data.md

Lists all available assets associated with a specific Planet item, including their status and any activation requirements. This helps users understand what data products are available for a given scene.

```sh
planet data asset-list PSScene 20230310_083933_71_2431
```

--------------------------------

### Visualize Large Dataset with Kepler.gl

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-tips-tricks.md

Searches for a large number of satellite scenes (1500) across multiple sources, sorts them by acquisition date, and visualizes the footprints using Kepler.gl.

```console
curl -s https://storage.googleapis.com/open-geodata/ch/vermont.json \
| planet data filter --geom - \
| planet data search PSScene,Sentinel2L1C,Landsat8L1G,SkySatCollect,Sentinel1 \
--sort 'acquired desc' --limit 1500 --filter - \
| kepler
```

--------------------------------

### Build Documentation with Nox

Source: https://github.com/planetlabs/planet-client-python/blob/main/CONTRIBUTING.md

Executes the Nox session named 'docs' to build the project documentation from Markdown files using MkDocs.

```console
nox -s docs
```

--------------------------------

### Local Publishing Workflow

Source: https://github.com/planetlabs/planet-client-python/blob/main/RELEASE.md

Commands to locally build and publish the Planet Python client to TestPyPI and PyPI using Nox. Requires API tokens to be provided.

```console
nox -s build publish-testpypi
```

```console
nox -s publish-pypi
```

--------------------------------

### Create Subscription JSON

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-subscriptions.md

Defines the structure for creating a new Planet subscription, including source parameters, processing tools (like clipping), and delivery configurations to cloud storage.

```json
{
  "name": "First Subscription",
  "source": {
    "parameters": {
      "asset_types": [
        "ortho_analytic_8b"
      ],
      "end_time": "2023-11-01T00:00:00Z",
      "geometry": {
        "coordinates": [
          [
            [
              139.5648193359375,
              35.42374884923695
            ],
            [
              140.1031494140625,
              35.42374884923695
            ],
            [
              140.1031494140625,
              35.77102915686019
            ],
            [
              139.5648193359375,
              35.77102915686019
            ],
            [
              139.5648193359375,
              35.42374884923695
            ]
          ]
        ],
        "type": "Polygon"
      },
      "item_types": [
        "PSScene"
      ],
      "start_time": "2023-03-17T04:08:00.0Z"
    }
  },
  "tools": [
    {
      "type": "clip",
      "parameters": {
        "aoi": {
          "coordinates": [
            [
              [
                139.5648193359375,
                35.42374884923695
              ],
              [
                140.1031494140625,
                35.42374884923695
              ],
              [
                140.1031494140625,
                35.77102915686019
              ],
              [
                139.5648193359375,
                35.77102915686019
              ],
              [
                139.5648193359375,
                35.42374884923695
              ]
            ]
          ],
          "type": "Polygon"
        }
      }
    }
  ],
  "delivery": {
    "type": "google_cloud_storage",
    "parameters": {
      "bucket": "pl-sub-bucket",
      "credentials": "<REDACTED>"
    }
  }
}
```

--------------------------------

### Downloading Multiple Assets in Parallel Example

Source: https://github.com/planetlabs/planet-client-python/blob/main/CHANGES.txt

References a new example demonstrating how to download multiple assets concurrently using the Planet Python client.

```python
# Add new example (example subfolder): Downloading multiple assets in parallel (#722).
```

--------------------------------

### Testing Configuration

Source: https://github.com/planetlabs/planet-client-python/blob/main/CLAUDE.md

Details the testing setup for the Planet Python client, including the testing framework (pytest), configuration file (`setup.cfg`), supported Python versions, coverage targets, and requirements for integration tests.

```python
# 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/
```

--------------------------------

### List Last 100 Orders (Bash Example)

Source: https://github.com/planetlabs/planet-client-python/blob/main/design-docs/CLI-Orders.md

Example of how to use the Planet CLI to list the last 100 orders, outputting the results as JSON.

```bash
$ planet orders list
```

--------------------------------

### Planet Orders API Documentation

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/resources/index.md

Documentation for Planet's Orders API, detailing how to create, manage, and monitor orders for data processing and delivery. Covers order request parameters, status tracking, and notifications.

```APIDOC
Orders API:
  Base URL: https://api.planet.com/orders/v2/

  Endpoints:
    - Create Order:
        Method: POST
        Path: /
        Description: Creates a new data processing order.
        Request Body:
          type: object
          properties:
            name: { type: string }
            products: { type: array, items: { type: object } }
            tools: { type: object }
            notifications: { type: object }
            callback: { type: string }
        Example:
          POST /
          {
            "name": "my-first-order",
            "products": [
              {
                "item_ids": ["item-1", "item-2"],
                "product_bundle": "analytic_sr_udm2"
              }
            ]
          }

    - Get Order:
        Method: GET
        Path: /{order_id}
        Description: Retrieves the status and details of a specific order.

    - List Orders:
        Method: GET
        Path: /
        Description: Lists all orders associated with the account.

  Order Status:
    - created
    - running
    - succeeded
    - failed
    - cancelled

  Authentication:
    API Key authentication is required. Include your Planet API key in the 'api-key' header.
```

--------------------------------

### List Last 5 Successful Orders (Bash Example)

Source: https://github.com/planetlabs/planet-client-python/blob/main/design-docs/CLI-Orders.md

Example of how to use the Planet CLI to list the last 5 successful orders, outputting the results as JSON.

--------------------------------

### Contributing Guide Improvements

Source: https://github.com/planetlabs/planet-client-python/blob/main/design-docs/content-plan.md

Details necessary updates for the `CONTRIBUTING.md` file, focusing on providing end-to-end steps for building, changing, testing, and viewing documentation, as well as clarifying build output locations.

```markdown
This document explains how to generate a local environment and documentation, but does not provide the final locations of the builds and does not instruct on how to view the documentation.

### Ticket to be filed

Update the contributing.md file with end-to-end steps to build, change, test, and view documentation.
```

--------------------------------

### Create Saved Search Example

Source: https://github.com/planetlabs/planet-client-python/blob/main/design-docs/CLI-Data.md

This example demonstrates how to create a saved search using the Planet CLI, combining a filter created with `planet data filter` with the `search-create` command.

```bash
$ planet data filter \
--range clear_percent gt 98 \
--date-range acquired gte 2021-07-01 \
--date-range acquired lt 2021-08-01 | planet data search-create test PSScene
```

--------------------------------

### Planet Python Client - Version 0.0.5 Changes

Source: https://github.com/planetlabs/planet-client-python/blob/main/CHANGES.txt

Details changes in version 0.0.5, including support for RapidEye in the CLI, fixes for README examples, and resolution of duplicate examples in documentation.

```python
# Support RapidEye in CLI
# Fix examples in README
# Fix duplicate example in doc
```

--------------------------------

### MkDocs Theme Development Resources

Source: https://github.com/planetlabs/planet-client-python/blob/main/design-docs/content-gsx-notes.md

Provides links to essential resources for developing and customizing MkDocs themes, including official documentation and community discussions.

```html
[mkdocs.org dev-guide themes ](https://www.mkdocs.org/dev-guide/themes/)
```

```html
[Developing Themes : A guide to creating and distributing custom themes.](https://www.mkdocs.org/dev-guide/themes/)
```

```html
[Steps to creating a similar homepage](https://github.com/squidfunk/mkdocs-material/issues/1996#issuecomment-855086383)
```

```html
[Template Designer Documentation](https://jinja.palletsprojects.com/en/3.1.x/templates/)
```

--------------------------------

### Mosaic Functionality Examples

Source: https://github.com/planetlabs/planet-client-python/blob/main/CHANGES.txt

Provides examples of mosaic functionality and updates CLI command help information for mosaics. Adds Sentinel-1 item type and SR & SkySat asset types to defaults.

```python
# Example of creating a mosaic
# planet mosaics create --name "my_mosaic" --source "PSScene" --filter "acquired<2023-01-01"
```

--------------------------------

### Legacy API Key file example

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/auth/auth-dev-app-managed-apikey.md

An example JSON file structure for storing a Planet API key, compatible with older versions of the SDK. This file should contain the 'api_key' field with your actual key.

```json
{
  "api_key": "YOUR_PLANET_API_KEY"
}
```

--------------------------------

### Create a Planet SDK Session (Context Manager)

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/python/async-sdk-guide.md

Shows how to create and use a Planet SDK `Session` as an asynchronous context manager. This ensures proper session management and automatic cleanup of connections.

```python
import asyncio
from planet import Session

async def main():
    async with Session() as sess:
        # perform operations here
        pass

asyncio.run(main())
```

--------------------------------

### Ordering and Clipping Multiple Cloud-Free PSScenes

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-orders.md

CLI commands to filter for cloud-free PlanetScope scenes, select the top 5, and create an order clipped to a specified geometry.

```sh
ids=$(planet data filter --geom geometry.geojson --range clear_percent gt 90 \
    | planet data search PSScene --limit 5 --filter - \
    | jq -r .id \
    | tr '\n' ',' \
    | sed 's/.$//'
)
planet orders request \
    --item-type PSScene \
    --bundle analytic_sr_udm2 \
    --name 'Clipped Scenes' \
    $ids \
    --clip geometry.geojson \
    | planet orders create -
```

--------------------------------

### Create a Scene Subscription with AWS S3 Delivery

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/python/sdk-guide.md

Demonstrates creating a subscription to scenes that match specific criteria, with delivery configured for Amazon S3. It includes defining the source geometry, activation times, and delivery details, and optionally clipping imagery to the source geometry.

```python
from planet.subscription_request import catalog_source, build_request, amazon_s3
from datetime import datetime

# Assuming pl is an initialized Planet client instance
# ACCESS_KEY_ID, SECRET_ACCESS_KEY, and 'test' bucket/region are placeholders

source = catalog_source(
    ["PSScene"],
    ["ortho_analytic_4b"],
    geometry={
        "type": "Polygon",
        "coordinates": [
            [
                [37.791595458984375, 14.84923123791421],
                [37.90214538574219, 14.84923123791421],
                [37.90214538574219, 14.945448293647944],
                [37.791595458984375, 14.945448293647944],
                [37.791595458984375, 14.84923123791421],
            ]
        ],
    },
    start_time=datetime.now(),
    publishing_stages=["standard"],
    time_range_type="acquired",
)

# define a delivery method. In this example, we're using AWS S3.
delivery = amazon_s3(ACCESS_KEY_ID, SECRET_ACCESS_KEY, "test", "us-east-1")

# build the request payload
request = build_request("Standard PSScene Ortho Analytic", source=source, delivery=delivery, clip_to_source=True)

# finally, create the subscription
# subscription = pl.subscriptions.create_subscription(request)
```

--------------------------------

### Create, Wait, and Download Order

Source: https://github.com/planetlabs/planet-client-python/blob/main/docs/cli/cli-orders.md

Combines order creation, waiting for availability, and downloading into a single, automated command sequence using shell scripting.

```sh
id=`planet orders create request-1.json | jq -r '.id'` && \
    planet orders wait $id && planet orders download $id
```