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

Author: Tom Augspurger

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. 

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",
+]

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:

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)),
+        )