refactor: split into recursive and max-depth

This makes it more clear how to enable/disable recursion.

Author: gadomski

README.md

@@ -95,12 +95,12 @@ make help
 **Basic Usage**
 
 ```bash
-stac_validator --help
-
-Usage: stac_validator [OPTIONS] STAC_FILE
+stac-validator --help
+Usage: stac-validator [OPTIONS] STAC_FILE
 
 Options:
-  --lint                   Use stac-check to lint stac object.
+  --lint                   Use stac-check to lint stac object instead of
+                           validating it.
   --core                   Validate core stac object only without extensions.
   --extensions             Validate extensions only.
   --links                  Additionally validate links. Only works with
@@ -109,8 +109,9 @@ Options:
                            default mode.
   -c, --custom TEXT        Validate against a custom schema (local filepath or
                            remote schema).
-  -r, --recursive INTEGER  Recursively validate all related stac objects. A
-                           depth of -1 indicates full recursion.
+  -r, --recursive          Recursively validate all related stac objects.
+  -m, --max-depth INTEGER  Maximum depth to traverse when recursing. Ignored
+                           if `recursive == False`.
   -v, --verbose            Enables verbose output for recursive mode.
   --no_output              Do not print output to console.
   --log_file TEXT          Save full recursive output to log file (local
@@ -277,7 +278,7 @@ stac_validator https://raw.githubusercontent.com/radiantearth/stac-spec/master/e
 **--recursive**
 
 ```bash
