stac-fastapi.core 7.2.0__tar.gz → 8.0.0__tar.gz

{stac_fastapi_core-7.2.0 → stac_fastapi_core-8.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stac_fastapi_core
-Version: 7.2.0
+Version: 8.0.0
 Summary: Core library for the Elasticsearch and Opensearch stac-fastapi backends.
 Project-URL: Homepage, https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch
 License: MIT
@@ -15,29 +15,29 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
 Requires-Dist: attrs>=23.2.0
-Requires-Dist: fastapi<0.142,>=0.109
+Requires-Dist: cql2<0.7.0,>=0.6.0
+Requires-Dist: fastapi<0.144,>=0.109
 Requires-Dist: jsonschema~=4.26.0
-Requires-Dist: orjson<3.13,>=3.11
+Requires-Dist: orjson<3.14,>=3.11
 Requires-Dist: overrides<7.8,>=7.4
 Requires-Dist: pydantic<3.0.0,>=2.4.1
-Requires-Dist: pygeofilter<0.5.0,>=0.3.1
 Requires-Dist: slowapi~=0.1.9
 Requires-Dist: stac-fastapi-api==7.0.0
 Requires-Dist: stac-fastapi-extensions==7.0.0
 Requires-Dist: stac-fastapi-types==7.0.0
-Requires-Dist: stac-pydantic<3.7,>=3.3
-Requires-Dist: starlette<1.7.0,>=0.35.0
-Requires-Dist: uvicorn<0.53,>=0.23
+Requires-Dist: stac-pydantic<3.8,>=3.7
+Requires-Dist: starlette<1.9.0,>=0.35.0
+Requires-Dist: uvicorn<0.55,>=0.23
 Provides-Extra: catalogs
 Requires-Dist: stac-fastapi-catalogs-extension==1.0.0; extra == 'catalogs'
 Provides-Extra: redis
 Requires-Dist: redis<8.2,>=6.4; extra == 'redis'
 Requires-Dist: retry~=0.9.2; extra == 'redis'
 Provides-Extra: sentry
-Requires-Dist: sentry-sdk<2.70,>=2.49; extra == 'sentry'
+Requires-Dist: sentry-sdk<2.73,>=2.49; extra == 'sentry'
 Provides-Extra: validator
 Requires-Dist: jsonpatch; extra == 'validator'
-Requires-Dist: stac-valid<4.6.0,>=4.2.2; extra == 'validator'
+Requires-Dist: stac-valid<4.7,>=4.6.1; extra == 'validator'
 Description-Content-Type: text/markdown
 
 # stac-fastapi-core

{stac_fastapi_core-7.2.0 → stac_fastapi_core-8.0.0}/pyproject.toml

@@ -29,20 +29,20 @@ keywords = [
 ]
 dynamic = ["version"]
 dependencies = [
-    "fastapi>=0.109,<0.142",
+    "fastapi>=0.109,<0.144",
     "attrs>=23.2.0",
     "pydantic>=2.4.1,<3.0.0",
-    "stac_pydantic>=3.3,<3.7",
+    "stac_pydantic>=3.7,<3.8",
     "stac-fastapi.types==7.0.0",
     "stac-fastapi.api==7.0.0",
     "stac-fastapi.extensions==7.0.0",
-    "orjson>=3.11,<3.13",
+    "orjson>=3.11,<3.14",
     "overrides>=7.4,<7.8",
-    "pygeofilter>=0.3.1,<0.5.0",
+    "cql2>=0.6.0,<0.7.0",
     "jsonschema~=4.26.0",
     "slowapi~=0.1.9",
-    "uvicorn>=0.23,<0.53",
-    "starlette>=0.35.0,<1.7.0",
+    "starlette>=0.35.0,<1.9.0",
+    "uvicorn>=0.23,<0.55",
 ]
 
 [project.optional-dependencies]
@@ -51,13 +51,13 @@ redis = [
     "retry~=0.9.2",
 ]
 sentry = [
-    "sentry-sdk>=2.49,<2.70",
+    "sentry-sdk>=2.49,<2.73",
 ]
 catalogs = [
     "stac-fastapi-catalogs-extension==1.0.0",
 ]
 validator = [
-    "stac-valid>=4.2.2,<4.6.0",
+    "stac-valid>=4.6.1,<4.7",
     "jsonpatch"
 ]
 

{stac_fastapi_core-7.2.0 → stac_fastapi_core-8.0.0}/stac_fastapi/core/base_database_logic.py

@@ -5,6 +5,17 @@ from typing import Any, Iterable
 
 from stac_pydantic.shared import BBox
 
+from stac_fastapi.core.etag import DocumentVersion
+from stac_fastapi.sfeos_helpers.database import (
+    find_item_in_alias,
+    index_alias_by_collection_id,
+    mk_item_id,
+)
+from stac_fastapi.sfeos_helpers.search_engine import (
+    BaseIndexInserter,
+    DatetimeIndexInserter,
+)
+from stac_fastapi.types.errors import NotFoundError
 from stac_fastapi.types.stac import Collection, Item
 
 
@@ -16,6 +27,12 @@ class BaseDatabaseLogic(abc.ABC):
     Subclasses must provide implementations for these methods.
     """
 
+    client: Any
+    async_index_inserter: BaseIndexInserter
+    #: Search-engine exception raised when a document lookup misses. Concrete
+    #: backends set this to their engine-specific not-found error class.
+    not_found_error_class: type[Exception]
+
     @abc.abstractmethod
     async def get_all_collections(
         self,
@@ -48,13 +65,85 @@ class BaseDatabaseLogic(abc.ABC):
         pass
 
     @abc.abstractmethod
-    async def get_one_item(self, collection_id: str, item_id: str) -> dict:
+    async def get_one_item(
+        self, collection_id: str, item_id: str, *, include_hidden: bool = False
+    ) -> dict:
         """Retrieve a single item from the database."""
         pass
 
+    async def get_item_for_write(self, collection_id: str, item_id: str) -> dict:
+        """Retrieve an item for a write without applying read visibility filters.
+
+        Under datetime index filtering the real-time ``mget`` lookup is used
+        for the same reason as in :meth:`get_item_hit_for_write`.
+        """
+        if isinstance(self.async_index_inserter, DatetimeIndexInserter):
+            hit = await self.get_item_hit_for_write(collection_id, item_id)
+            return hit["_source"]
+        return await self.get_one_item(collection_id, item_id, include_hidden=True)
+
+    async def get_item_hit_for_write(self, collection_id: str, item_id: str) -> dict:
+        """Retrieve the write-lookup hit for an item, including its version.
+
+        Returns a hit dict carrying ``_source``, ``_index``, ``_seq_no`` and
+        ``_primary_term``, so callers that then write via ``create_item`` can
+        pass the result back as ``existing_hit`` (the existence check is not
+        repeated) or read the stored version from it.
+
+        Under datetime index filtering, ``_id`` uniqueness is enforced per
+        physical index and a just-written document may not be visible to
+        ``_search`` yet, so the lookup is a real-time ``mget`` over the
+        collection alias's concrete indexes instead.
+
+        Raises:
+            NotFoundError: If the item does not exist in the collection.
+        """
+        if isinstance(self.async_index_inserter, DatetimeIndexInserter):
+            try:
+                hit = await find_item_in_alias(
+                    self.client,
+                    index_alias_by_collection_id(collection_id),
+                    mk_item_id(item_id, collection_id),
+                )
+            except self.not_found_error_class:
+                hit = None
+            if hit is None:
+                raise NotFoundError(
+                    f"Item {item_id} does not exist inside Collection {collection_id}"
+                )
+            return hit
+        item, version = await self.get_one_item_with_version(
+            collection_id, item_id, include_hidden=True
+        )
+        return {
+            "_source": item,
+            "_index": version.index,
+            "_seq_no": version.seq_no,
+            "_primary_term": version.primary_term,
+        }
+
+    @abc.abstractmethod
+    async def get_one_item_with_version(
+        self, collection_id: str, item_id: str, *, include_hidden: bool = False
+    ) -> tuple[dict, DocumentVersion]:
+        """Retrieve a single item and the version of its stored document.
+
+        With `include_hidden`, HIDE_ITEM_PATH does not apply, as for a write.
+        """
+        pass
+
     @abc.abstractmethod
-    async def create_item(self, item: dict, refresh: bool = False) -> None:
-        """Create an item in the database."""
+    async def create_item(
+        self,
+        item: dict,
+        refresh: bool = False,
+        version: DocumentVersion | None = None,
+        **kwargs: Any,
+    ) -> DocumentVersion | None:
+        """Create an item in the database; return the version it stored.
+
+        With `version` (If-Match), only that stored version is replaced; 412 otherwise.
+        """
         pass
 
     @abc.abstractmethod
@@ -72,6 +161,7 @@ class BaseDatabaseLogic(abc.ABC):
         item: dict,
         base_url: str,
         refresh: bool = True,
+        version: DocumentVersion | None = None,
     ) -> dict:
         """Patch a item in the database follows RF7396."""
         pass
@@ -85,13 +175,18 @@ class BaseDatabaseLogic(abc.ABC):
         base_url: str,
         create_nest: bool = False,
         refresh: bool = True,
+        version: DocumentVersion | None = None,
     ) -> dict:
         """Patch a item in the database follows RF6902."""
         pass
 
     @abc.abstractmethod
     async def delete_item(
-        self, item_id: str, collection_id: str, refresh: bool = False
+        self,
+        item_id: str,
+        collection_id: str,
+        refresh: bool = False,
+        version: DocumentVersion | None = None,
     ) -> None:
         """Delete an item from the database."""
         pass
@@ -109,8 +204,10 @@ class BaseDatabaseLogic(abc.ABC):
         pass
 
     @abc.abstractmethod
-    async def create_collection(self, collection: dict, refresh: bool = False) -> None:
-        """Create a collection in the database."""
+    async def create_collection(
+        self, collection: dict, refresh: bool = False
+    ) -> DocumentVersion | None:
+        """Create a collection in the database; return the version it stored."""
         pass
 
     @abc.abstractmethod
@@ -120,6 +217,7 @@ class BaseDatabaseLogic(abc.ABC):
         collection: dict,
         base_url: str,
         refresh: bool = True,
+        version: DocumentVersion | None = None,
     ) -> dict:
         """Patch a collection in the database follows RF7396."""
         pass
@@ -132,6 +230,7 @@ class BaseDatabaseLogic(abc.ABC):
         base_url: str,
         create_nest: bool = False,
         refresh: bool = True,
+        version: DocumentVersion | None = None,
     ) -> dict:
         """Patch a collection in the database follows RF6902."""
         pass
@@ -141,16 +240,47 @@ class BaseDatabaseLogic(abc.ABC):
         """Find a collection in the database."""
         pass
 
+    @abc.abstractmethod
+    async def find_collection_with_version(
+        self, collection_id: str
+    ) -> tuple[dict, DocumentVersion]:
+        """Find a collection and the version of its stored document."""
+        pass
+
     @abc.abstractmethod
     async def update_collection(
-        self, collection_id: str, collection: Collection, **kwargs: Any
-    ) -> None:
+        self,
+        collection_id: str,
+        collection: Collection,
+        preserve_parent_ids: bool = False,
+        version: DocumentVersion | None = None,
+        **kwargs: Any,
+    ) -> DocumentVersion | None:
         """Update a collection in the database."""
         pass
 
+    @abc.abstractmethod
+    async def update_parent_ids(
+        self,
+        doc_id: str,
+        doc_type: str,
+        parent_id: str,
+        add: bool,
+        refresh: bool | str = False,
+    ) -> dict:
+        """Atomically add or remove one parent id in a Collection's or Catalog's parent_ids.
+
+        Returns:
+            The stored document after the update.
+        """
+        pass
+
     @abc.abstractmethod
     async def delete_collection(
-        self, collection_id: str, refresh: bool = False
+        self,
+        collection_id: str,
+        refresh: bool = False,
+        version: DocumentVersion | None = None,
     ) -> None:
         """Delete a collection from the database."""
         pass
@@ -175,6 +305,7 @@ class BaseDatabaseLogic(abc.ABC):
         limit: int,
         request: Any = None,
         sort: list[dict[str, Any]] | None = None,
+        filter: dict[str, Any] | None = None,
     ) -> tuple[list[dict[str, Any]], str | None, int | None]:
         """Retrieve a list of catalogs from the database, supporting pagination.
 
@@ -183,6 +314,7 @@ class BaseDatabaseLogic(abc.ABC):
             limit (int): The number of results to return.
             request (Any, optional): The FastAPI request object. Defaults to None.
             sort (Optional[List[Dict[str, Any]]], optional): Optional sort parameter. Defaults to None.
+            filter (Optional[Dict[str, Any]], optional): A CQL2 JSON filter the catalogs must match. Defaults to None.
 
         Returns:
             A tuple of (catalogs, next pagination token if any, optional count).
@@ -190,8 +322,13 @@ class BaseDatabaseLogic(abc.ABC):
         pass
 
     @abc.abstractmethod
-    async def create_catalog(self, catalog: dict, refresh: bool = False) -> None:
-        """Create a catalog in the database."""
+    async def create_catalog(
+        self, catalog: dict, refresh: bool = False
+    ) -> DocumentVersion | None:
+        """Create a catalog; reject an id already used by any document.
+
+        Returns the version of the stored document.
+        """
         pass
 
     @abc.abstractmethod
@@ -200,12 +337,34 @@ class BaseDatabaseLogic(abc.ABC):
         pass
 
     @abc.abstractmethod
-    async def delete_catalog(self, catalog_id: str, refresh: bool = False) -> None:
+    async def find_catalog_with_version(
+        self, catalog_id: str
+    ) -> tuple[dict, DocumentVersion]:
+        """Find a catalog and the version of its stored document."""
+        pass
+
+    @abc.abstractmethod
+    async def delete_catalog(
+        self,
+        catalog_id: str,
+        refresh: bool = False,
+        version: DocumentVersion | None = None,
+    ) -> None:
         """Delete a catalog from the database.
 
         Implementations MUST verify the document exists and is a Catalog
         before deleting, raising NotFoundError otherwise; deleting a catalog
-        must never remove Collection or Item data.
+        must never remove Collection or Item data. With `version` (If-Match),
+        only that stored version is deleted, and nothing changes otherwise.
+        """
+        pass
+
+    @abc.abstractmethod
+    async def unlink_catalog_orphans(self, catalog_id: str) -> None:
+        """Unlink children that still reference a catalog that no longer exists.
+
+        Nothing is deleted. A retry of a catalog delete whose cleanup failed
+        calls this, with or without If-Match.
         """
         pass
 
@@ -217,8 +376,9 @@ class BaseDatabaseLogic(abc.ABC):
         token: str | None,
         request: Any = None,
         resource_type: str | None = None,
+        filter: dict[str, Any] | None = None,
     ) -> tuple[list[dict[str, Any]], int, str | None]:
