stac-fastapi-pgstac 6.1.0__py3-none-any.whl

stac_fastapi/pgstac/__init__.py

@@ -0,0 +1 @@
+"""stac_fastapi.pgstac module."""

stac_fastapi/pgstac/app.py

@@ -0,0 +1,217 @@
+"""FastAPI application using PGStac.
+
+Enables the extensions specified as a comma-delimited list in
+the ENABLED_EXTENSIONS environment variable (e.g. `transactions,sort,query`).
+If the variable is not set, enables all extensions.
+"""
+
+import os
+from contextlib import asynccontextmanager
+
+from brotli_asgi import BrotliMiddleware
+from fastapi import APIRouter, FastAPI
+from stac_fastapi.api.app import StacApi
+from stac_fastapi.api.middleware import CORSMiddleware, ProxyHeaderMiddleware
+from stac_fastapi.api.models import (
+    EmptyRequest,
+    ItemCollectionUri,
+    JSONResponse,
+    create_get_request_model,
+    create_post_request_model,
+    create_request_model,
+)
+from stac_fastapi.extensions.core import (
+    CollectionSearchExtension,
+    CollectionSearchFilterExtension,
+    FieldsExtension,
+    ItemCollectionFilterExtension,
+    OffsetPaginationExtension,
+    SearchFilterExtension,
+    SortExtension,
+    TokenPaginationExtension,
+    TransactionExtension,
+)
+from stac_fastapi.extensions.core.fields import FieldsConformanceClasses
+from stac_fastapi.extensions.core.free_text import FreeTextConformanceClasses
+from stac_fastapi.extensions.core.query import QueryConformanceClasses
+from stac_fastapi.extensions.core.sort import SortConformanceClasses
+from stac_fastapi.extensions.third_party import BulkTransactionExtension
+from starlette.middleware import Middleware
+
+from stac_fastapi.pgstac.config import Settings
+from stac_fastapi.pgstac.core import CoreCrudClient, health_check
+from stac_fastapi.pgstac.db import close_db_connection, connect_to_db
+from stac_fastapi.pgstac.extensions import FreeTextExtension, QueryExtension
+from stac_fastapi.pgstac.extensions.filter import FiltersClient
+from stac_fastapi.pgstac.transactions import BulkTransactionsClient, TransactionsClient
+from stac_fastapi.pgstac.types.search import PgstacSearch
+
+settings = Settings()
+
+# search extensions
+search_extensions_map = {
+    "query": QueryExtension(),
+    "sort": SortExtension(),
+    "fields": FieldsExtension(),
+    "filter": SearchFilterExtension(client=FiltersClient()),
+    "pagination": TokenPaginationExtension(),
+}
+
+# collection_search extensions
+cs_extensions_map = {
+    "query": QueryExtension(conformance_classes=[QueryConformanceClasses.COLLECTIONS]),
+    "sort": SortExtension(conformance_classes=[SortConformanceClasses.COLLECTIONS]),
+    "fields": FieldsExtension(conformance_classes=[FieldsConformanceClasses.COLLECTIONS]),
+    "filter": CollectionSearchFilterExtension(client=FiltersClient()),
+    "free_text": FreeTextExtension(
+        conformance_classes=[FreeTextConformanceClasses.COLLECTIONS],
+    ),
+    "pagination": OffsetPaginationExtension(),
+}
+
+# item_collection extensions
+itm_col_extensions_map = {
+    "query": QueryExtension(
+        conformance_classes=[QueryConformanceClasses.ITEMS],
+    ),
+    "sort": SortExtension(
+        conformance_classes=[SortConformanceClasses.ITEMS],
+    ),
+    "fields": FieldsExtension(conformance_classes=[FieldsConformanceClasses.ITEMS]),
+    "filter": ItemCollectionFilterExtension(client=FiltersClient()),
+    "pagination": TokenPaginationExtension(),
+}
+
+enabled_extensions = {
+    *search_extensions_map.keys(),
+    *cs_extensions_map.keys(),
+    *itm_col_extensions_map.keys(),
+    "collection_search",
+}
+
+if ext := os.environ.get("ENABLED_EXTENSIONS"):
+    enabled_extensions = set(ext.split(","))
+
+application_extensions = []
+
+with_transactions = os.environ.get("ENABLE_TRANSACTIONS_EXTENSIONS", "").lower() in [
+    "yes",
+    "true",
+    "1",
+]
+if with_transactions:
+    application_extensions.append(
+        TransactionExtension(
+            client=TransactionsClient(),
+            settings=settings,
+            response_class=JSONResponse,
+        ),
+    )
+
+    application_extensions.append(
+        BulkTransactionExtension(client=BulkTransactionsClient()),
+    )
+
+# /search models
+search_extensions = [
+    extension
+    for key, extension in search_extensions_map.items()
+    if key in enabled_extensions
+]
+post_request_model = create_post_request_model(search_extensions, base_model=PgstacSearch)
+get_request_model = create_get_request_model(search_extensions)
+application_extensions.extend(search_extensions)
+
+# /collections/{collectionId}/items model
+items_get_request_model = ItemCollectionUri
+itm_col_extensions = [
+    extension
+    for key, extension in itm_col_extensions_map.items()
+    if key in enabled_extensions
+]
+if itm_col_extensions:
+    items_get_request_model = create_request_model(
+        model_name="ItemCollectionUri",
+        base_model=ItemCollectionUri,
+        extensions=itm_col_extensions,
+        request_type="GET",
+    )
+    application_extensions.extend(itm_col_extensions)
+
+# /collections model
+collections_get_request_model = EmptyRequest
+if "collection_search" in enabled_extensions:
+    cs_extensions = [
+        extension
+        for key, extension in cs_extensions_map.items()
+        if key in enabled_extensions
+    ]
+    collection_search_extension = CollectionSearchExtension.from_extensions(cs_extensions)
+    collections_get_request_model = collection_search_extension.GET
+    application_extensions.append(collection_search_extension)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """FastAPI Lifespan."""
+    await connect_to_db(app, add_write_connection_pool=with_transactions)
+    yield
+    await close_db_connection(app)
+
+
+api = StacApi(
+    app=FastAPI(
+        openapi_url=settings.openapi_url,
+        docs_url=settings.docs_url,
+        redoc_url=None,
+        root_path=settings.root_path,
+        title=settings.stac_fastapi_title,
+        version=settings.stac_fastapi_version,
+        description=settings.stac_fastapi_description,
+        lifespan=lifespan,
+    ),
+    router=APIRouter(prefix=settings.prefix_path),
+    settings=settings,
+    extensions=application_extensions,
+    client=CoreCrudClient(pgstac_search_model=post_request_model),
+    response_class=JSONResponse,
+    items_get_request_model=items_get_request_model,
+    search_get_request_model=get_request_model,
+    search_post_request_model=post_request_model,
+    collections_get_request_model=collections_get_request_model,
+    middlewares=[
+        Middleware(BrotliMiddleware),
+        Middleware(ProxyHeaderMiddleware),
+        Middleware(
+            CORSMiddleware,
+            allow_origins=settings.cors_origins,
+            allow_origin_regex=settings.cors_origin_regex,
+            allow_methods=settings.cors_methods,
+            allow_credentials=settings.cors_credentials,
+            allow_headers=settings.cors_headers,
+        ),
+    ],
+    health_check=health_check,
+)
+app = api.app
+
+
+def run():
+    """Run app from command line using uvicorn if available."""
+    try:
+        import uvicorn
+
+        uvicorn.run(
+            "stac_fastapi.pgstac.app:app",
+            host=settings.app_host,
+            port=settings.app_port,
+            log_level="info",
+            reload=settings.reload,
+            root_path=os.getenv("UVICORN_ROOT_PATH", ""),
+        )
+    except ImportError as e:
+        raise RuntimeError("Uvicorn must be installed in order to use command") from e
+
+
+if __name__ == "__main__":
+    run()