-stac_validator https://spot-canada-ortho.s3.amazonaws.com/catalog.json --recursive 1 --verbose
+stac_validator https://spot-canada-ortho.s3.amazonaws.com/catalog.json --recursive --max-depth 1 --verbose
 [
     {
         "version": "0.8.1",

stac_validator/stac_validator.py

@@ -38,9 +38,14 @@
 @click.option(
     "--recursive",
     "-r",
+    is_flag=True,
+    help="Recursively validate all related stac objects.",
+)
+@click.option(
+    "--max-depth",
+    "-m",
     type=int,
-    default=-2,
-    help="Recursively validate all related stac objects. A depth of -1 indicates full recursion.",
+    help="Maximum depth to traverse when recursing. Ignored if `recursive == False`.",
 )
 @click.option(
     "-v", "--verbose", is_flag=True, help="Enables verbose output for recursive mode."
@@ -56,6 +61,7 @@ def main(
     stac_file,
     lint,
     recursive,
+    max_depth,
     core,
     extensions,
     links,
@@ -73,6 +79,7 @@ def main(
         stac = StacValidate(
             stac_file=stac_file,
             recursive=recursive,
+            max_depth=max_depth,
             core=core,
             links=links,
             assets=assets,
@@ -87,7 +94,7 @@ def main(
         if no_output is False:
             click.echo(json.dumps(stac.message, indent=4))
 
-        if recursive == -2 and stac.message[0]["valid_stac"] is False:
+        if not recursive and stac.message[0]["valid_stac"] is False:
             sys.exit(1)
 
 

stac_validator/validate.py

@@ -1,7 +1,7 @@
 import json
 import os
 from json.decoder import JSONDecodeError
-from typing import List
+from typing import List, Optional
 from urllib.error import HTTPError, URLError
 
 import click  # type: ignore
@@ -21,7 +21,8 @@ class StacValidate:
     def __init__(
         self,
         stac_file: str = None,
-        recursive: int = -2,
+        recursive: bool = False,
+        max_depth: Optional[int] = None,
         core: bool = False,
         links: bool = False,
         assets: bool = False,
@@ -37,6 +38,7 @@ def __init__(
         self.links = links
         self.assets = assets
         self.recursive = recursive
+        self.max_depth = max_depth
         self.extensions = extensions
         self.core = core
         self.stac_content: dict = {}
@@ -202,8 +204,8 @@ def recursive_validator(self, stac_type: str):
             message["valid_stac"] = True
             self.message.append(message)
             self.depth = self.depth + 1
-            if self.recursive > -1:
-                if self.depth >= int(self.recursive):
+            if self.max_depth:
+                if self.depth >= self.max_depth:
                     self.skip_val = True
             base_url = self.stac_file
             for link in self.stac_content["links"]:
@@ -244,7 +246,9 @@ def recursive_validator(self, stac_type: str):
 
                     if self.log != "":
                         self.message.append(message)
-                    if self.recursive < 5:
+                    if (
+                        self.max_depth and self.max_depth < 5
+                    ):  # TODO this should be configurable, correct?
                         self.message.append(message)
                     if self.verbose is True:
                         click.echo(json.dumps(message, indent=4))
@@ -271,7 +275,7 @@ def run(cls):
                 message["schema"] = [cls.custom]
                 cls.custom_validator()
                 cls.valid = True
-            elif cls.recursive > -2:
+            elif cls.recursive:
                 cls.recursive_validator(stac_type)
                 cls.valid = True
             elif cls.extensions is True:
@@ -311,7 +315,7 @@ def run(cls):
 
         message["valid_stac"] = cls.valid
 
-        if cls.recursive < -1:
+        if not cls.recursive:
             cls.message.append(message)
 
         if cls.log != "":

tests/test_recursion.py

@@ -9,7 +9,7 @@
 
 def test_recursive_lvl_3_v070():
     stac_file = "https://radarstac.s3.amazonaws.com/stac/catalog.json"
-    stac = stac_validator.StacValidate(stac_file, recursive=4)
+    stac = stac_validator.StacValidate(stac_file, recursive=True, max_depth=4)
     stac.run()
     assert stac.message == [
         {
@@ -97,7 +97,7 @@ def test_recursive_lvl_3_v070():
 
 def test_recursive_local_v090():
     stac_file = "tests/test_data/v090/catalog.json"
-    stac = stac_validator.StacValidate(stac_file, recursive=1)
+    stac = stac_validator.StacValidate(stac_file, recursive=True, max_depth=1)
     stac.run()
     assert stac.message == [
         {
@@ -133,7 +133,7 @@ def test_recursive_local_v090():
 
 def test_recursive_v1beta1():
     stac_file = "tests/test_data/1beta1/sentinel2.json"
-    stac = stac_validator.StacValidate(stac_file, recursive=0)
+    stac = stac_validator.StacValidate(stac_file, recursive=True, max_depth=0)
     stac.run()
     assert stac.message == [
         {
@@ -149,7 +149,7 @@ def test_recursive_v1beta1():
 
 def test_recursive_v1beta2():
     stac_file = "https://raw.githubusercontent.com/stac-utils/pystac/main/tests/data-files/examples/1.0.0-beta.2/collection-spec/examples/sentinel2.json"
-    stac = stac_validator.StacValidate(stac_file, recursive=0)
+    stac = stac_validator.StacValidate(stac_file, recursive=True, max_depth=0)
     stac.run()
     assert stac.message == [
         {
@@ -167,7 +167,7 @@ def test_recursive_v1beta2():
 
 def test_recursion_collection_local_v1rc1():
     stac_file = "tests/test_data/1rc1/collection.json"
-    stac = stac_validator.StacValidate(stac_file, recursive=1)
+    stac = stac_validator.StacValidate(stac_file, recursive=True, max_depth=1)
     stac.run()
     assert stac.message == [
         {
@@ -219,7 +219,7 @@ def test_recursion_collection_local_v1rc1():
 
 def test_recursion_collection_local_v1rc2():
     stac_file = "tests/test_data/1rc2/collection.json"
-    stac = stac_validator.StacValidate(stac_file, recursive=1)
+    stac = stac_validator.StacValidate(stac_file, recursive=True, max_depth=1)
     stac.run()
     assert stac.message == [
         {
@@ -272,7 +272,7 @@ def test_recursion_collection_local_v1rc2():
 
 def test_recursion_collection_local_2_v1rc2():
     stac_file = "tests/test_data/1rc2/extensions-collection/collection.json"
-    stac = stac_validator.StacValidate(stac_file, recursive=1)
+    stac = stac_validator.StacValidate(stac_file, recursive=True, max_depth=1)
     stac.run()
     assert stac.message == [
         {