stac-fastapi.extensions 6.3.2__tar.gz → 6.4.0__tar.gz

{stac_fastapi_extensions-6.3.2 → stac_fastapi_extensions-6.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stac-fastapi-extensions
-Version: 6.3.2
+Version: 6.4.0
 Summary: Extensions for stac-fastapi apis.
 Project-URL: Homepage, https://github.com/stac-utils/stac-fastapi
 Author-email: ArturoAI <engineering@arturo.ai>
@@ -16,5 +16,5 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
-Requires-Dist: stac-fastapi-api~=6.2
-Requires-Dist: stac-fastapi-types~=6.2
+Requires-Dist: stac-fastapi-api~=6.4
+Requires-Dist: stac-fastapi-types~=6.4

{stac_fastapi_extensions-6.3.2 → stac_fastapi_extensions-6.4.0}/pyproject.toml

@@ -32,8 +32,8 @@ classifiers = [
 ]
 dynamic = ["version"]
 dependencies = [
-    "stac-fastapi.types~=6.2",
-    "stac-fastapi.api~=6.2",
+    "stac-fastapi.types~=6.4",
+    "stac-fastapi.api~=6.4",
 ]
 
 [dependency-groups]

stac_fastapi_extensions-6.4.0/stac_fastapi/extensions/sort/__init__.py

@@ -0,0 +1,20 @@
+"""Sort extension module."""
+
+from .client import AsyncBaseSortablesClient, BaseSortablesClient
+from .sort import (
+    CollectionSearchSortExtension,
+    ItemCollectionSortExtension,
+    SearchSortExtension,
+    SortConformanceClasses,
+    SortExtension,
+)
+
+__all__ = [
+    "SortExtension",
+    "SearchSortExtension",
+    "ItemCollectionSortExtension",
+    "CollectionSearchSortExtension",
+    "SortConformanceClasses",
+    "AsyncBaseSortablesClient",
+    "BaseSortablesClient",
+]

stac_fastapi_extensions-6.4.0/stac_fastapi/extensions/sort/client.py

@@ -0,0 +1,107 @@
+"""Sort extension clients."""
+
+import abc
+from typing import Any
+
+import attr
+from starlette.requests import Request
+
+
+@attr.s
+class AsyncBaseSortablesClient(abc.ABC):
+    """Defines a pattern for implementing the STAC sort extension sortables endpoints."""
+
+    async def get_sortables(
+        self, request: Request | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Get the sortables available for item search.
+
+        This base implementation returns a blank sortables schema.
+        """
+        return {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "$id": "https://example.org/sortables",
+            "type": "object",
+            "title": "Sortables",
+            "properties": {},
+        }
+
+    async def get_collection_sortables(
+        self, collection_id: str, request: Request | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Get the sortables available for a specific collection.
+
+        This base implementation returns a blank sortables schema.
+        """
+        return {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "$id": f"https://example.org/collections/{collection_id}/sortables",
+            "type": "object",
+            "title": "Sortables",
+            "properties": {},
+        }
+
+    async def get_collections_sortables(
+        self, request: Request | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Get the sortables available for collection search.
+
+        This base implementation returns a blank sortables schema.
+        """
+        return {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "$id": "https://example.org/collections-sortables",
+            "type": "object",
+            "title": "Sortables",
+            "properties": {},
+        }
+
+
+@attr.s
+class BaseSortablesClient(abc.ABC):
+    """Defines a pattern for implementing the STAC sort extension sortables endpoints."""
+
+    def get_sortables(
+        self, request: Request | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Get the sortables available for item search.
+
+        This base implementation returns a blank sortables schema.
+        """
+        return {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "$id": "https://example.org/sortables",
+            "type": "object",
+            "title": "Sortables",
+            "properties": {},
+        }
+
+    def get_collection_sortables(
+        self, collection_id: str, request: Request | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Get the sortables available for a specific collection.
+
+        This base implementation returns a blank sortables schema.
+        """
+        return {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "$id": f"https://example.org/collections/{collection_id}/sortables",
+            "type": "object",
+            "title": "Sortables",
+            "properties": {},
+        }
+
+    def get_collections_sortables(
+        self, request: Request | None = None, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Get the sortables available for collection search.
+
+        This base implementation returns a blank sortables schema.
+        """
+        return {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "$id": "https://example.org/collections-sortables",
+            "type": "object",
+            "title": "Sortables",
+            "properties": {},
+        }

stac_fastapi_extensions-6.4.0/stac_fastapi/extensions/sort/sort.py

@@ -0,0 +1,289 @@
+"""Sort extension."""
+
+from enum import StrEnum
+from typing import Any
+
+import attr
+from fastapi import APIRouter, FastAPI
+from pydantic import BaseModel, Field
+
+from stac_fastapi.api.models import (
+    CollectionUri,
+    EmptyRequest,
+    JSONSchemaResponse,
+)
+from stac_fastapi.api.routes import create_async_endpoint
+from stac_fastapi.types.extension import ApiExtension
+from stac_fastapi.types.search import APIRequest
+
+from .client import AsyncBaseSortablesClient, BaseSortablesClient
+from .request import SortExtensionGetRequest, SortExtensionPostRequest
+
+
+class SortablesSchema(BaseModel):
+    """Pydantic model for the Sortables JSON Schema response."""
+
+    schema_url: str = Field(
+        default="https://json-schema.org/draft/2020-12/schema", alias="$schema"
+    )
+    id_url: str = Field(alias="$id")
+    type: str = "object"
+    title: str | None = "Sortables"
+    properties: dict[str, Any] = Field(default_factory=dict)
+    additionalProperties: bool = True
+
+    model_config = {
+        "populate_by_name": True,
+        "json_schema_extra": {
+            "example": {
+                "$schema": "https://json-schema.org/draft/2020-12/schema",
+                "$id": "https://example.com/sortables",
+                "title": "Sortables",
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string"},
+                    "datetime": {"type": "string", "format": "date-time"},
+                },
+                "additionalProperties": True,
+            }
+        },
+    }
+
+
+class SortConformanceClasses(StrEnum):
+    """Conformance classes for the Sort v1.1.0 extension.
+
+    See https://github.com/stac-api-extensions/sort
+    """
+
+    ITEM_SEARCH_SORT = "https://api.stacspec.org/v1.1.0/item-search#sort"
+    ITEM_SEARCH_SORTABLES = "https://api.stacspec.org/v1.1.0/item-search#sortables"
+
+    FEATURES_SORT = "https://api.stacspec.org/v1.1.0/ogcapi-features#sort"
+    FEATURES_SORTABLES = (
+        "http://www.opengis.net/spec/ogcapi-features-5/1.0/conf/sortables"
+    )
+
+    COLLECTION_SEARCH_SORT = "https://api.stacspec.org/v1.1.0/collection-search#sort"
+    COLLECTION_SEARCH_SORTABLES = (
+        "https://api.stacspec.org/v1.1.0/collection-search#sortables"
+    )
+
+
+SORTABLES_CONFORMANCE_URIS: frozenset[str] = frozenset(
+    {
+        SortConformanceClasses.ITEM_SEARCH_SORTABLES.value,
+        SortConformanceClasses.FEATURES_SORTABLES.value,
+        SortConformanceClasses.COLLECTION_SEARCH_SORTABLES.value,
+    }
+)
+
+
+@attr.s
+class SortExtension(ApiExtension):
+    """Sort Extension.
+
+    The Sort extension adds the `sortby` parameter to search endpoints and provides
+    sortables endpoints for discovering available sort fields.
+    https://github.com/stac-api-extensions/sort
+    """
+
+    GET: type[APIRequest] = SortExtensionGetRequest
+    POST: type[BaseModel] = SortExtensionPostRequest
+    client: AsyncBaseSortablesClient | BaseSortablesClient | None = attr.ib(default=None)
+    router: APIRouter = attr.ib(
+        factory=lambda: APIRouter(default_response_class=JSONSchemaResponse)
+    )
+
+    conformance_classes: list[str] = attr.ib(
+        factory=lambda: [
+            SortConformanceClasses.ITEM_SEARCH_SORT,
+            SortConformanceClasses.ITEM_SEARCH_SORTABLES,
+            SortConformanceClasses.FEATURES_SORT,
+            SortConformanceClasses.FEATURES_SORTABLES,
+            SortConformanceClasses.COLLECTION_SEARCH_SORT,
+            SortConformanceClasses.COLLECTION_SEARCH_SORTABLES,
+        ]
+    )
+
+    def __attrs_post_init__(self):
+        """Remove sortables conformance classes when no client is provided.
+
+        Without a client the sortables endpoints cannot be served, so the
+        associated conformance URIs are removed from the advertised list.
+        """
+        if self.client is None:
+            self.conformance_classes = [
+                c for c in self.conformance_classes if c not in SORTABLES_CONFORMANCE_URIS
+            ]
+
+    def register(self, app: FastAPI) -> None:
+        """Register the extension with a FastAPI application.
+
+        Args:
+            app: target FastAPI application.
+
+        Returns:
+            None
+        """
+        if self.client is None:
+            return
+
+        self.router.prefix = app.state.router_prefix
+
+        self.router.add_api_route(
+            name="Sortables",
+            path="/sortables",
+            methods=["GET"],
+            response_model=SortablesSchema,
+            response_model_exclude_none=True,
+            endpoint=create_async_endpoint(self.client.get_sortables, EmptyRequest),
+        )
+
+        self.router.add_api_route(
+            name="Collection Sortables",
+            path="/collections/{collection_id}/sortables",
+            methods=["GET"],
+            response_model=SortablesSchema,
+            response_model_exclude_none=True,
+            endpoint=create_async_endpoint(
+                self.client.get_collection_sortables, CollectionUri
+            ),
+        )
+
+        self.router.add_api_route(
+            name="Collections Catalog Sortables",
+            path="/collections-sortables",
+            methods=["GET"],
+            response_model=SortablesSchema,
+            response_model_exclude_none=True,
+            endpoint=create_async_endpoint(
+                self.client.get_collections_sortables, EmptyRequest
+            ),
+        )
+
+        app.include_router(self.router, tags=["Sort Extension"])
+
+
+@attr.s
+class SearchSortExtension(SortExtension):
+    """Item Search Sort Extension.
+
+    Provides sort capabilities for the `/search` endpoint.
+    """
+
+    conformance_classes: list[str] = attr.ib(
+        factory=lambda: [
+            SortConformanceClasses.ITEM_SEARCH_SORT,
+            SortConformanceClasses.ITEM_SEARCH_SORTABLES,
+        ]
+    )
+
+    def register(self, app: FastAPI) -> None:
+        """Register the extension with a FastAPI application.
+
+        Args:
+            app: target FastAPI application.
+
+        Returns:
+            None
+        """
+        if self.client is None:
+            return
+
+        self.router.prefix = app.state.router_prefix
+
+        self.router.add_api_route(
+            name="Sortables",
+            path="/sortables",
+            methods=["GET"],
+            response_model=SortablesSchema,
+            response_model_exclude_none=True,
+            endpoint=create_async_endpoint(self.client.get_sortables, EmptyRequest),
+        )
+
+        app.include_router(self.router, tags=["Sort Extension"])
+
+
+@attr.s
+class ItemCollectionSortExtension(SortExtension):
+    """Item Collection Sort Extension.
+
+    Provides sort capabilities for the `/collections/{id}/items` endpoint.
+    """
+
+    conformance_classes: list[str] = attr.ib(
+        factory=lambda: [
+            SortConformanceClasses.FEATURES_SORT,
+            SortConformanceClasses.FEATURES_SORTABLES,
+        ]
+    )
+
+    def register(self, app: FastAPI) -> None:
+        """Register the extension with a FastAPI application.
+
+        Args:
+            app: target FastAPI application.
+
+        Returns:
+            None
+        """
+        if self.client is None:
+            return
+
+        self.router.prefix = app.state.router_prefix
+
+        self.router.add_api_route(
+            name="Collection Sortables",
+            path="/collections/{collection_id}/sortables",
+            methods=["GET"],
+            response_model=SortablesSchema,
+            response_model_exclude_none=True,
+            endpoint=create_async_endpoint(
+                self.client.get_collection_sortables, CollectionUri
+            ),
+        )
+
+        app.include_router(self.router, tags=["Sort Extension"])
+
+
+@attr.s
+class CollectionSearchSortExtension(SortExtension):
+    """Collection Search Sort Extension.
+
+    Provides sort capabilities for the `/collections` endpoint.
+    """
+
+    conformance_classes: list[str] = attr.ib(
+        factory=lambda: [
+            SortConformanceClasses.COLLECTION_SEARCH_SORT,
+            SortConformanceClasses.COLLECTION_SEARCH_SORTABLES,
+        ]
+    )
+
+    def register(self, app: FastAPI) -> None:
+        """Register the extension with a FastAPI application.
+
+        Args:
+            app: target FastAPI application.
+
+        Returns:
+            None
+        """
+        if self.client is None:
+            return
+
+        self.router.prefix = app.state.router_prefix
+
+        self.router.add_api_route(
+            name="Collections Catalog Sortables",
+            path="/collections-sortables",
+            methods=["GET"],
+            response_model=SortablesSchema,
+            response_model_exclude_none=True,
+            endpoint=create_async_endpoint(
+                self.client.get_collections_sortables, EmptyRequest
+            ),
+        )
+
+        app.include_router(self.router, tags=["Sort Extension"])

{stac_fastapi_extensions-6.3.2 → stac_fastapi_extensions-6.4.0}/stac_fastapi/extensions/version.py

@@ -1,3 +1,3 @@
 """Library version."""
 
-__version__ = "6.3.2"
+__version__ = "6.4.0"

stac_fastapi_extensions-6.3.2/stac_fastapi/extensions/sort/__init__.py

@@ -1,5 +0,0 @@
-"""Sort extension module."""
-
-from .sort import SortConformanceClasses, SortExtension
-
-__all__ = ["SortExtension", "SortConformanceClasses"]

stac_fastapi_extensions-6.3.2/stac_fastapi/extensions/sort/sort.py

@@ -1,55 +0,0 @@
-"""Sort extension."""
-
-from enum import StrEnum
-
-import attr
-from fastapi import FastAPI
-from pydantic import BaseModel
-
-from stac_fastapi.types.extension import ApiExtension
-from stac_fastapi.types.search import APIRequest
-
-from .request import SortExtensionGetRequest, SortExtensionPostRequest
-
-
-class SortConformanceClasses(StrEnum):
-    """Conformance classes for the Sort extension.
-
-    See https://github.com/stac-api-extensions/sort
-
-    """
-
-    SEARCH = "https://api.stacspec.org/v1.0.0/item-search#sort"
-    ITEMS = "https://api.stacspec.org/v1.0.0/ogcapi-features#sort"
-    COLLECTIONS = "https://api.stacspec.org/v1.0.0-rc.1/collection-search#sort"
-
-
-@attr.s
-class SortExtension(ApiExtension):
-    """Sort Extension.
-
-    The Sort extension adds the `sortby` parameter to the `/search` endpoint, allowing the
-    caller to specify the sort order of the returned items.
-    https://github.com/stac-api-extensions/sort
-    """
-
-    GET: type[APIRequest] = SortExtensionGetRequest
-    POST: type[BaseModel] = SortExtensionPostRequest
-
-    conformance_classes: list[str] = attr.ib(
-        factory=lambda: [
-            SortConformanceClasses.SEARCH,
-        ]
-    )
-    schema_href: str | None = attr.ib(default=None)
-
-    def register(self, app: FastAPI) -> None:
-        """Register the extension with a FastAPI application.
-
-        Args:
-            app: target FastAPI application.
-
-        Returns:
-            None
-        """
-        pass