-        """Get children of a catalog.
+        """Get children of a catalog, optionally matching a CQL2 JSON filter.
 
         Returns:
             Tuple of (children_list, total_count, next_token).
@@ -232,9 +392,15 @@ class BaseDatabaseLogic(abc.ABC):
         limit: int,
         token: str | None,
         request: Any = None,
+        filter: dict[str, Any] | None = None,
+        sort: list[dict[str, Any]] | None = None,
+        q: list[str] | None = None,
     ) -> tuple[list[dict[str, Any]], int, str | None]:
         """Get collections of a catalog.
 
+        Optionally matching a CQL2 JSON `filter`, ordered by `sort`
+        ({field, direction} pairs), and matching `q` free-text terms.
+
         Returns:
             Tuple of (collections_list, total_count, next_token).
         """
@@ -247,8 +413,9 @@ class BaseDatabaseLogic(abc.ABC):
         limit: int,
         token: str | None,
         request: Any = None,
+        filter: dict[str, Any] | None = None,
     ) -> tuple[list[dict[str, Any]], int, str | None]:
-        """Get sub-catalogs of a catalog.
+        """Get sub-catalogs of a catalog, optionally matching a CQL2 JSON filter.
 
         Returns:
             Tuple of (catalogs_list, total_count, next_token).
