Sign vrt-strings

CHANGELOG.md

@@ -1,3 +1,9 @@
+# 0.4.4
+
+## New Features
+
+* `sign` will now sign VRT-like strings, like those returned by GDAL's [STACIT](https://gdal.org/drivers/raster/stacit.html) driver.
+
 # 0.4.3
 
 ## Bug Fixes

planetary_computer/__init__.py

@@ -11,6 +11,7 @@
 )
 from planetary_computer.settings import set_subscription_key
 
+from planetary_computer.version import __version__
 
 __all__ = [
     "set_subscription_key",
@@ -20,4 +21,5 @@
     "sign_item",
     "sign_url",
     "sign",
+    "__version__",
 ]

planetary_computer/sas.py

@@ -1,3 +1,4 @@
+import re
 from datetime import datetime, timezone
 from typing import Any, Dict, Optional
 import warnings
@@ -11,7 +12,13 @@
 from pystac_client import ItemSearch
 
 from planetary_computer.settings import Settings
-from planetary_computer.utils import parse_blob_url, parse_adlfs_url, is_fsspec_asset
+from planetary_computer.utils import (
+    parse_blob_url,
+    parse_adlfs_url,
+    is_fsspec_asset,
+    is_vrt_string,
+    asset_xpr,
+)
 
 
 BLOB_STORAGE_DOMAIN = ".blob.core.windows.net"
@@ -73,13 +80,41 @@ def sign(obj: Any) -> Any:
 
 
 @sign.register(str)
+def sign_string(url: str) -> str:
+    """Sign a URL or VRT-like string containing URLs with a Shared Access (SAS) Token
+
+    Signing with a SAS token allows read access to files in blob storage.
+
+    Args:
+        url (str): The HREF of the asset as a URL or a GDAL VRT
+
+            Single URLs can be found on a STAC Item's Asset ``href`` value. Only URLs to
+            assets in Azure Blob Storage are signed, other URLs are returned unmodified.
+
+            GDAL VRTs can combine many data sources into a single mosaic. A VRT can be
+            built quickly from the GDAL STACIT driver
+            https://gdal.org/drivers/raster/stacit.html. Each URL to Azure Blob Storage
+            within the VRT is signed.
+
+    Returns:
+        str: The signed HREF or VRT
+    """
+    if is_vrt_string(url):
+        return sign_vrt_string(url)
+    else:
+        return sign_url(url)
+
+
 def sign_url(url: str) -> str:
-    """Sign a URL with a Shared Access (SAS) Token, which allows for read access.
+    """Sign a URL or with a Shared Access (SAS) Token
+
+    Signing with a SAS token allows read access to files in blob storage.
 
     Args:
-        url (str): The HREF of the asset in the format of a URL.
-            This can be found on STAC Item's Asset 'href' value. Only URLs to assets
-            in Azure Blob Storage are signed, other URLs are returned unmodified.
+        url (str): The HREF of the asset as a URL
+
+            Single URLs can be found on a STAC Item's Asset ``href`` value. Only URLs to
+            assets in Azure Blob Storage are signed, other URLs are returned unmodified.
 
     Returns:
         str: The signed HREF
@@ -93,6 +128,46 @@ def sign_url(url: str) -> str:
     return token.sign(url).href
 
 
+def _repl_vrt(m: re.Match) -> str:
+    # replace all blob-storages URLs with a signed version.
+    return sign_url(m.string[slice(*m.span())])
+
+
+def sign_vrt_string(vrt: str) -> str:
+    """Sign a VRT-like string containing URLs with a Shared Access (SAS) Token
+
+    Signing with a SAS token allows read access to files in blob storage.
+
+    Args:
+        vrt (str): The GDAL VRT
+
+            GDAL VRTs can combine many data sources into a single mosaic. A VRT can be
+            built quickly from the GDAL STACIT driver
+            https://gdal.org/drivers/raster/stacit.html. Each URL to Azure Blob Storage
+            within the VRT is signed.
+
+    Returns:
+        str: The signed VRT
+
+    Examples
+    --------
+    >>> from osgeo import gdal
+    >>> from pathlib import Path
+    >>> search = (
+    ...     "STACIT:\"https://planetarycomputer.microsoft.com/api/stac/v1/search?"
+    ...     "collections=naip&bbox=-100,40,-99,41"
+    ...     "&datetime=2019-01-01T00:00:00Z%2F..\":asset=image"
+    ... )
+    >>> gdal.Translate("out.vrt", search)
+    >>> signed_vrt = planetary_computer.sign(Path("out.vrt").read_text())
+    >>> print(signed_vrt)
+    <VRTDataset rasterXSize="161196" rasterYSize="25023">
+    ...
+    </VRTDataset>
+    """
+    return asset_xpr.sub(_repl_vrt, vrt)
+
+
 @sign.register(Item)
 def sign_item(item: Item) -> Item:
     """Sign all assets within a PySTAC item

planetary_computer/utils.py

@@ -1,3 +1,5 @@
+import re
+
 from typing import Tuple, Optional
 from urllib.parse import ParseResult, urlunparse, urlparse
 
@@ -57,3 +59,18 @@ def is_fsspec_asset(asset: pystac.Asset) -> bool:
     return "account_name" in asset.extra_fields.get(
         "table:storage_options", {}
     ) or "account_name" in asset.extra_fields.get("xarray:storage_options", {})
+
+
+def is_vrt_string(s: str) -> bool:
+    """
+    Check whether a string looks like a VRT
+    """
+    return s.strip().startswith("<VRTDataset") and s.strip().endswith("</VRTDataset>")
+
+
+asset_xpr = re.compile(
+    r"https://(?P<account>[A-z0-9]+?)"
+    r"\.blob\.core\.windows\.net/"
+    r"(?P<container>.+?)"
+    r"/(?P<blob>[^<]+)"
+)

planetary_computer/version.py

@@ -1,2 +1,3 @@
-__version__ = "0.4.3"
 """Library version"""
+
+__version__ = "0.4.4"

requirements-dev.txt

@@ -1,5 +1,6 @@
-black==20.8b1
-flake8==3.8.4
+black==21.10b0
+flake8==4.0.1
 ipdb==0.13.7
-mypy==0.790
-setuptools==56.0.0
+mypy==0.910
+types-requests==2.26.0
+setuptools==58.5.3

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = planetary-computer
-version = 0.4.3
+version = 0.4.4
 license_file = LICENSE
 author = microsoft
 author_email = planetarycomputer@microsoft.com