Use Protocol

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>

Author: bact

pyproject.toml

@@ -70,6 +70,7 @@ explicit_package_bases = true
 # they are excluded below so they don't mask issues in the new code.
 files = [
     "src/spdx_tools/spdx3/formats.py",
+    "src/spdx_tools/spdx3/object_set.py",
     "src/spdx_tools/spdx3/parser",
 ]
 

src/spdx_tools/spdx3/object_set.py

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: 2026-present SPDX contributors
+# SPDX-License-Identifier: Apache-2.0
+from typing import Any, Iterable, Optional, Protocol, Set, runtime_checkable
+
+
+@runtime_checkable
+class SpdxObjectSet(Protocol):
+    """Version-agnostic structural type for a SHACL object set.
+
+    Satisfied by ``SHACLObjectSet`` from any ``spdx_python_model.vX_Y_Z``
+    version module, so callers are not tied to a specific SPDX spec version.
+    """
+
+    def foreach(self) -> Iterable[Any]: ...
+
+    def foreach_type(self, typ: Any, *, match_subclass: bool = True) -> Iterable[Any]: ...
+
+    def find_by_id(self, _id: str, default: Optional[Any] = None) -> Optional[Any]: ...
+
+    def add(self, obj: Any) -> Any: ...
+
+    def link(self) -> Set[str]: ...

src/spdx_tools/spdx3/parser/json_ld/json_ld_parser.py

@@ -2,13 +2,14 @@
 # SPDX-License-Identifier: Apache-2.0
 from spdx_python_model import v3_0_1 as spdx_3_0
 
+from spdx_tools.spdx3.object_set import SpdxObjectSet
 from spdx_tools.spdx.parser.error import SPDXParsingError
 
 
-def parse_from_file(file_name: str, encoding: str = "utf-8") -> spdx_3_0.SHACLObjectSet:
+def parse_from_file(file_name: str, encoding: str = "utf-8") -> SpdxObjectSet:
     """Read a SPDX 3 JSON-LD file into a SHACLObjectSet (the in-memory representation
     provided by the spdx-python-model bindings)."""
-    object_set: spdx_3_0.SHACLObjectSet = spdx_3_0.SHACLObjectSet()
+    object_set = spdx_3_0.SHACLObjectSet()
     try:
         # The binding's deserializer reads from a binary stream.
         with open(file_name, "rb") as file:

src/spdx_tools/spdx3/parser/parse_anything.py

@@ -1,13 +1,12 @@
 # SPDX-FileCopyrightText: 2026-present SPDX contributors
 # SPDX-License-Identifier: Apache-2.0
-from spdx_python_model import v3_0_1 as spdx_3_0
-
 from spdx_tools.spdx3.formats import FileFormat, file_name_to_format
+from spdx_tools.spdx3.object_set import SpdxObjectSet
 from spdx_tools.spdx3.parser.json_ld import json_ld_parser
 from spdx_tools.spdx.parser.error import SPDXParsingError
 
 
-def parse_file(file_name: str, encoding: str = "utf-8") -> spdx_3_0.SHACLObjectSet:
+def parse_file(file_name: str, encoding: str = "utf-8") -> SpdxObjectSet:
     """Parse a SPDX 3 file into a SHACLObjectSet, dispatching on the file format.
 
     SPDX 3.0 currently defines a single serialization (JSON-LD); the dispatch is

tests/spdx3/parser/test_read.py

@@ -3,8 +3,8 @@
 import os
 
 import pytest
-from spdx_python_model import v3_0_1 as spdx_3_0
 
+from spdx_tools.spdx3.object_set import SpdxObjectSet
 from spdx_tools.spdx3.parser import parse_file
 from spdx_tools.spdx.parser.error import SPDXParsingError
 
@@ -14,7 +14,7 @@
 def test_parse_file_returns_object_set():
     object_set = parse_file(EXAMPLE_FILE)
 
-    assert isinstance(object_set, spdx_3_0.SHACLObjectSet)
+    assert isinstance(object_set, SpdxObjectSet)
 
     elements = list(object_set.foreach())
     assert len(elements) == 60