stac-fastapi.api 5.1.1__tar.gz → 5.2.1__tar.gz

{stac_fastapi_api-5.1.1 → stac_fastapi_api-5.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: stac-fastapi.api
-Version: 5.1.1
+Version: 5.2.1
 Summary: An implementation of STAC API based on the FastAPI framework.
 Home-page: https://github.com/stac-utils/stac-fastapi
 Author: Arturo Engineering
@@ -19,7 +19,7 @@ Classifier: License :: OSI Approved :: MIT License
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: brotli_asgi
-Requires-Dist: stac-fastapi.types~=5.0
+Requires-Dist: stac-fastapi.types~=5.2
 Provides-Extra: dev
 Requires-Dist: httpx; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
@@ -30,9 +30,12 @@ Requires-Dist: requests; extra == "dev"
 Provides-Extra: benchmark
 Requires-Dist: pytest-benchmark; extra == "benchmark"
 Provides-Extra: docs
-Requires-Dist: mkdocs; extra == "docs"
-Requires-Dist: mkdocs-material; extra == "docs"
-Requires-Dist: pdocs; extra == "docs"
+Requires-Dist: black>=23.10.1; extra == "docs"
+Requires-Dist: mkdocs>=1.4.3; extra == "docs"
+Requires-Dist: mkdocs-jupyter>=0.24.5; extra == "docs"
+Requires-Dist: mkdocs-material[imaging]>=9.5; extra == "docs"
+Requires-Dist: griffe-inherited-docstrings>=1.0.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.25.1; extra == "docs"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier

{stac_fastapi_api-5.1.1 → stac_fastapi_api-5.2.1}/setup.py

@@ -7,7 +7,7 @@ with open("README.md") as f:
 
 install_requires = [
     "brotli_asgi",
-    "stac-fastapi.types~=5.0",
+    "stac-fastapi.types~=5.2",
 ]
 
 extra_reqs = {
@@ -22,7 +22,14 @@ extra_reqs = {
     "benchmark": [
         "pytest-benchmark",
     ],
-    "docs": ["mkdocs", "mkdocs-material", "pdocs"],
+    "docs": [
+        "black>=23.10.1",
+        "mkdocs>=1.4.3",
+        "mkdocs-jupyter>=0.24.5",
+        "mkdocs-material[imaging]>=9.5",
+        "griffe-inherited-docstrings>=1.0.0",
+        "mkdocstrings[python]>=0.25.1",
+    ],
 }
 
 

{stac_fastapi_api-5.1.1 → stac_fastapi_api-5.2.1}/stac_fastapi/api/app.py

@@ -1,7 +1,7 @@
 """Fastapi app creation."""
 
 
-from typing import Dict, List, Optional, Tuple, Type, Union
+from typing import Awaitable, Callable, Dict, List, Optional, Tuple, Type, Union
 
 import attr
 from brotli_asgi import BrotliMiddleware
@@ -12,7 +12,7 @@ from stac_pydantic.api.collections import Collections
 from stac_pydantic.shared import MimeTypes
 from stac_pydantic.version import STAC_VERSION
 from starlette.middleware import Middleware
-from starlette.responses import JSONResponse, Response
+from starlette.responses import Response
 
 from stac_fastapi.api.errors import DEFAULT_STATUS_CODES, add_exception_handlers
 from stac_fastapi.api.middleware import CORSMiddleware, ProxyHeaderMiddleware
@@ -21,11 +21,18 @@ from stac_fastapi.api.models import (
     CollectionUri,
     EmptyRequest,
     GeoJSONResponse,
+    HealthCheck,
     ItemCollectionUri,
     ItemUri,
+    JSONResponse,
 )
 from stac_fastapi.api.openapi import update_openapi
-from stac_fastapi.api.routes import Scope, add_route_dependencies, create_async_endpoint
+from stac_fastapi.api.routes import (
+    Scope,
+    add_direct_response,
+    add_route_dependencies,
+    create_async_endpoint,
+)
 from stac_fastapi.types.config import ApiSettings, Settings
 from stac_fastapi.types.core import AsyncBaseCoreClient, BaseCoreClient
 from stac_fastapi.types.extension import ApiExtension
@@ -62,6 +69,10 @@ class StacApi:
             specified routes. This is useful
             for applying custom auth requirements to routes defined elsewhere in
             the application.
+        health_check:
+            A Callable which return application's `health` information.
+            Defaults to `def health: return {"status": "UP"}`
+
     """
 
     settings: ApiSettings = attr.ib()
@@ -123,6 +134,9 @@ class StacApi:
         )
     )
     route_dependencies: List[Tuple[List[Scope], List[Depends]]] = attr.ib(default=[])
+    health_check: Union[Callable[[], Dict], Callable[[], Awaitable[Dict]]] = attr.ib(
+        default=lambda: {"status": "UP"}
+    )
 
     def get_extension(self, extension: Type[ApiExtension]) -> Optional[ApiExtension]:
         """Get an extension.
@@ -138,12 +152,8 @@ class StacApi:
                 return ext
         return None
 
-    def register_landing_page(self):
-        """Register landing page (GET /).
-
-        Returns:
-            None
-        """
+    def register_landing_page(self) -> None:
+        """Register landing page (GET /)."""
         self.router.add_api_route(
             name="Landing Page",
             path="/",
@@ -165,12 +175,8 @@ class StacApi:
             endpoint=create_async_endpoint(self.client.landing_page, EmptyRequest),
         )
 
-    def register_conformance_classes(self):
-        """Register conformance classes (GET /conformance).
-
-        Returns:
-            None
-        """
+    def register_conformance_classes(self) -> None:
+        """Register conformance classes (GET /conformance)."""
         self.router.add_api_route(
             name="Conformance Classes",
             path="/conformance",
@@ -192,12 +198,8 @@ class StacApi:
             endpoint=create_async_endpoint(self.client.conformance, EmptyRequest),
         )
 
-    def register_get_item(self):
-        """Register get item endpoint (GET /collections/{collection_id}/items/{item_id}).
-
-        Returns:
-            None
-        """
+    def register_get_item(self) -> None:
+        """Register get item endpoint (GET /collections/{collection_id}/items/{item_id})."""  # noqa: E501
         self.router.add_api_route(
             name="Get Item",
             path="/collections/{collection_id}/items/{item_id}",
@@ -219,12 +221,8 @@ class StacApi:
             ),
         )
 
-    def register_post_search(self):
-        """Register search endpoint (POST /search).
-
-        Returns:
-            None
-        """
+    def register_post_search(self) -> None:
+        """Register search endpoint (POST /search)."""
         self.router.add_api_route(
             name="Search",
             path="/search",
@@ -248,12 +246,8 @@ class StacApi:
             ),
         )
 
