From 3656b6d5fc5e84e9f081bcd963d6c71f1fc49a65 Mon Sep 17 00:00:00 2001
From: Tom Augspurger <taugspurger@microsoft.com>
Date: Thu, 8 Jul 2021 14:04:15 -0500
Subject: [PATCH] API Updates (#19)

* API Updates

* Added `sign_*` to the public API, for users wishing to bypass the
  overhead of `sign`
* Restored `sign_assets` with a deprecation
* Added a changelog
---
 CHANGELOG.md                   | 14 ++++++++++++++
 planetary_computer/__init__.py | 22 ++++++++++++++++++++--
 planetary_computer/sas.py      | 19 +++++++++++++++----
 tests/test_signing.py          | 18 ++++++++++++++++++
 4 files changed, 67 insertions(+), 6 deletions(-)
 create mode 100644 CHANGELOG.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..3a63364
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,14 @@
+# 0.3.0
+
+## New Features
+
+* `sign` now works on strings, `pystac.Item`, `pystac.Asset`, `pystac.ItemCollection`, and `pystac_client.ItemSearch` instances.
+* Added top-level methods `sign_item`, `sign_asset`, and `sign_item_collection` to directly sign objects of those types.
+
+## Deprecations
+
+* `sign_assets` is deprecated. Use `sign_item` instead.
+
+## Bug Fixes
+
+* `sign_item` now handles items with assets containing links to files outside of blob storage by returning the asset unchanged. 
\ No newline at end of file
diff --git a/planetary_computer/__init__.py b/planetary_computer/__init__.py
index d2f7ef1..5d748d4 100644
--- a/planetary_computer/__init__.py
+++ b/planetary_computer/__init__.py
@@ -1,5 +1,23 @@
 """Planetary Computer Python SDK"""
 # flake8:noqa
 
-from planetary_computer.sas import sign  # type:ignore
-from planetary_computer.settings import set_subscription_key  # type:ignore
+from planetary_computer.sas import (
+    sign,
+    sign_url,
+    sign_item,
+    sign_assets,
+    sign_asset,
+    sign_item_collection,
+)
+from planetary_computer.settings import set_subscription_key
+
+
+__all__ = [
+    "set_subscription_key",
+    "sign_asset",
+    "sign_assets",
+    "sign_item_collection",
+    "sign_item",
+    "sign_url",
+    "sign",
+]
diff --git a/planetary_computer/sas.py b/planetary_computer/sas.py
index 0a7c52d..2af095d 100644
--- a/planetary_computer/sas.py
+++ b/planetary_computer/sas.py
@@ -1,5 +1,6 @@
 from datetime import datetime, timezone
 from typing import Any, Dict
+import warnings
 
 from functools import singledispatch
 from urllib.parse import urlparse
@@ -72,7 +73,7 @@ def sign(obj: Any) -> Any:
 
 
 @sign.register(str)
-def _sign_url(url: str) -> str:
+def sign_url(url: str) -> str:
     """Sign a URL with a Shared Access (SAS) Token, which allows for read access.
 
     Args:
@@ -111,7 +112,7 @@ def _sign_url(url: str) -> str:
 
 
 @sign.register(Item)
-def _sign_item(item: Item) -> Item:
+def sign_item(item: Item) -> Item:
     """Sign all assets within a PySTAC item
 
     Args:
@@ -130,7 +131,7 @@ def _sign_item(item: Item) -> Item:
 
 
 @sign.register(Asset)
-def _sign_asset(asset: Asset) -> Asset:
+def sign_asset(asset: Asset) -> Asset:
     """Sign a PySTAC asset
 
     Args:
@@ -145,8 +146,18 @@ def _sign_asset(asset: Asset) -> Asset:
     return signed_asset
 
 
+def sign_assets(item: Item) -> Item:
+    warnings.warn(
+        "'sign_assets' is deprecated and will be removed in a future version. Use "
+        "'sign_item' instead.",
+        FutureWarning,
+        stacklevel=2,
+    )
+    return sign_item(item)
+
+
 @sign.register(ItemCollection)
-def _sign_item_collection(item_collection: ItemCollection) -> ItemCollection:
+def sign_item_collection(item_collection: ItemCollection) -> ItemCollection:
     """Sign a PySTAC item collection
 
     Args:
diff --git a/tests/test_signing.py b/tests/test_signing.py
index 5e97962..da6d6fc 100644
--- a/tests/test_signing.py
+++ b/tests/test_signing.py
@@ -104,3 +104,21 @@ def test_search_and_sign(self) -> None:
         self.assertEqual(len(list(signed_item_collection)), 1)
         for signed_item in signed_item_collection:
             self.verify_signed_urls_in_item(signed_item)
+
+    def test_sign_assets_deprecated(self) -> None:
+        item = get_sample_item()
+        with self.assertWarns(FutureWarning):
+            pc.sign_assets(item)
+
+    def test_public_api(self) -> None:
+        item = get_sample_item()
+
+        self.assertEqual(type(pc.sign(item)), type(pc.sign_item(item)))
+        self.assertEqual(
+            type(pc.sign(item.assets["image"])),
+            type(pc.sign_asset(item.assets["image"])),
+        )
+        self.assertEqual(
+            type(pc.sign(item.assets["image"].href)),
+            type(pc.sign_url(item.assets["image"].href)),
+        )