Raise an error on APILayoutStrategy when root_href is non-url

pystac/catalog.py

@@ -15,8 +15,9 @@
 
 import pystac
 from pystac.cache import ResolvedObjectCache
-from pystac.errors import STACTypeError
+from pystac.errors import STACError, STACTypeError
 from pystac.layout import (
+    APILayoutStrategy,
     BestPracticesLayoutStrategy,
     HrefLayoutStrategy,
     LayoutTemplate,
@@ -32,6 +33,7 @@
     HREF,
     StringEnum,
     is_absolute_href,
+    is_url,
     make_absolute_href,
     make_relative_href,
 )
@@ -769,6 +771,9 @@ def normalize_hrefs(
         if not is_absolute_href(root_href):
             root_href = make_absolute_href(root_href, os.getcwd(), start_is_dir=True)
 
+        if isinstance(_strategy, APILayoutStrategy) and not is_url(root_href):
+            raise STACError("When using APILayoutStrategy the root_href must be a URL")
+
         def process_item(
             item: Item, _root_href: str, is_root: bool, parent: Catalog | None
         ) -> Callable[[], None] | None:

pystac/stac_io.py

@@ -16,7 +16,7 @@
     merge_common_properties,
     migrate_to_latest,
 )
-from pystac.utils import HREF, safe_urlparse
+from pystac.utils import HREF, is_url, safe_urlparse
 
 # Use orjson if available
 try:
@@ -294,7 +294,7 @@ def read_text_from_href(self, href: str) -> str:
             href : The URI of the file to open.
         """
         href_contents: str
-        if _is_url(href):
+        if is_url(href):
             try:
                 logger.debug(f"GET {href} Headers: {self.headers}")
                 req = Request(href, headers=self.headers)
@@ -327,7 +327,7 @@ def write_text_to_href(self, href: str, txt: str) -> None:
             href : The path to which the file will be written.
             txt : The string content to write to the file.
         """
-        if _is_url(href):
+        if is_url(href):
             raise NotImplementedError("DefaultStacIO cannot write to urls")
         href = safe_urlparse(href).path
         dirname = os.path.dirname(href)
@@ -390,11 +390,6 @@ def _report_duplicate_object_names(
         return result
 
 
-def _is_url(href: str) -> bool:
-    parsed = safe_urlparse(href)
-    return parsed.scheme not in ["", "file"]
-
-
 if HAS_URLLIB3:
     from typing import cast
 
@@ -433,7 +428,7 @@ def read_text_from_href(self, href: str) -> str:
             Args:
                 href : The URI of the file to open.
             """
-            if _is_url(href):
+            if is_url(href):
                 # TODO provide a pooled StacIO to enable more efficient network
                 # access (probably named `PooledStacIO`).
                 http = PoolManager()

pystac/utils.py

@@ -605,3 +605,8 @@ def is_file_path(href: str) -> bool:
     """
     parsed = urlparse(href)
     return bool(os.path.splitext(parsed.path)[1])
+
+
+def is_url(href: str) -> bool:
+    parsed = safe_urlparse(href)
+    return parsed.scheme not in ["", "file"]

tests/test_catalog.py

@@ -25,6 +25,7 @@
     MediaType,
 )
 from pystac.layout import (
+    APILayoutStrategy,
     BestPracticesLayoutStrategy,
     HrefLayoutStrategy,
     TemplateLayoutStrategy,
@@ -1968,3 +1969,15 @@ def test_add_item_layout_strategy(
     template = template.format(id=item.id).replace("$", "")
 
     assert item.self_href == f"{base_url}/{template}/{item_id}.json"
+
+
+def test_APILayoutStrategy_requires_root_to_be_url(
+    catalog: Catalog, collection: Collection, item: Item
+) -> None:
+    collection.add_item(item)
+    catalog.add_child(collection)
+    with pytest.raises(
+        pystac.errors.STACError,
+        match="When using APILayoutStrategy the root_href must be a URL",
+    ):
+        catalog.normalize_hrefs(root_href="issues-1486", strategy=APILayoutStrategy())