Jak/stapi v0.2.0

.github/workflows/ci.yaml

@@ -31,8 +31,6 @@ jobs:
         run: uv run pre-commit run --all-files
       - name: Test
         run: ./scripts/run-tests.sh
-      - name: Validate test server
-        run: uv run scripts/validate-stapi-fastapi
       - name: Docs
         run: uv run mkdocs build --strict
       - uses: actions/upload-pages-artifact@v3

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
 
       - id: mypy
         name: Check typing with mypy
-        entry: uv run mypy
+        entry: ./scripts/run-mypy.sh
         language: system
         types: [python]
         pass_filenames: false

pyproject.toml

@@ -9,6 +9,7 @@ dependencies = [
     "pystapi-validator",
     "stapi-pydantic",
     "stapi-fastapi",
+    "pystapi-schema-generator",
 ]
 
 [dependency-groups]
@@ -19,6 +20,8 @@ dev = [
     "pre-commit>=4.2.0",
     "pre-commit-hooks>=5.0.0",
     "pygithub>=2.6.1",
+    "pyyaml>=6.0",
+    "types-pyyaml>=6.0",
 ]
 docs = [
     "mkdocs-material>=9.6.11",
@@ -29,13 +32,14 @@ docs = [
 default-groups = ["dev", "docs"]
 
 [tool.uv.workspace]
-members = ["pystapi-validator", "stapi-pydantic", "pystapi-client", "stapi-fastapi"]
+members = ["pystapi-validator", "stapi-pydantic", "pystapi-client", "stapi-fastapi", "pystapi-schema-generator"]
 
 [tool.uv.sources]
 pystapi-client.workspace = true
 pystapi-validator.workspace = true
 stapi-pydantic.workspace = true
 stapi-fastapi.workspace = true
+pystapi-schema-generator.workspace = true
 
 [tool.ruff]
 line-length = 120
@@ -62,11 +66,12 @@ files = [
     "pystapi-client/src/pystapi_client/**/*.py",
     "pystapi-validator/src/pystapi_validator/**/*.py",
     "stapi-pydantic/src/stapi_pydantic/**/*.py",
-    "stapi-fastapi/src/stapi_fastapi/**/*.py"
+    "stapi-fastapi/src/stapi_fastapi/**/*.py",
+    "pystapi-schema-generator/src/pystapi_schema_generator/**/*.py"
 ]
 
 [[tool.mypy.overrides]]
-module = "pygeofilter.parsers.*"
+module = "respx.*"
 ignore_missing_imports = true
 
 [tool.pymarkdown]
@@ -81,7 +86,11 @@ filterwarnings = [
     "ignore:The 'app' shortcut is now deprecated.:DeprecationWarning",
     "ignore:Pydantic serializer warnings:UserWarning",
     "ignore:jsonschema.exceptions.RefResolutionError is deprecated:DeprecationWarning",
+    # Both raised by schemathesis<4, which still uses the pre-4.18 jsonschema
+    # referencing API. Removable once the validator moves to schemathesis 4.
+    "ignore:jsonschema.RefResolver is deprecated:DeprecationWarning",
 ]
 markers = [
     "mock_products",
+    "root_router_kwargs",
 ]

pystapi-client/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pystapi-client"
-version = "0.0.1"
+version = "0.0.2"
 description = "Python library for searching Satellite Tasking API (STAPI) APIs."
 readme = "README.md"
 authors = [
@@ -14,7 +14,7 @@ license = { text = "MIT" }
 requires-python = ">=3.11"
 dependencies = [
     "httpx>=0.28.1",
-    "stapi-pydantic",
+    "stapi-pydantic>=0.2.0",
     "python-dateutil>=2.8.2",
     "click>=8.1.8",
 ]

pystapi-client/src/pystapi_client/client.py

@@ -11,15 +11,18 @@
 from pydantic import AnyUrl
 from stapi_pydantic import (
     CQL2Filter,
+    Geometry,
     Link,
     Opportunity,
     OpportunityCollection,
-    OpportunityPayload,
+    OpportunityProperties,
+    OpportunityRequest,
     Order,
     OrderCollection,
-    OrderPayload,
+    OrderParameters,
+    OrderRequest,
     Product,
-    ProductsCollection,
+    ProductCollection,
 )
 
 from pystapi_client.conformance import ConformanceClasses
@@ -257,13 +260,52 @@ def has_conformance(self, conformance_class: ConformanceClasses | str) -> bool:
 
         return any(re.match(conformance_class.pattern, uri) for uri in self.get_conforms_to())
 
-    def _supports_opportunities(self) -> bool:
-        """Check if the API supports opportunities"""
-        return self.has_conformance(ConformanceClasses.OPPORTUNITIES)
+    def _product_has_conformance(
+        self,
+        product: str | Product,
+        conformance_class: ConformanceClasses,
+    ) -> bool:
+        """Check whether a Product advertises the given conformance class.
+
+        Opportunity capability classes are advertised per-Product, not in the
+        root landing page.
+
+        Args:
+            product: A Product ID or an already-fetched
+                :class:`~stapi_pydantic.Product`. If an ID is given the Product
+                is fetched from the API.
+            conformance_class: The conformance class to check for.
+
+        Return:
+            Whether the Product conforms to the given class.
+        """
+        if isinstance(product, str):
+            product = self.get_product(product)
+        return any(re.match(conformance_class.pattern, uri) for uri in product.conforms_to)
+
+    def product_supports_opportunities(self, product: str | Product) -> bool:
+        """Check if a Product supports synchronous opportunity search.
+
+        Args:
+            product: A Product ID or an already-fetched
+                :class:`~stapi_pydantic.Product`.
+
+        Return:
+            Whether the Product supports synchronous opportunity search.
+        """
+        return self._product_has_conformance(product, ConformanceClasses.OPPORTUNITIES)
+
+    def product_supports_async_opportunities(self, product: str | Product) -> bool:
+        """Check if a Product supports asynchronous opportunity search.
 
-    def _supports_async_opportunities(self) -> bool:
-        """Check if the API supports asynchronous opportunities"""
-        return self.has_conformance(ConformanceClasses.ASYNC_OPPORTUNITIES)
+        Args:
+            product: A Product ID or an already-fetched
+                :class:`~stapi_pydantic.Product`.
+
+        Return:
+            Whether the Product supports asynchronous opportunity search.
+        """
+        return self._product_has_conformance(product, ConformanceClasses.ASYNC_OPPORTUNITIES)
 
     def get_products(self, limit: int | None = None) -> Iterator[Product]:
         """Get all products from this STAPI API
@@ -282,7 +324,7 @@ def get_products(self, limit: int | None = None) -> Iterator[Product]:
 
         products_collection_iterator = self.stapi_io.get_pages(link=products_link, lookup_key="products")
         for products_collection in products_collection_iterator:
-            yield from ProductsCollection.model_validate(products_collection).products
+            yield from ProductCollection.model_validate(products_collection).products
 
     def get_product(self, product_id: str) -> Product:
         """Get a single product from this STAPI API
@@ -302,10 +344,9 @@ def get_product_opportunities(
         product_id: str,
         date_range: tuple[str, str],
         geometry: dict[str, Any],
-        cql2_filter: CQL2Filter | None = None,  # type: ignore[type-arg]
+        cql2_filter: CQL2Filter | None = None,
         limit: int = 10,
-    ) -> Iterator[Opportunity]:  # type: ignore[type-arg]
-        # TODO Update return type after the pydantic model generic type is fixed
+    ) -> Iterator[Opportunity[Geometry, OpportunityProperties]]:
         """Get all opportunities for a product from this STAPI API
         Args:
             product_id: The Product ID to get opportunities for
@@ -316,14 +357,16 @@ def get_product_opportunities(
         """
         product_opportunities_endpoint = self._get_products_href(product_id, subpath="opportunities")
 
-        opportunity_parameters = OpportunityPayload.model_validate(
+        opportunity_parameters = OpportunityRequest.model_validate(
             {
-                "datetime": (
-                    datetime.fromisoformat(date_range[0]),
-                    datetime.fromisoformat(date_range[1]),
-                ),
-                "geometry": geometry,
-                "filter": cql2_filter,
+                "search_parameters": {
+                    "datetime": (
+                        datetime.fromisoformat(date_range[0]),
+                        datetime.fromisoformat(date_range[1]),
+                    ),
+                    "geometry": geometry,
+                    "filter": cql2_filter,
+                },
                 "limit": limit,
             }
         )
@@ -348,8 +391,7 @@ def get_product_opportunities(
         for opportunity_collection in product_opportunities_json:
             yield from OpportunityCollection.model_validate(opportunity_collection).features
 
-    def create_product_order(self, product_id: str, order_parameters: OrderPayload) -> Order:  # type: ignore[type-arg]
-        # TODO Update return type after the pydantic model generic type is fixed
+    def create_product_order(self, product_id: str, order_parameters: OrderRequest[OrderParameters]) -> Order:
         """Create an order for a product
 
         Args:
@@ -393,8 +435,7 @@ def _get_products_href(self, product_id: str | None = None, subpath: str | None
 
         return str(product_url)
 
-    def get_orders(self, limit: int | None = None) -> Iterator[Order]:  # type: ignore[type-arg]
-        # TODO Update return type after the pydantic model generic type is fixed
+    def get_orders(self, limit: int | None = None) -> Iterator[Order]:
         """Get orders from this STAPI API
 
         Args:
@@ -416,8 +457,7 @@ def get_orders(self, limit: int | None = None) -> Iterator[Order]:  # type: igno
         for orders_collection in orders_collection_iterator:
             yield from OrderCollection.model_validate(orders_collection).features
 
-    def get_order(self, order_id: str) -> Order:  # type: ignore[type-arg]
-        # TODO Update return type after the pydantic model generic type is fixed
+    def get_order(self, order_id: str) -> Order:
         """Get a single order from this STAPI API
 
         Args:

pystapi-client/src/pystapi_client/conformance.py

@@ -6,9 +6,14 @@ class ConformanceClasses(Enum):
     """Enumeration class for Conformance Classes"""
 
     # defined conformance classes regexes
+    # API-level classes (advertised in the root landing page / `/conformance`)
     CORE = "/core"
+    ORDER_STATUSES = "/order-statuses"
+    SEARCHES_OPPORTUNITY = "/searches-opportunity"
+    SEARCHES_OPPORTUNITY_STATUSES = "/searches-opportunity-statuses"
+    # Product-level classes (advertised in a Product's own `conformsTo`)
     OPPORTUNITIES = "/opportunities"
-    ASYNC_OPPORTUNITIES = "/async-opportunities"
+    ASYNC_OPPORTUNITIES = "/opportunities-async"
 
     @classmethod
     def get_by_name(cls, name: str) -> "ConformanceClasses":
@@ -29,4 +34,4 @@ def valid_uri(self) -> str:
 
     @property
     def pattern(self) -> re.Pattern[str]:
-        return re.compile(rf"{re.escape('https://stapi.example.com/v')}(.*){re.escape(self.value)}")
+        return re.compile(rf"{re.escape('https://stapi.example.com/v')}[^/]+{re.escape(self.value)}\Z")

pystapi-client/tests/conftest.py

@@ -14,7 +14,7 @@
 
 def load_fixture(name: str) -> dict[str, Any]:
     with open(WORKING_DIR / "fixtures" / f"{name}.json") as f:
-        return cast(dict, json.load(f))
+        return cast(dict[str, Any], json.load(f))
 
 
 @pytest.fixture
@@ -37,7 +37,8 @@ def mock_products_response(request: Request) -> Response:
                 start_index = (page - 1) * int(limit)
                 end_index = start_index + int(limit)
                 products_limited["products"] = products_limited["products"][start_index:end_index]
-                has_next_page = end_index < len(products_limited["products"]) + 1
+                # against the full fixture, not the page just sliced out of it
+                has_next_page = end_index < len(products["products"])
                 if has_next_page:
                     products_limited["links"].append(
                         {
@@ -51,4 +52,7 @@ def mock_products_response(request: Request) -> Response:
         respx_mock.get("/products").mock(side_effect=mock_products_response)
         respx_mock.get("/products", params={"limit": 1}).mock(side_effect=mock_products_response)
 
+        for product in products["products"]:
+            respx_mock.get(f"/products/{product['id']}").return_value = Response(200, json=product)
+
         yield respx_mock

pystapi-client/tests/fixtures/landing_page.json

@@ -3,9 +3,10 @@
     "title": "A simple STAPI Example",
     "description": "This API demonstrated the landing page for a SpatioTemporal Asset Tasking API",
     "conformsTo": [
-        "https://stapi.example.com/v0.1.0/core",
-        "https://geojson.org/schema/Point.json",
-        "https://geojson.org/schema/Polygon.json"
+        "https://stapi.example.com/v0.2.0/core",
+        "https://stapi.example.com/v0.2.0/order-statuses",
+        "https://stapi.example.com/v0.2.0/searches-opportunity",
+        "https://stapi.example.com/v0.2.0/searches-opportunity-statuses"
     ],
     "links": [
         {

pystapi-client/tests/fixtures/products.json

@@ -1,8 +1,18 @@
 {
+    "stapi_type": "ProductCollection",
+    "stapi_version": "0.2.0",
     "products": [
         {
             "type": "Collection",
+            "stapi_type": "Product",
+            "stapi_version": "0.2.0",
             "id": "multispectral",
+            "conformsTo": [
+                "https://stapi.example.com/v0.2.0/opportunities",
+                "https://stapi.example.com/v0.2.0/opportunities-async",
+                "https://geojson.org/schema/Point.json",
+                "https://geojson.org/schema/Polygon.json"
+            ],
             "title": "Multispectral",
             "description": "Full color EO image",
             "keywords": [
@@ -103,7 +113,13 @@
         },
         {
             "type": "Collection",
+            "stapi_type": "Product",
+            "stapi_version": "0.2.0",
             "id": "spotlight",
+            "conformsTo": [
+                "https://geojson.org/schema/Point.json",
+                "https://geojson.org/schema/Polygon.json"
+            ],
             "title": "Spotlight",
             "description": "SAR Spotlight frame",
             "keywords": [