@@ -295,34 +462,26 @@ class BaseDatabaseLogic(abc.ABC):
         datetime: str | None = None,
         limit: int = 10,
         sortby: str | None = None,
-        filter_expr: str | None = None,
-        filter_lang: str | None = None,
+        filter: dict[str, Any] | None = None,
         token: str | None = None,
         query: str | None = None,
         fields: list[str] | None = None,
     ) -> Any:
-        """Get items from a collection in a catalog."""
-        pass
-
-    @abc.abstractmethod
-    async def get_catalog_collection_item(
-        self,
-        catalog_id: str,
-        collection_id: str,
-        item_id: str,
-        request: Any,
-    ) -> Any:
-        """Get an item from a collection in a catalog."""
+        """Get items from a collection in a catalog, optionally matching a CQL2 JSON filter."""
         pass
 
     @abc.abstractmethod
     async def update_catalog(
         self,
         catalog_id: str,
-        catalog: Any,
-        request: Any,
-    ) -> Any:
-        """Update a catalog."""
+        catalog: dict,
+        refresh: bool | str = False,
+        version: DocumentVersion | None = None,
+    ) -> DocumentVersion | None:
+        """Replace a catalog, keeping its stored parent_ids; return the version stored.
+
+        With `version` (If-Match), only that stored version is replaced; 412 otherwise.
+        """
         pass
 
     @abc.abstractmethod
@@ -388,7 +547,9 @@ class BaseDatabaseLogic(abc.ABC):
         pass
 
     @abc.abstractmethod
-    def populate_sort(self, sortby: list) -> Any:
+    def populate_sort(
+        self, sortby: list, field_types: dict[str, str] | None = None
+    ) -> Any:
         """Populate sort for the search."""
         pass
 
@@ -464,6 +625,11 @@ class BaseDatabaseLogic(abc.ABC):
         """Check if a collection exists."""
         pass
 
+    @abc.abstractmethod
+    def check_collection_exists_sync(self, collection_id: str) -> None:
+        """Check if a collection exists, using the synchronous client."""
+        pass
+
     @abc.abstractmethod
     async def delete_items(self) -> None:
         """Delete all items."""