sfeos-helpers 6.0.0__py3-none-any.whl → 6.2.0__py3-none-any.whl

stac_fastapi/sfeos_helpers/search_engine/selection/base.py

@@ -0,0 +1,30 @@
+"""Base classes for index selection strategies."""
+
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional
+
+
+class BaseIndexSelector(ABC):
+    """Base class for async index selectors."""
+
+    @abstractmethod
+    async def select_indexes(
+        self,
+        collection_ids: Optional[List[str]],
+        datetime_search: Dict[str, Optional[str]],
+    ) -> str:
+        """Select appropriate indexes asynchronously.
+
+        Args:
+            collection_ids (Optional[List[str]]): List of collection IDs to filter by.
+            datetime_search (Dict[str, Optional[str]]): Datetime search criteria.
+
+        Returns:
+            str: Comma-separated string of selected index names.
+        """
+        pass
+
+    @abstractmethod
+    async def refresh_cache(self):
+        """Refresh cache (no-op for unfiltered selector)."""
+        pass

stac_fastapi/sfeos_helpers/search_engine/selection/cache_manager.py

@@ -0,0 +1,127 @@
+"""Cache management for index selection strategies."""
+
+import threading
+import time
+from collections import defaultdict
+from typing import Any, Dict, List, Optional
+
+from stac_fastapi.sfeos_helpers.database import index_alias_by_collection_id
+from stac_fastapi.sfeos_helpers.mappings import ITEMS_INDEX_PREFIX
+
+
+class IndexCacheManager:
+    """Manages caching of index aliases with expiration."""
+
+    def __init__(self, cache_ttl_seconds: int = 3600):
+        """Initialize the cache manager.
+
+        Args:
+            cache_ttl_seconds (int): Time-to-live for cache entries in seconds.
+        """
+        self._cache: Optional[Dict[str, List[str]]] = None
+        self._timestamp: float = 0
+        self._ttl = cache_ttl_seconds
+        self._lock = threading.Lock()
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if the cache has expired.
+
+        Returns:
+            bool: True if cache is expired, False otherwise.
+        """
+        return time.time() - self._timestamp > self._ttl
+
+    def get_cache(self) -> Optional[Dict[str, List[str]]]:
+        """Get the current cache if not expired.
+
+        Returns:
+            Optional[Dict[str, List[str]]]: Cache data if valid, None if expired.
+        """
+        with self._lock:
+            if self.is_expired:
+                return None
+            return {k: v.copy() for k, v in self._cache.items()}
+
+    def set_cache(self, data: Dict[str, List[str]]) -> None:
+        """Set cache data and update timestamp.
+
+        Args:
+            data (Dict[str, List[str]]): Cache data to store.
+        """
+        self._cache = data
+        self._timestamp = time.time()
+
+    def clear_cache(self) -> None:
+        """Clear the cache and reset timestamp."""
+        self._cache = None
+        self._timestamp = 0
+
+
+class IndexAliasLoader:
+    """Asynchronous loader for index aliases."""
+
+    def __init__(self, client: Any, cache_manager: IndexCacheManager):
+        """Initialize the async alias loader.
+
+        Args:
+            client: Async search engine client instance.
+            cache_manager (IndexCacheManager): Cache manager instance.
+        """
+        self.client = client
+        self.cache_manager = cache_manager
+
+    async def load_aliases(self) -> Dict[str, List[str]]:
+        """Load index aliases from search engine.
+
+        Returns:
+            Dict[str, List[str]]: Mapping of base aliases to item aliases.
+        """
+        response = await self.client.indices.get_alias(index=f"{ITEMS_INDEX_PREFIX}*")
+        result = defaultdict(list)
+        for index_info in response.values():
+            aliases = index_info.get("aliases", {})
+            items_aliases = sorted(
+                [
+                    alias
+                    for alias in aliases.keys()
+                    if alias.startswith(ITEMS_INDEX_PREFIX)
+                ]
+            )
+
+            if items_aliases:
+                result[items_aliases[0]].extend(items_aliases[1:])
+
+        self.cache_manager.set_cache(result)
+        return result
+
+    async def get_aliases(self) -> Dict[str, List[str]]:
+        """Get aliases from cache or load if expired.
+
+        Returns:
+            Dict[str, List[str]]: Alias mapping data.
+        """
+        cached = self.cache_manager.get_cache()
+        if cached is not None:
+            return cached
+        return await self.load_aliases()
+
+    async def refresh_aliases(self) -> Dict[str, List[str]]:
+        """Force refresh aliases from search engine.
+
+        Returns:
+            Dict[str, List[str]]: Fresh alias mapping data.
+        """
+        return await self.load_aliases()
+
+    async def get_collection_indexes(self, collection_id: str) -> List[str]:
+        """Get all index aliases for a specific collection.
+
+        Args:
+            collection_id (str): Collection identifier.
+
+        Returns:
+            List[str]: List of index aliases for the collection.
+        """
+        aliases = await self.get_aliases()
+        return aliases.get(index_alias_by_collection_id(collection_id), [])

stac_fastapi/sfeos_helpers/search_engine/selection/factory.py

@@ -0,0 +1,37 @@
+"""Factory for creating index selection strategies."""
+
+from typing import Any
+
+from stac_fastapi.core.utilities import get_bool_env
+
+from .base import BaseIndexSelector
+from .selectors import DatetimeBasedIndexSelector, UnfilteredIndexSelector
+
+
+class IndexSelectorFactory:
+    """Factory class for creating index selector instances."""
+
+    @staticmethod
+    def create_selector(client: Any) -> BaseIndexSelector:
+        """Create an appropriate asynchronous index selector based on environment configuration.
+
+        Checks the ENABLE_DATETIME_INDEX_FILTERING environment variable to determine
+        whether to use datetime-based filtering or return all available indices.
+
+        Args:
+            client: Asynchronous Elasticsearch/OpenSearch client instance, used only if datetime
+                filtering is enabled.
+
+        Returns:
+            IndexSelectionStrategy: Either an AsyncDatetimeBasedIndexSelector if datetime
+                filtering is enabled, or an UnfilteredIndexSelector otherwise.
+        """
+        use_datetime_filtering = get_bool_env(
+            "ENABLE_DATETIME_INDEX_FILTERING", default="false"
+        )
+
+        return (
+            DatetimeBasedIndexSelector(client)
+            if use_datetime_filtering
+            else UnfilteredIndexSelector()
+        )

stac_fastapi/sfeos_helpers/search_engine/selection/selectors.py

@@ -0,0 +1,129 @@
+"""Async index selectors with datetime-based filtering."""
+
+from typing import Any, Dict, List, Optional
+
+from stac_fastapi.sfeos_helpers.database import filter_indexes_by_datetime
+from stac_fastapi.sfeos_helpers.mappings import ITEM_INDICES
+
+from ...database import indices
+from .base import BaseIndexSelector
+from .cache_manager import IndexAliasLoader, IndexCacheManager
+
+
+class DatetimeBasedIndexSelector(BaseIndexSelector):
+    """Asynchronous index selector that filters indices based on datetime criteria with caching."""
+
+    _instance = None
+
+    def __new__(cls, client):
+        """Create singleton instance.
+
+        Args:
+            client: Async search engine client instance.
+
+        Returns:
+            DatetimeBasedIndexSelector: Singleton instance.
+        """
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self, client: Any):
+        """Initialize the datetime-based index selector.
+
+        Args:
+            client: Elasticsearch/OpenSearch client instance used for querying
+                index aliases and metadata.
+        """
+        if not hasattr(self, "_initialized"):
+            self.cache_manager = IndexCacheManager()
+            self.alias_loader = IndexAliasLoader(client, self.cache_manager)
+            self._initialized = True
+
+    async def refresh_cache(self) -> Dict[str, List[str]]:
+        """Force refresh of the aliases cache.
+
+        Returns:
+            Dict[str, List[str]]: Refreshed dictionary mapping base collection aliases
+                to lists of their corresponding item index aliases.
+        """
+        return await self.alias_loader.refresh_aliases()
+
+    async def get_collection_indexes(self, collection_id: str) -> List[str]:
+        """Get all index aliases for a specific collection.
+
+        Args:
+            collection_id (str): The ID of the collection to retrieve indexes for.
+
+        Returns:
+            List[str]: List of index aliases associated with the collection.
+                Returns empty list if collection is not found in cache.
+        """
+        return await self.alias_loader.get_collection_indexes(collection_id)
+
+    async def select_indexes(
+        self,
+        collection_ids: Optional[List[str]],
+        datetime_search: Dict[str, Optional[str]],
+    ) -> str:
+        """Select indexes filtered by collection IDs and datetime criteria.
+
+        For each specified collection, retrieves its associated indexes and filters
+        them based on datetime range. If no collection IDs are provided, returns
+        all item indices.
+
+        Args:
+            collection_ids (Optional[List[str]]): List of collection IDs to filter by.
+                If None or empty, returns all item indices.
+            datetime_search (Dict[str, Optional[str]]): Dictionary containing datetime
+                search criteria with 'gte' and 'lte' keys for range filtering.
+
+        Returns:
+            str: Comma-separated string of selected index names that match the
+                collection and datetime criteria. Returns empty string if no
+                indexes match the criteria.
+        """
+        if collection_ids:
+            selected_indexes = []
+            for collection_id in collection_ids:
+                collection_indexes = await self.get_collection_indexes(collection_id)
+                filtered_indexes = filter_indexes_by_datetime(
+                    collection_indexes,
+                    datetime_search.get("gte"),
+                    datetime_search.get("lte"),
+                )
+                selected_indexes.extend(filtered_indexes)
+
+            return ",".join(selected_indexes) if selected_indexes else ""
+
+        return ITEM_INDICES
+
+
+class UnfilteredIndexSelector(BaseIndexSelector):
+    """Index selector that returns all available indices without filtering."""
+
+    async def select_indexes(
+        self,
+        collection_ids: Optional[List[str]],
+        datetime_search: Dict[str, Optional[str]],
+    ) -> str:
+        """Select all indices for given collections without datetime filtering.
+
+        Args:
+            collection_ids (Optional[List[str]]): List of collection IDs to filter by.
+                If None, all collections are considered.
+            datetime_search (Dict[str, Optional[str]]): Datetime search criteria
+                (ignored by this implementation).
+
+        Returns:
+            str: Comma-separated string of all available index names for the collections.
+        """
+        return indices(collection_ids)
+
+    async def refresh_cache(self):
+        """Refresh cache (no-op for unfiltered selector).
+
+        Note:
+            Unfiltered selector doesn't use cache, so this is a no-op operation.
+        """
+        pass

stac_fastapi/sfeos_helpers/version.py

@@ -1,2 +1,2 @@
 """library version."""
-__version__ = "6.0.0"
+__version__ = "6.2.0"

sfeos_helpers-6.0.0.dist-info/RECORD

@@ -1,21 +0,0 @@
-stac_fastapi/sfeos_helpers/mappings.py,sha256=z6GJFJUE7bRKF9ODc8_ddkb7JCOokMtj4p2LeaQqrQQ,8237
-stac_fastapi/sfeos_helpers/version.py,sha256=Fo5UFEQVxJZ3nywa3IY-enu5UQBE0X45nrQaRBe8c9o,45
-stac_fastapi/sfeos_helpers/aggregation/__init__.py,sha256=Mym17lFh90by1GnoQgMyIKAqRNJnvCgVSXDYzjBiPQk,1210
-stac_fastapi/sfeos_helpers/aggregation/client.py,sha256=JCUVBXsUXHdUXn59WaytGxB-R6OLhC_LApPm-pzQNTI,17818
-stac_fastapi/sfeos_helpers/aggregation/format.py,sha256=qUW1jjh2EEjy-V7riliFR77grpi-AgsTmP76z60K5Lo,2011
-stac_fastapi/sfeos_helpers/database/__init__.py,sha256=WAZc7Djw9VZHt-crkFkhtILVCZb8GzIegS6CpdGA4gc,2477
-stac_fastapi/sfeos_helpers/database/datetime.py,sha256=L_bY0EtRi6b8XIN9zcHbFe-O2jFdItkgkNvkQ4Z1jyY,2279
-stac_fastapi/sfeos_helpers/database/document.py,sha256=LtjX15gvaOuZC_k2t_oQhys_c-zRTLN5rwX0hNJkHnM,1725
-stac_fastapi/sfeos_helpers/database/index.py,sha256=7xFNzOQzFxBAtQUKUmhKcqz5j3_HRPuwIecdEEWb0i0,4476
-stac_fastapi/sfeos_helpers/database/mapping.py,sha256=4-MSd4xH5wg7yoC4aPjzYMDSEvP026bw4k2TfffMT5E,1387
-stac_fastapi/sfeos_helpers/database/query.py,sha256=3aFby56ggvTxtBg1vH1AXw2P2_CloPIV-cwL260P47E,2972
-stac_fastapi/sfeos_helpers/database/utils.py,sha256=nPTWqP-pdSZumeYRx92XTN4xmmufRSqCDHaiSLdg-3o,7311
-stac_fastapi/sfeos_helpers/filter/__init__.py,sha256=n3zL_MhEGOoxMz1KeijyK_UKiZ0MKPl90zHtYI5RAy8,1557
-stac_fastapi/sfeos_helpers/filter/client.py,sha256=QwjYWXkevoVS7HPtoXfeSzDy-_GJnFhPJtJM49D14oU,4229
-stac_fastapi/sfeos_helpers/filter/cql2.py,sha256=Cg9kRYD9CVkVSyRqOyB5oVXmlyteSn2bw88sqklGpUM,955
-stac_fastapi/sfeos_helpers/filter/transform.py,sha256=1GEWQSp-rbq7_1nDVv1ApDbWxt8DswJWxwaxzV85gj4,4644
-stac_fastapi/sfeos_helpers/models/patch.py,sha256=akzfF7vXI6AyGDrxgP8KqVwBvBDQayXYNNf4pm6Q8qM,4209
-sfeos_helpers-6.0.0.dist-info/METADATA,sha256=huD7geSPsXMjM-KvE7KsaM6gTuGHRO7QPDBlpyTBayc,31173
-sfeos_helpers-6.0.0.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-sfeos_helpers-6.0.0.dist-info/top_level.txt,sha256=vqn-D9-HsRPTTxy0Vk_KkDmTiMES4owwBQ3ydSZYb2s,13
-sfeos_helpers-6.0.0.dist-info/RECORD,,