-    def register_get_search(self):
-        """Register search endpoint (GET /search).
-
-        Returns:
-            None
-        """
+    def register_get_search(self) -> None:
+        """Register search endpoint (GET /search)."""
         self.router.add_api_route(
             name="Search",
             path="/search",
@@ -277,12 +271,8 @@ class StacApi:
             ),
         )
 
-    def register_get_collections(self):
-        """Register get collections endpoint (GET /collections).
-
-        Returns:
-            None
-        """
+    def register_get_collections(self) -> None:
+        """Register get collections endpoint (GET /collections)."""
         self.router.add_api_route(
             name="Get Collections",
             path="/collections",
@@ -306,12 +296,8 @@ class StacApi:
             ),
         )
 
-    def register_get_collection(self):
-        """Register get collection endpoint (GET /collection/{collection_id}).
-
-        Returns:
-            None
-        """
+    def register_get_collection(self) -> None:
+        """Register get collection endpoint (GET /collection/{collection_id})."""
         self.router.add_api_route(
             name="Get Collection",
             path="/collections/{collection_id}",
@@ -335,12 +321,8 @@ class StacApi:
             ),
         )
 
-    def register_get_item_collection(self):
-        """Register get item collection endpoint (GET /collection/{collection_id}/items).
-
-        Returns:
-            None
-        """
+    def register_get_item_collection(self) -> None:
+        """Register get item collection endpoint (GET /collection/{collection_id}/items)."""  # noqa: E501
         self.router.add_api_route(
             name="Get ItemCollection",
             path="/collections/{collection_id}/items",
@@ -364,7 +346,7 @@ class StacApi:
             ),
         )
 
