Jak/stapi v0.2.0

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,7 +66,8 @@ 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]]

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 = [

pystapi-client/src/pystapi_client/client.py

@@ -14,10 +14,10 @@
     Link,
     Opportunity,
     OpportunityCollection,
-    OpportunityPayload,
+    OpportunityRequest,
     Order,
     OrderCollection,
-    OrderPayload,
+    OrderRequest,
     Product,
     ProductsCollection,
 )
@@ -257,13 +257,53 @@ 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 (in the
+        Product's own ``conformsTo``, also served at
+        ``/products/{id}/conformance``), 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.conformsTo)
+
+    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
@@ -316,14 +356,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,7 +390,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]
+    def create_product_order(self, product_id: str, order_parameters: OrderRequest) -> Order:  # type: ignore[type-arg]
         # TODO Update return type after the pydantic model generic type is fixed
         """Create an order for a product
 

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

@@ -51,4 +51,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": [

pystapi-client/tests/test_client.py

@@ -1,4 +1,5 @@
 from pystapi_client.client import Client
+from pystapi_client.conformance import ConformanceClasses
 from respx import MockRouter
 from stapi_pydantic import Link
 
@@ -23,3 +24,90 @@ def test_pagination(api: MockRouter) -> None:
     products_link = Link(href="http://stapi.test/products", method="GET", body={"limit": 1}, rel="")
     for products_collection in client.stapi_io.get_pages(products_link, "products"):
         assert len(products_collection["products"]) == 1
+
+
+def test_async_opportunities_uri_matches_reference_server() -> None:
+    server_advertised = "https://stapi.example.com/v0.2.0/opportunities-async"
+    assert ConformanceClasses.ASYNC_OPPORTUNITIES.pattern.match(server_advertised)
+
+
+def test_sync_opportunities_uri_does_not_match_async_uri() -> None:
+    async_uri = "https://stapi.example.com/v0.2.0/opportunities-async"
+    assert not ConformanceClasses.OPPORTUNITIES.pattern.match(async_uri)
+    assert ConformanceClasses.OPPORTUNITIES.pattern.match("https://stapi.example.com/v0.2.0/opportunities")
+
+
+# --- Item 1: version pattern is a single path segment, anchored with \Z ---
+
+
+def test_version_pattern_matches_single_version_segment() -> None:
+    pattern = ConformanceClasses.OPPORTUNITIES.pattern
+    assert pattern.match("https://stapi.example.com/v0.2.0/opportunities")
+
+
+def test_version_pattern_rejects_extra_path_segments() -> None:
+    pattern = ConformanceClasses.OPPORTUNITIES.pattern
+    assert not pattern.match("https://stapi.example.com/v0.2.0/foo/opportunities")
+
+
+def test_version_pattern_rejects_empty_version() -> None:
+    pattern = ConformanceClasses.OPPORTUNITIES.pattern
+    assert not pattern.match("https://stapi.example.com/v/opportunities")
+
+
+def test_version_pattern_rejects_trailing_newline() -> None:
+    pattern = ConformanceClasses.OPPORTUNITIES.pattern
+    assert not pattern.match("https://stapi.example.com/v0.2.0/opportunities\n")
+
+
+# --- Item 2: API-level extension conformance classes exist in the enum ---
+
+
+def test_api_level_extension_classes_exist_and_match() -> None:
+    order_statuses = ConformanceClasses.get_by_name("ORDER_STATUSES")
+    searches_opportunity = ConformanceClasses.get_by_name("SEARCHES_OPPORTUNITY")
+    searches_opportunity_statuses = ConformanceClasses.get_by_name("SEARCHES_OPPORTUNITY_STATUSES")
+
+    assert order_statuses.pattern.match("https://stapi.example.com/v0.2.0/order-statuses")
+    assert searches_opportunity.pattern.match("https://stapi.example.com/v0.2.0/searches-opportunity")
+    assert searches_opportunity_statuses.pattern.match("https://stapi.example.com/v0.2.0/searches-opportunity-statuses")
+
+
+def test_searches_opportunity_does_not_match_statuses_uri() -> None:
+    searches_opportunity = ConformanceClasses.get_by_name("SEARCHES_OPPORTUNITY")
+    assert not searches_opportunity.pattern.match("https://stapi.example.com/v0.2.0/searches-opportunity-statuses")
+
+
+# --- Item 3 / 4: product-scoped opportunity capability checks ---
+
+
+def test_supports_opportunities_reads_product_conformance(api: MockRouter) -> None:
+    client = Client.open(url="http://stapi.test")
+    assert client.product_supports_opportunities("multispectral") is True
+
+
+def test_supports_async_opportunities_reads_product_conformance(api: MockRouter) -> None:
+    client = Client.open(url="http://stapi.test")
+    assert client.product_supports_async_opportunities("multispectral") is True
+
+
+def test_product_without_opportunities_returns_false(api: MockRouter) -> None:
+    client = Client.open(url="http://stapi.test")
+    assert client.product_supports_opportunities("spotlight") is False
+    assert client.product_supports_async_opportunities("spotlight") is False
+
+
+def test_opportunity_support_does_not_depend_on_root_conformance(api: MockRouter) -> None:
+    client = Client.open(url="http://stapi.test")
+    # Root conformsTo must not advertise the product-level opportunity classes.
+    assert not client.has_conformance(ConformanceClasses.OPPORTUNITIES)
+    assert not client.has_conformance(ConformanceClasses.ASYNC_OPPORTUNITIES)
+    # Yet the product does support opportunities per its own conformsTo.
+    assert client.product_supports_opportunities("multispectral") is True
+
+
+def test_root_advertises_api_level_extension_classes(api: MockRouter) -> None:
+    client = Client.open(url="http://stapi.test")
+    assert client.has_conformance(ConformanceClasses.CORE)
+    assert client.has_conformance("ORDER_STATUSES")
+    assert client.has_conformance("SEARCHES_OPPORTUNITY")

pystapi-schema-generator/README.md

@@ -0,0 +1,9 @@
+# pystapi-schema-generator
+
+A minimal reference STAPI application and console script for exporting its OpenAPI document as YAML.
+
+## Usage
+
+```bash
+pystapi-schema-generator > openapi.yaml
+```

pystapi-schema-generator/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "pystapi-schema-generator"
+version = "0.1.0"
+description = "Reference STAPI application and OpenAPI schema export tooling"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Christian Wygoda", email = "christian.wygoda@wygoda.net" },
+    { name = "Phil Varner", email = "phil@philvarner.com" },
+]
+requires-python = ">=3.11"
+dependencies = [
+    "stapi-fastapi>=0.9.0",
+    "pyyaml>=6.0",
+]
+
+[project.scripts]
+pystapi-schema-generator = "pystapi_schema_generator.application:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+]
+
+[tool.uv.sources]
+stapi-fastapi = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

pystapi-schema-generator/src/pystapi_schema_generator/__init__.py

@@ -0,0 +1,7 @@
+from .application import create_reference_app, export_openapi, main
+
+__all__ = [
+    "create_reference_app",
+    "export_openapi",
+    "main",
+]