stac_fastapi/pgstac/config.py

@@ -0,0 +1,225 @@
+"""Postgres API configuration."""
+
+import warnings
+from typing import Annotated, Any, List, Optional, Sequence, Type
+from urllib.parse import quote_plus as quote
+
+from pydantic import BaseModel, BeforeValidator, Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from stac_fastapi.types.config import ApiSettings
+from typing_extensions import Self
+
+from stac_fastapi.pgstac.types.base_item_cache import (
+    BaseItemCache,
+    DefaultBaseItemCache,
+)
+
+DEFAULT_INVALID_ID_CHARS = [
+    ":",
+    "/",
+    "?",
+    "#",
+    "[",
+    "]",
+    "@",
+    "!",
+    "$",
+    "&",
+    "'",
+    "(",
+    ")",
+    "*",
+    "+",
+    ",",
+    ";",
+    "=",
+]
+
+
+class ServerSettings(BaseModel):
+    """Server runtime parameters.
+
+    Attributes:
+        search_path: Postgres search path. Defaults to "pgstac,public".
+        application_name: PgSTAC Application name. Defaults to 'pgstac'.
+    """
+
+    search_path: str = "pgstac,public"
+    application_name: str = "pgstac"
+
+    model_config = SettingsConfigDict(extra="allow")
+
+
+class PostgresSettings(BaseSettings):
+    """Postgres-specific API settings.
+
+    Attributes:
+        pguser: postgres username.
+        pgpassword: postgres password.
+        pghost: hostname for the connection.
+        pgport: database port.
+        pgdatabase: database name.
+
+    """
+
+    postgres_user: Annotated[
+        Optional[str],
+        Field(
+            deprecated="`postgres_user` is deprecated, please use `pguser`", default=None
+        ),
+    ]
+    postgres_pass: Annotated[
+        Optional[str],
+        Field(
+            deprecated="`postgres_pass` is deprecated, please use `pgpassword`",
+            default=None,
+        ),
+    ]
+    postgres_host_reader: Annotated[
+        Optional[str],
+        Field(
+            deprecated="`postgres_host_reader` is deprecated, please use `pghost`",
+            default=None,
+        ),
+    ]
+    postgres_host_writer: Annotated[
+        Optional[str],
+        Field(
+            deprecated="`postgres_host_writer` is deprecated, please use `pghost`",
+            default=None,
+        ),
+    ]
+    postgres_port: Annotated[
+        Optional[int],
+        Field(
+            deprecated="`postgres_port` is deprecated, please use `pgport`", default=None
+        ),
+    ]
+    postgres_dbname: Annotated[
+        Optional[str],
+        Field(
+            deprecated="`postgres_dbname` is deprecated, please use `pgdatabase`",
+            default=None,
+        ),
+    ]
+
+    pguser: str
+    pgpassword: str
+    pghost: str
+    pgport: int
+    pgdatabase: str
+
+    db_min_conn_size: int = 1
+    db_max_conn_size: int = 10
+    db_max_queries: int = 50000
+    db_max_inactive_conn_lifetime: float = 300
+
+    server_settings: ServerSettings = ServerSettings()
+
+    model_config = {"env_file": ".env", "extra": "ignore"}
+
+    @model_validator(mode="before")
+    @classmethod
+    def _pg_settings_compat(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            compat = {
+                "postgres_user": "pguser",
+                "postgres_pass": "pgpassword",
+                "postgres_host_reader": "pghost",
+                "postgres_host_writer": "pghost",
+                "postgres_port": "pgport",
+                "postgres_dbname": "pgdatabase",
+            }
+            for old_key, new_key in compat.items():
+                if val := data.get(old_key, None):
+                    warnings.warn(
+                        f"`{old_key}` is deprecated, please use `{new_key}`",
+                        DeprecationWarning,
+                        stacklevel=1,
+                    )
+                    data[new_key] = val
+
+            if (pgh_reader := data.get("postgres_host_reader")) and (
+                pgh_writer := data.get("postgres_host_writer")
+            ):
+                if pgh_reader != pgh_writer:
+                    raise ValueError(
+                        "In order to use different host values for reading and writing "
+                        "you must explicitly provide write_postgres_settings to the connect_to_db function"
+                    )
+
+        return data
+
+    @property
+    def connection_string(self):
+        """Create reader psql connection string."""
+        return f"postgresql://{self.pguser}:{quote(self.pgpassword)}@{self.pghost}:{self.pgport}/{self.pgdatabase}"
+
+
+def str_to_list(value: Any) -> Any:
+    if isinstance(value, str):
+        return [v.strip() for v in value.split(",")]
+    return value
+
+
+class Settings(ApiSettings):
+    """API settings.
+
+    Attributes:
+        prefix_path: An optional path prefix for the underyling FastAPI router.
+        use_api_hydrate: perform hydration of stac items within stac-fastapi.
+        invalid_id_chars: list of characters that are not allowed in item or collection ids.
+
+    """
+
+    prefix_path: str = ""
+    use_api_hydrate: bool = False
+    """
+    When USE_API_HYDRATE=TRUE, PgSTAC database will receive `NO_HYDRATE=TRUE`
+
+    | use_api_hydrate | nohydrate | Hydration |
+    |             --- |       --- |       --- |
+    |           False |     False |    PgSTAC |
+    |            True |      True |       API |
+
+    ref: https://stac-utils.github.io/pgstac/pgstac/#runtime-configurations
+    """
+    exclude_hydrate_markers: bool = True
+    """
+    In some case, PgSTAC can return `DO_NOT_MERGE_MARKER` markers (`𒍟※`).
+    If `EXCLUDE_HYDRATE_MARKERS=TRUE` and `USE_API_HYDRATE=TRUE`, stac-fastapi-pgstac
+    will exclude those values from the responses.
+    """
+
+    invalid_id_chars: List[str] = DEFAULT_INVALID_ID_CHARS
+    base_item_cache: Type[BaseItemCache] = DefaultBaseItemCache
+
+    validate_extensions: bool = False
+    """
+    Validate `stac_extensions` schemas against submitted data when creating or updated STAC objects.
+
+    Implies that the `Transactions` extension is enabled.
+    """
+
+    cors_origins: Annotated[Sequence[str], BeforeValidator(str_to_list)] = ("*",)
+    cors_origin_regex: Optional[str] = None
+    cors_methods: Annotated[Sequence[str], BeforeValidator(str_to_list)] = (
+        "GET",
+        "POST",
+        "OPTIONS",
+    )
+    cors_credentials: bool = False
+    cors_headers: Annotated[Sequence[str], BeforeValidator(str_to_list)] = (
+        "Content-Type",
+    )
+
+    testing: bool = False
+
+    @model_validator(mode="after")
+    def check_origins(self) -> Self:
+        if self.cors_origin_regex and "*" in self.cors_origins:
+            raise ValueError(
+                "Conflicting options found in API settings: `cors_origin_regex` and `*` in `cors_origins`"
+            )
+
+        return self