-    def register_core(self):
+    def register_core(self) -> None:
         """Register core STAC endpoints.
 
             GET /
@@ -378,8 +360,6 @@ class StacApi:
 
         Injects application logic (StacApi.client) into the API layer.
 
-        Returns:
-            None
         """
         self.register_landing_page()
         self.register_conformance_classes()
@@ -390,41 +370,71 @@ class StacApi:
         self.register_get_collection()
         self.register_get_item_collection()
 
-    def add_health_check(self):
+    def add_health_check(self) -> None:
         """Add a health check."""
+
         mgmt_router = APIRouter(prefix=self.app.state.router_prefix)
 
-        @mgmt_router.get("/_mgmt/ping")
         async def ping():
-            """Liveliness/readiness probe."""
+            """Liveliness probe."""
             return {"message": "PONG"}
 
+        mgmt_router.add_api_route(
+            name="Ping",
+            path="/_mgmt/ping",
+            response_model=Dict,
+            responses={
+                200: {
+                    "content": {
+                        MimeTypes.json.value: {},
+                    },
+                },
+            },
+            response_class=self.response_class,
+            methods=["GET"],
+            endpoint=ping,
+        )
+
+        mgmt_router.add_api_route(
+            name="Health",
+            path="/_mgmt/health",
+            response_model=(
+                HealthCheck if self.settings.enable_response_models else None
+            ),
+            responses={
+                200: {
+                    "content": {
+                        MimeTypes.json.value: {},
+                    },
+                    "model": HealthCheck,
+                },
+            },
+            response_class=self.response_class,
+            methods=["GET"],
+            endpoint=self.health_check,
+        )
         self.app.include_router(mgmt_router, tags=["Liveliness/Readiness"])
 
     def add_route_dependencies(
-        self, scopes: List[Scope], dependencies=List[Depends]
+        self, scopes: List[Scope], dependencies: List[Depends]
     ) -> None:
         """Add custom dependencies to routes.
 
         Args:
-            scopes: list of scopes. Each scope should be a dict with a `path`
-                and `method` property.
-            dependencies: list of [FastAPI
-                dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/)
+            scopes: list of Scope.
+                Each scope should be a dict with a `path` and `method` property.
+            dependencies: list of fastapi.Depends
+                [FastAPI dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/)
                 to apply to each scope.
 
-        Returns:
-            None
         """
         return add_route_dependencies(self.app.router.routes, scopes, dependencies)
 
-    def __attrs_post_init__(self):
+    def __attrs_post_init__(self) -> None:
         """Post-init hook.
 
         Responsible for setting up the application upon instantiation of the class.
 
-        Returns:
-            None
         """
         # inject settings
         self.client.extensions = self.extensions
@@ -463,3 +473,6 @@ class StacApi:
         # customize route dependencies
         for scopes, dependencies in self.route_dependencies:
             self.add_route_dependencies(scopes=scopes, dependencies=dependencies)
+
+        if self.app.state.settings.enable_direct_response:
+            add_direct_response(self.app)

{stac_fastapi_api-5.1.1 → stac_fastapi_api-5.2.1}/stac_fastapi/api/errors.py

@@ -8,8 +8,8 @@ from fastapi.encoders import jsonable_encoder
 from fastapi.exceptions import RequestValidationError, ResponseValidationError
 from starlette import status
 from starlette.requests import Request
-from starlette.responses import JSONResponse
 
