Repository: planetlabs/planet-client-python

Issue:
Add Sentinel-2 to Harmonization tool
**Is your feature request related to a problem? Please describe.**
Our SDK only allows data harmonization with Dove Classic, however the [openAPI spec ](https://developers.planet.com/apis/orders/reference/#tag/Orders/operation/createOrder) has added Sentinel-2 as a target sensor for harmonization.

I propose we add Sentinel-2 as an option for harmonization to the Orders API.

**Describe the solution you'd like**

Current [harmonization tool](https://github.com/planetlabs/planet-client-python/blob/main/planet/order_request.py#L432):
```
def harmonize_tool() -> dict:
    '''Create the API spec representation of a harmonize tool.

    Currently, only "PS2" (Dove Classic) is supported as a target sensor, and
    it will transform only items captured by “PS2.SD” (Dove-R).
    '''
    return _tool('harmonize', {'target_sensor': 'PS2'})
```

Proposed solution:
```
def harmonize_tool(target_sensor: str) -> dict:
    '''Create the API spec representation of a harmonize tool.

    Currently, only "PS2" (Dove Classic) and "Sentinel-2" are supported as 
    target sensors. Dove-R can only be transformed by PS2 and Sentinel-2 can 
    only transform surface reflectance bundles for PSScene 
    (ie., analytic_8b_sr_udm2, analytic_sr_udm2).
    '''
    return _tool('harmonize', {'target_sensor': target_sensor})
```

I also suggest adding a test for hamonization in `tests/unit/test_order_request.py`:
```
@pytest.mark.parametrize("target_sensor", ["PS2", "Sentinel-2"])
def test_harmonization_tool(target_sensor):
    ht = order_request.harmonize_tool(target_sensor)
    expected = {'harmonize': {'target_sensor': target_sensor}}
    assert ht == expected
```

**Additional context**
I would double check the sensor harmonization compatibility on the [Dev Center](https://developers.planet.com/apis/orders/tools/#harmonization).


Comments:

Patch:
diff --git a/docs/cli/cli-orders.md b/docs/cli/cli-orders.md
index 7804dff..f2561c7 100644
--- a/docs/cli/cli-orders.md
+++ b/docs/cli/cli-orders.md
@@ -467,7 +467,23 @@ curl -s https://raw.githubusercontent.com/planetlabs/planet-client-python/main/d
 
 ### Harmonize
 
-TODO
+The harmonize tool allows you to compare data to different generations of satellites by radiometrically harmonizing imagery captured by one satellite instrument type to imagery captured by another. To harmonize your data to a sensor you must define the sensor you wish to harmonize with in your `tools.json`. Currently, only "PS2" (Dove Classic) and "Sentinel-2" are supported as target sensors. The Sentinel-2 target only harmonizes PSScene surface reflectance bundle types (`analytic_8b_sr_udm2`, `analytic_sr_udm2`). The PS2 target only works on analytic bundles from Dove-R (`PS2.SD`).
+
+```json
+[
+  {
+    "harmonize": {
+      "target_sensor": "Sentinel-2"
+      }
+    }
+]
+```
+
+You may create an order request by calling `tools.json` with `--tools`.
+
+```console
+planet orders request psscene analytic_sr_udm2 --name "Harmonized data" --id 20200925_161029_69_2223 --tools tools.json
+```
 
 ### STAC Metadata
 
diff --git a/docs/resources/index.md b/docs/resources/index.md
index 335931d..8da0223 100644
--- a/docs/resources/index.md
+++ b/docs/resources/index.md
@@ -2,26 +2,45 @@
 title: Resources
 ---
 
-## This Build
+## Examples
 
-[Planet](https://planet.com) Software Development Kit (SDK) for Python [![Build Status](https://travis-ci.org/planetlabs/planet-client-python.svg?branch=master)](https://travis-ci.org/planetlabs/planet-client-python)
+### SDK examples
 
+The following examples were created specifically to show you how to use the SDK and CLI:
+
+* [download_multiple_assets.py](https://github.com/planetlabs/planet-client-python/blob/main/examples/download_multiple_assets.py) - this Python script orders, activates, and downloads two assets
+* [orders_create_and_download_multiple_orders.py](https://github.com/planetlabs/planet-client-python/blob/main/examples/orders_create_and_download_multiple_orders.py) - this Python script creates two orders, each with unique Area of Interest (AoI), preventing a combined download
+* [Planet API Python Client](https://github.com/planetlabs/notebooks/blob/master/jupyter-notebooks/data-api-tutorials/planet_python_client_introduction.ipynb) - a Python notebook to introduce Planet’s Data API and the `planet` module
+* [Orders API & Planet SDK](https://github.com/planetlabs/notebooks/blob/665f165e59f2c3584976ad2dde569c649e631c0b/jupyter-notebooks/orders_api_tutorials/Planet_SDK_Orders_demo.ipynb) - a Python notebook shows how to get started with Planet SDK and the Orders API.
+* [Analysis Ready Data Tutorial Part 1: Introduction and Best Practices](https://github.com/planetlabs/notebooks/blob/6cc220ff6db246353af4798be219ee1fe7e858b0/jupyter-notebooks/analysis-ready-data/ard_1_intro_and_best_practices.ipynb) - this Python notebook uses the SDK to prepare Analysis Ready Data.
+* [Analysis Ready Data Tutorial Part 2](https://github.com/planetlabs/notebooks/blob/6cc220ff6db246353af4798be219ee1fe7e858b0/jupyter-notebooks/analysis-ready-data/ard_2_use_case_1.ipynb) - the first use case in this Python notebook leverages the SDK’s `order_request` feature to prepare an NDVI time stack and the second use case visualizes the NDVI imagery.
+
+### Other examples
+
+Besides the SDK-specific examples, above, you can find many examples that show how to access Planet data in the documentation and Planet School at the [Planet Developers Center](https://developers.planet.com).Also, more working examples are on the [Planet Labs Python notebooks](https://github.com/planetlabs/notebooks) on GitHub.
 
 ## Planet APIs
 
-## Planet Tutorials
+This pre-release SDK has implemented interfaces for several Planet APIs. Check out the documentation for the underlying API:
 
-## Contact Support
+* [Data](https://developers.planet.com/docs/apis/data/)
+* [Orders](https://developers.planet.com/apis/orders/)
+* [Subscriptions](https://developers.planet.com/docs/subscriptions/)
 
 ## Email Developer Relations
 
+We are eager to share this pre-release with you and encourage you to test your workflows rigorously. Based on your feedback, we may roll out additional updates to improve your experience. Besides joining the discussion, and filing issues and pull requests here, feel free to share your general feedback with us at developers@planet.com.
+## Contribute to this open source project
+
+To contribute or develop with this library, see
+[CONTRIBUTING](https://github.com/planetlabs/planet-client-python/blob/main/CONTRIBUTING.md).
+
 ## Build Status
 
+[Planet Software Development Kit (SDK) for Python main branch](https://github.com/planetlabs/planet-client-python)
+
 [![Build Status](https://travis-ci.org/planetlabs/planet-client-python.svg?branch=master)](https://travis-ci.org/planetlabs/planet-client-python)
 
-[Planet](https://planet.com) Software Development Kit (SDK) for Python.
+## Version 1 of this SDK
 
-## Contribute to this open source project
-
-To contribute or develop with this library, see
-[CONTRIBUTING](https://github.com/planetlabs/planet-client-python/CONTRIBUTING.md).
+[Version 1 of this SDK](https://github.com/planetlabs/planet-client-python/tree/1.5.2) is significantly different (see the [documentation](https://planet-sdk-for-python.readthedocs.io/en/latest/)). Version 2 is not backward compatible. Make sure to create a separate virtual environment if you need to work with both versions. For more information on how to do this, see the [Virtual Environments and the Planet SDK for Python](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/get-started/venv-tutorial/).
\ No newline at end of file
diff --git a/planet/order_request.py b/planet/order_request.py
index 34b4cbb..586c44f 100644
--- a/planet/order_request.py
+++ b/planet/order_request.py
@@ -429,10 +429,12 @@ def toar_tool(scale_factor: Optional[int] = None, ) -> dict:
     return _tool('toar', parameters)
 
 
-def harmonize_tool() -> dict:
+def harmonize_tool(target_sensor: str) -> dict:
     '''Create the API spec representation of a harmonize tool.
 
-    Currently, only "PS2" (Dove Classic) is supported as a target sensor, and
-    it will transform only items captured by “PS2.SD” (Dove-R).
+    Currently, only "PS2" (Dove Classic) and "Sentinel-2" are supported as
+    target sensors. The Sentinel-2 target only harmonizes PSScene
+    surface reflectance bundle types (analytic_8b_sr_udm2, analytic_sr_udm2).
+    The PS2 target only works on analytic bundles from Dove-R (PS2.SD).
     '''
-    return _tool('harmonize', {'target_sensor': 'PS2'})
+    return _tool('harmonize', {'target_sensor': target_sensor})


Test patch:
diff --git a/tests/unit/test_order_request.py b/tests/unit/test_order_request.py
index 0163357..49e3554 100644
--- a/tests/unit/test_order_request.py
+++ b/tests/unit/test_order_request.py
@@ -251,3 +251,10 @@ def test_toar_tool():
     tt_empty = order_request.toar_tool()
     expected_empty = {'toar': {}}
     assert tt_empty == expected_empty
+
+
+@pytest.mark.parametrize("target_sensor", ["PS2", "Sentinel-2"])
+def test_harmonization_tool(target_sensor):
+    ht = order_request.harmonize_tool(target_sensor)
+    expected = {'harmonize': {'target_sensor': target_sensor}}
+    assert ht == expected