+from stac_fastapi.api.models import JSONResponse
 from stac_fastapi.types.errors import (
     ConflictError,
     DatabaseError,

{stac_fastapi_api-5.1.1 → stac_fastapi_api-5.2.1}/stac_fastapi/api/middleware.py

@@ -82,7 +82,7 @@ class ProxyHeaderMiddleware:
 
         await self.app(scope, receive, send)
 
-    def _get_forwarded_url_parts(self, scope: Scope) -> Tuple[str]:
+    def _get_forwarded_url_parts(self, scope: Scope) -> Tuple[str, str, str]:
         proto = scope.get("scheme", "http")
         header_host = self._get_header_value_by_name(scope, "host")
         if header_host is None:
@@ -127,7 +127,7 @@ class ProxyHeaderMiddleware:
     @staticmethod
     def _replace_header_value_by_name(
         scope: Scope, header_name: str, new_value: str
-    ) -> List[Tuple[str]]:
+    ) -> List[Tuple[str, str]]:
         return [
             (name, value)
             for name, value in scope["headers"]

{stac_fastapi_api-5.1.1 → stac_fastapi_api-5.2.1}/stac_fastapi/api/models.py

@@ -1,6 +1,6 @@
 """Api request/response models."""
 
-from typing import List, Optional, Type, Union
+from typing import List, Literal, Optional, Type, Union
 
 import attr
 from fastapi import Path, Query
@@ -135,3 +135,9 @@ class JSONSchemaResponse(JSONResponse):
     """JSON with custom, vendor content-type."""
 
     media_type = "application/schema+json"
+
+
+class HealthCheck(BaseModel, extra="allow"):
+    """health check response model."""
+
+    status: Literal["UP", "DOWN"]

{stac_fastapi_api-5.1.1 → stac_fastapi_api-5.2.1}/stac_fastapi/api/openapi.py

@@ -2,7 +2,7 @@
 
 from fastapi import FastAPI
 from starlette.requests import Request
-from starlette.responses import JSONResponse, Response
+from starlette.responses import Response
 from starlette.routing import Route, request_response
 
 
@@ -22,7 +22,7 @@ def update_openapi(app: FastAPI) -> FastAPI:
     # Create a patched endpoint function that modifies the content type of the response
     async def patched_openapi_endpoint(req: Request) -> Response:
         # Get the response from the old endpoint function
-        response: JSONResponse = await old_endpoint(req)
+        response = await old_endpoint(req)
         # Update the content type header in place
         response.headers["content-type"] = "application/vnd.oai.openapi+json;version=3.0"
         # Return the updated response

{stac_fastapi_api-5.1.1 → stac_fastapi_api-5.2.1}/stac_fastapi/api/routes.py

@@ -5,13 +5,15 @@ import functools
 import inspect
 from typing import Any, Callable, Dict, List, Optional, Type, TypedDict, Union
 
-from fastapi import Depends, params
-from fastapi.dependencies.utils import get_parameterless_sub_dependant
+from fastapi import Depends, FastAPI, params
+from fastapi.datastructures import DefaultPlaceholder
+from fastapi.dependencies.utils import get_dependant, get_parameterless_sub_dependant
+from fastapi.routing import APIRoute
 from pydantic import BaseModel
 from starlette.concurrency import run_in_threadpool
 from starlette.requests import Request
 from starlette.responses import Response
-from starlette.routing import BaseRoute, Match
+from starlette.routing import BaseRoute, Match, request_response
 from starlette.status import HTTP_204_NO_CONTENT
 
 from stac_fastapi.api.models import APIRequest
@@ -86,7 +88,7 @@ class Scope(TypedDict, total=False):
 
 
 def add_route_dependencies(
-    routes: List[BaseRoute], scopes: List[Scope], dependencies=List[params.Depends]
+    routes: List[BaseRoute], scopes: List[Scope], dependencies: List[params.Depends]
 ) -> None:
     """Add dependencies to routes.
 
@@ -131,3 +133,33 @@ def add_route_dependencies(
             # https://github.com/tiangolo/fastapi/blob/58ab733f19846b4875c5b79bfb1f4d1cb7f4823f/fastapi/applications.py#L337-L360
             # https://github.com/tiangolo/fastapi/blob/58ab733f19846b4875c5b79bfb1f4d1cb7f4823f/fastapi/routing.py#L677-L678
             route.dependencies.extend(dependencies)
+
+
+def add_direct_response(app: FastAPI) -> None:
+    """
+    Setup FastAPI application's endpoints to return Response Object directly, avoiding
+    Pydantic validation and FastAPI (slow) serialization.
+
+    ref: https://gist.github.com/Zaczero/00f3a2679ebc0a25eb938ed82bc63553
+    """
+
+    def wrap_endpoint(endpoint: Callable, cls: Type[Response]):
+        @functools.wraps(endpoint)
+        async def wrapper(*args, **kwargs):
+            content = await endpoint(*args, **kwargs)
+            return content if isinstance(content, Response) else cls(content)
+
+        return wrapper
+
+    for route in app.routes:
+        if not isinstance(route, APIRoute):
+            continue
+
+        response_class = route.response_class
+        if isinstance(response_class, DefaultPlaceholder):
+            response_class = response_class.value
+
+        if issubclass(response_class, Response):
+            route.endpoint = wrap_endpoint(route.endpoint, response_class)
+            route.dependant = get_dependant(path=route.path_format, call=route.endpoint)
+            route.app = request_response(route.get_route_handler())

{stac_fastapi_api-5.1.1 → stac_fastapi_api-5.2.1}/stac_fastapi/api/version.py

@@ -1,3 +1,3 @@
 """Library version."""
 
-__version__ = "5.1.1"
+__version__ = "5.2.1"

{stac_fastapi_api-5.1.1 → stac_fastapi_api-5.2.1}/stac_fastapi.api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: stac-fastapi.api
-Version: 5.1.1
+Version: 5.2.1
 Summary: An implementation of STAC API based on the FastAPI framework.
 Home-page: https://github.com/stac-utils/stac-fastapi
 Author: Arturo Engineering
@@ -19,7 +19,7 @@ Classifier: License :: OSI Approved :: MIT License
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: brotli_asgi
-Requires-Dist: stac-fastapi.types~=5.0
+Requires-Dist: stac-fastapi.types~=5.2
 Provides-Extra: dev
 Requires-Dist: httpx; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
@@ -30,9 +30,12 @@ Requires-Dist: requests; extra == "dev"
 Provides-Extra: benchmark
 Requires-Dist: pytest-benchmark; extra == "benchmark"
 Provides-Extra: docs
-Requires-Dist: mkdocs; extra == "docs"
-Requires-Dist: mkdocs-material; extra == "docs"
-Requires-Dist: pdocs; extra == "docs"
+Requires-Dist: black>=23.10.1; extra == "docs"
+Requires-Dist: mkdocs>=1.4.3; extra == "docs"
+Requires-Dist: mkdocs-jupyter>=0.24.5; extra == "docs"
+Requires-Dist: mkdocs-material[imaging]>=9.5; extra == "docs"
+Requires-Dist: griffe-inherited-docstrings>=1.0.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.25.1; extra == "docs"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier

stac_fastapi_api-5.2.1/stac_fastapi.api.egg-info/requires.txt

@@ -0,0 +1,21 @@
+brotli_asgi
+stac-fastapi.types~=5.2
+
+[benchmark]
+pytest-benchmark
+
+[dev]
+httpx
+pytest
+pytest-cov
+pytest-asyncio
+pre-commit
+requests
+
+[docs]
+black>=23.10.1
+mkdocs>=1.4.3
+mkdocs-jupyter>=0.24.5
+mkdocs-material[imaging]>=9.5
+griffe-inherited-docstrings>=1.0.0
+mkdocstrings[python]>=0.25.1

{stac_fastapi_api-5.1.1 → stac_fastapi_api-5.2.1}/tests/test_app.py

@@ -6,6 +6,7 @@ from fastapi import Path, Query
 from fastapi.testclient import TestClient
 from pydantic import ValidationError
 from stac_pydantic import api
+from starlette.requests import Request
 from typing_extensions import Annotated
 
 from stac_fastapi.api import app
@@ -108,6 +109,31 @@ def test_client_invalid_response_type(validate, TestCoreClient, item_dict):
         assert item.status_code == 200, item.text
 
 
+def test_client_response_by_pass(TestCoreClient, item_dict):
+    """Check with `enable_direct_response` option."""
+
+    class InValidResponseClient(TestCoreClient):
+        def get_item(self, item_id: str, collection_id: str, **kwargs) -> stac.Item:
+            item_dict.pop("bbox", None)
+            item_dict.pop("geometry", None)
+            return item_dict
+
+    test_app = app.StacApi(
+        settings=ApiSettings(
+            enable_response_models=False,
+            enable_direct_response=True,
+        ),
+        client=InValidResponseClient(),
+    )
+
+    with TestClient(test_app.app) as client:
+        item = client.get("/collections/test/items/test")
+
+    assert item.json()
+    assert item.status_code == 200
+    assert item.headers["content-type"] == "application/geo+json"
+
+
 def test_client_openapi(TestCoreClient):
     """Test if response models are all documented with OpenAPI."""
 
@@ -504,3 +530,51 @@ def test_client_datetime_input_params():
     assert post_search.json() == "2020-01-01T00:00:00.00001Z"
     assert post_search_zero.status_code == 200, post_search_zero.text
     assert post_search_zero.json() == "2020-01-01T00:00:00.0000Z"
+
+
+def test_mgmt_endpoints(AsyncTestCoreClient):
+    """Test ping/health endpoints."""
+
+    test_app = app.StacApi(
+        settings=ApiSettings(),
+        client=AsyncTestCoreClient(),
+    )
+
+    with TestClient(test_app.app) as client:
+        resp = client.get("/_mgmt/ping")
+        assert resp.status_code == 200
+        assert resp.json() == {"message": "PONG"}
+
+        resp = client.get("/_mgmt/health")
+        assert resp.status_code == 200
+        assert resp.json() == {"status": "UP"}
+
+    def health_check(request: Request):
+        return {
+            "status": "UP",
+            "database": {
+                "status": "UP",
+                "version": "0.1.0",
+            },
+        }
+
+    test_app = app.StacApi(
+        settings=ApiSettings(),
+        client=AsyncTestCoreClient(),
+        health_check=health_check,
+    )
+
+    with TestClient(test_app.app) as client:
+        resp = client.get("/_mgmt/ping")
+        assert resp.status_code == 200
+        assert resp.json() == {"message": "PONG"}
+
+        resp = client.get("/_mgmt/health")
+        assert resp.status_code == 200
+        assert resp.json() == {
+            "status": "UP",
+            "database": {
+                "status": "UP",
+                "version": "0.1.0",
+            },
+        }

{stac_fastapi_api-5.1.1 → stac_fastapi_api-5.2.1}/tests/test_app_prefix.py

@@ -34,6 +34,9 @@ def test_api_prefix(TestCoreClient, prefix):
     )
 
     with TestClient(api.app, base_url="http://stac.io") as client:
+        ping = client.get(f"{prefix}/_mgmt/ping")
+        assert ping.status_code == 200, ping.json() == {"message": "PONG"}
+
         landing = client.get(f"{prefix}/")
         assert landing.status_code == 200, landing.json()
 

{stac_fastapi_api-5.1.1 → stac_fastapi_api-5.2.1}/tests/test_models.py

@@ -43,7 +43,10 @@ def test_create_get_request_model():
     model = request_model(bbox="0,0,0,1,1,1")
     assert model.bbox == (0.0, 0.0, 0.0, 1.0, 1.0, 1.0)
 
-    with pytest.raises(AssertionError):
+    with pytest.raises(HTTPException):
+        request_model(bbox="a,b")
+
+    with pytest.raises(HTTPException):
         request_model(bbox="0,0,0,1,1")
 
     model = request_model(

stac_fastapi_api-5.1.1/stac_fastapi.api.egg-info/requires.txt

@@ -1,18 +0,0 @@
-brotli_asgi
-stac-fastapi.types~=5.0
-
-[benchmark]
-pytest-benchmark
-
-[dev]
-httpx
-pytest
-pytest-cov
-pytest-asyncio
-pre-commit
-requests
-
-[docs]
-mkdocs
-mkdocs-material
-pdocs