sfeos-helpers 6.5.0__tar.gz → 6.6.0__tar.gz

sfeos_helpers-6.6.0/.gitignore

@@ -0,0 +1,143 @@
+elasticsearch/snapshots/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+/esdata
+
+# Virtualenv
+venv
+
+# VSCode folder
+.vscode
+
+/docs/src/api/*
+
+.DS_Store

sfeos_helpers-6.6.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: sfeos_helpers
+Version: 6.6.0
+Summary: Helper library for the Elasticsearch and Opensearch stac-fastapi backends.
+Project-URL: Homepage, https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch
+License: MIT
+Keywords: Elasticsearch,FastAPI,Opensearch,STAC,STAC-API,stac-fastapi
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Requires-Dist: stac-fastapi-core==6.6.0
+Description-Content-Type: text/markdown
+
+# sfeos-helpers
+
+Helper utilities for the stac-fastapi project. For full documentation, please see the [main README](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/blob/main/README.md).
+
+## Package Information
+
+- **Package name**: sfeos-helpers
+- **Description**: Helper utilities for the stac-fastapi project.
+- **Documentation**: [https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/](https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/)
+- **Source**: [GitHub Repository](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/)
+
+## Installation
+
+This package is a dependency of stac-fastapi-elasticsearch and stac-fastapi-opensearch and is typically installed automatically.
+
+```bash
+pip install stac-fastapi-elasticsearch  # or stac-fastapi-opensearch
+```
+
+## Quick Start
+
+For detailed usage and examples, please refer to the [main documentation](https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/).

sfeos_helpers-6.6.0/README.md

@@ -0,0 +1,22 @@
+# sfeos-helpers
+
+Helper utilities for the stac-fastapi project. For full documentation, please see the [main README](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/blob/main/README.md).
+
+## Package Information
+
+- **Package name**: sfeos-helpers
+- **Description**: Helper utilities for the stac-fastapi project.
+- **Documentation**: [https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/](https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/)
+- **Source**: [GitHub Repository](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/)
+
+## Installation
+
+This package is a dependency of stac-fastapi-elasticsearch and stac-fastapi-opensearch and is typically installed automatically.
+
+```bash
+pip install stac-fastapi-elasticsearch  # or stac-fastapi-opensearch
+```
+
+## Quick Start
+
+For detailed usage and examples, please refer to the [main documentation](https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/).

sfeos_helpers-6.6.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sfeos_helpers"
+description = "Helper library for the Elasticsearch and Opensearch stac-fastapi backends."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = []
+classifiers = [
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "License :: OSI Approved :: MIT License",
+]
+keywords = [
+    "STAC",
+    "STAC-API",
+    "FastAPI",
+    "stac-fastapi",
+    "Elasticsearch",
+    "Opensearch",
+]
+dynamic = ["version"]
+dependencies = [
+    "stac-fastapi.core==6.6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch"
+
+[tool.hatch.version]
+path = "stac_fastapi/sfeos_helpers/version.py"
+
+[tool.hatch.build.targets.sdist]
+exclude = ["alembic", "tests", "scripts"]
+
+[tool.hatch.build.targets.wheel]
+only-include = ["stac_fastapi"]

sfeos_helpers-6.6.0/stac_fastapi/sfeos_helpers/aggregation/README.md

@@ -0,0 +1,57 @@
+# STAC FastAPI Aggregation Package
+
+This package contains shared aggregation functionality used by both the Elasticsearch and OpenSearch implementations of STAC FastAPI. It helps reduce code duplication and ensures consistent behavior between the two implementations.
+
+## Package Structure
+
+The aggregation package is organized into three main modules:
+
+- **client.py**: Contains the base aggregation client implementation
+  - `EsAsyncBaseAggregationClient`: The main class that implements the STAC aggregation extension for Elasticsearch/OpenSearch
+  - Methods for handling aggregation requests, validating parameters, and formatting responses
+
+- **format.py**: Contains functions for formatting aggregation responses
+  - `frequency_agg`: Formats frequency distribution aggregation responses
+  - `metric_agg`: Formats metric aggregation responses
+
+- **__init__.py**: Package initialization and exports
+  - Exports the main classes and functions for use by other modules
+
+## Features
+
+The aggregation package provides the following features:
+
+- Support for various aggregation types:
+  - Datetime frequency
+  - Collection frequency
+  - Property frequency
+  - Geospatial grid aggregations (geohash, geohex, geotile)
+  - Metric aggregations (min, max, etc.)
+
+- Parameter validation:
+  - Precision validation for geospatial aggregations
+  - Interval validation for datetime aggregations
+
+- Response formatting:
+  - Consistent response structure
+  - Proper typing and documentation
+
+## Usage
+
+The aggregation package is used by the Elasticsearch and OpenSearch implementations to provide aggregation functionality for STAC API. The main entry point is the `EsAsyncBaseAggregationClient` class, which is instantiated in the respective app.py files.
+
+Example:
+```python
+from stac_fastapi.sfeos_helpers.aggregation import EsAsyncBaseAggregationClient
+
+# Create an instance of the aggregation client
+aggregation_client = EsAsyncBaseAggregationClient(database)
+
+# Register the aggregation extension with the API
+api = StacApi(
+    ...,
+    extensions=[
+        ...,
+        AggregationExtension(client=aggregation_client),
+    ],
+)

sfeos_helpers-6.6.0/stac_fastapi/sfeos_helpers/database/README.md

@@ -0,0 +1,61 @@
+# STAC FastAPI Database Package
+
+This package contains shared database operations used by both the Elasticsearch and OpenSearch
+implementations of STAC FastAPI. It helps reduce code duplication and ensures consistent behavior
+between the two implementations.
+
+## Package Structure
+
+The database package is organized into five main modules:
+
+- **index.py**: Contains functions for managing indices
+  - [create_index_templates_shared](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/database_logic_helpers.py:15:0-48:33): Creates index templates for Collections and Items
+  - [delete_item_index_shared](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/database_logic_helpers.py:128:0-153:30): Deletes an item index for a collection
+  - [index_by_collection_id](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/utilities.py:86:0-100:5): Translates a collection ID into an index name
+  - [index_alias_by_collection_id](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/utilities.py:103:0-115:5): Translates a collection ID into an index alias
+  - [indices](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/utilities.py:118:0-132:5): Gets a comma-separated string of index names
+
+- **query.py**: Contains functions for building and manipulating queries
+  - [apply_free_text_filter_shared](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/database_logic_helpers.py:51:0-74:16): Applies a free text filter to a search
+  - [apply_intersects_filter_shared](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/database_logic_helpers.py:77:0-104:5): Creates a geo_shape filter for intersecting geometry
+  - [populate_sort_shared](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/database_logic_helpers.py:107:0-125:16): Creates a sort configuration for queries
+
+- **mapping.py**: Contains functions for working with mappings
+  - [get_queryables_mapping_shared](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/database_logic_helpers.py:156:0-185:27): Retrieves mapping of Queryables for search
+
+- **document.py**: Contains functions for working with documents
+  - [mk_item_id](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/utilities.py:140:0-150:5): Creates a document ID for an Item
+  - [mk_actions](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/utilities.py:153:0-175:5): Creates bulk actions for indexing items
+
+- **utils.py**: Contains utility functions for database operations
+  - [validate_refresh](cci:1://file:///home/computer/Code/stac-fastapi-elasticsearch-opensearch/stac_fastapi/sfeos_helpers/stac_fastapi/sfeos_helpers/utilities.py:41:0-78:5): Validates the refresh parameter value
+
+## Usage
+
+Import the necessary components from the database package:
+
+```python
+from stac_fastapi.sfeos_helpers.database import (
+    # Index operations
+    create_index_templates_shared,
+    delete_item_index_shared,
+    index_alias_by_collection_id,
+    index_by_collection_id,
+    indices,
+    
+    # Query operations
+    apply_free_text_filter_shared,
+    apply_intersects_filter_shared,
+    populate_sort_shared,
+    
+    # Mapping operations
+    get_queryables_mapping_shared,
+    
+    # Document operations
+    mk_item_id,
+    mk_actions,
+    
+    # Utility functions
+    validate_refresh,
+)
+```

{sfeos_helpers-6.5.0 → sfeos_helpers-6.6.0}/stac_fastapi/sfeos_helpers/database/__init__.py

@@ -42,11 +42,13 @@ from .index import (
 )
 from .mapping import get_queryables_mapping_shared
 from .query import (
+    apply_collections_bbox_filter_shared,
+    apply_collections_datetime_filter_shared,
     apply_free_text_filter_shared,
     apply_intersects_filter_shared,
     populate_sort_shared,
 )
-from .utils import get_bool_env, validate_refresh
+from .utils import add_bbox_shape_to_collection, get_bool_env, validate_refresh
 
 __all__ = [
     # Index operations
@@ -59,6 +61,8 @@ __all__ = [
     # Query operations
     "apply_free_text_filter_shared",
     "apply_intersects_filter_shared",
+    "apply_collections_bbox_filter_shared",
+    "apply_collections_datetime_filter_shared",
     "populate_sort_shared",
     # Mapping operations
     "get_queryables_mapping_shared",
@@ -68,6 +72,7 @@ __all__ = [
     # Utility functions
     "validate_refresh",
     "get_bool_env",
+    "add_bbox_shape_to_collection",
     # Datetime utilities
     "return_date",
     "extract_date",

sfeos_helpers-6.6.0/stac_fastapi/sfeos_helpers/database/query.py

@@ -0,0 +1,255 @@
+"""Query building functions for Elasticsearch/OpenSearch.
+
+This module provides functions for building and manipulating Elasticsearch/OpenSearch queries.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, Union
+
+from stac_fastapi.core.utilities import bbox2polygon
+from stac_fastapi.sfeos_helpers.mappings import Geometry
+
+ES_MAX_URL_LENGTH = 4096
+
+
+def apply_free_text_filter_shared(
+    search: Any, free_text_queries: Optional[List[str]]
+) -> Any:
+    """Create a free text query for Elasticsearch/OpenSearch.
+
+    Args:
+        search (Any): The search object to apply the query to.
+        free_text_queries (Optional[List[str]]): A list of text strings to search for in the properties.
+
+    Returns:
+        Any: The search object with the free text query applied, or the original search
+            object if no free_text_queries were provided.
+
+    Notes:
+        This function creates a query_string query that searches for the specified text strings
+        in all properties of the documents. The query strings are joined with OR operators.
+    """
+    if free_text_queries is not None:
+        free_text_query_string = '" OR properties.\\*:"'.join(free_text_queries)
+        search = search.query(
+            "query_string", query=f'properties.\\*:"{free_text_query_string}"'
+        )
+
+    return search
+
+
+def apply_intersects_filter_shared(
+    intersects: Geometry,
+) -> Dict[str, Dict]:
+    """Create a geo_shape filter for intersecting geometry.
+
+    Args:
+        intersects (Geometry): The intersecting geometry, represented as a GeoJSON-like object.
+
+    Returns:
+        Dict[str, Dict]: A dictionary containing the geo_shape filter configuration
+            that can be used with Elasticsearch/OpenSearch Q objects.
+
+    Notes:
+        This function creates a geo_shape filter configuration to find documents that intersect
+        with the specified geometry. The returned dictionary should be wrapped in a Q object
+        when applied to a search.
+    """
+    return {
+        "geo_shape": {
+            "geometry": {
+                "shape": {
+                    "type": intersects.type.lower(),
+                    "coordinates": intersects.coordinates,
+                },
+                "relation": "intersects",
+            }
+        }
+    }
+
+
+def apply_collections_datetime_filter_shared(
+    datetime_str: Optional[str],
+) -> Optional[Dict[str, Any]]:
+    """Create a temporal filter for collections based on their extent.
+
+    Args:
+        datetime_str: The datetime parameter. Can be:
+            - A single datetime string (e.g., "2020-01-01T00:00:00Z")
+            - A datetime range with "/" separator (e.g., "2020-01-01T00:00:00Z/2021-01-01T00:00:00Z")
+            - Open-ended ranges using ".." (e.g., "../2021-01-01T00:00:00Z" or "2020-01-01T00:00:00Z/..")
+            - None if no datetime filter is provided
+
+    Returns:
+        Optional[Dict[str, Any]]: A dictionary containing the temporal filter configuration
+            that can be used with Elasticsearch/OpenSearch queries, or None if datetime_str is None.
+            Example return value:
+            {
+                "bool": {
+                    "must": [
+                        {"range": {"extent.temporal.interval": {"lte": "2021-01-01T00:00:00Z"}}},
+                        {"range": {"extent.temporal.interval": {"gte": "2020-01-01T00:00:00Z"}}}
+                    ]
+                }
+            }
+
+    Notes:
+        - This function is specifically for filtering collections by their temporal extent
+        - It queries the extent.temporal.interval field
+        - Open-ended ranges (..) are replaced with concrete dates (1800-01-01 for start, 2999-12-31 for end)
+    """
+    if not datetime_str:
+        return None
+
+    # Parse the datetime string into start and end
+    if "/" in datetime_str:
+        start, end = datetime_str.split("/")
+        # Replace open-ended ranges with concrete dates
+        if start == "..":
+            # For open-ended start, use a very early date
+            start = "1800-01-01T00:00:00Z"
+        if end == "..":
+            # For open-ended end, use a far future date
+            end = "2999-12-31T23:59:59Z"
+    else:
+        # If it's just a single date, use it for both start and end
+        start = end = datetime_str
+
+    return {
+        "bool": {
+            "must": [
+                # Check if any date in the array is less than or equal to the query end date
+                # This will match if the collection's start date is before or equal to the query end date
+                {"range": {"extent.temporal.interval": {"lte": end}}},
+                # Check if any date in the array is greater than or equal to the query start date
+                # This will match if the collection's end date is after or equal to the query start date
+                {"range": {"extent.temporal.interval": {"gte": start}}},
+            ]
+        }
+    }
+
+
+def apply_collections_bbox_filter_shared(
+    bbox: Union[str, List[float], None]
+) -> Optional[Dict[str, Dict]]:
+    """Create a geo_shape filter for collections bbox search.
+
+    This function handles bbox parsing from both GET requests (string format) and POST requests
+    (list format), and constructs a geo_shape query for filtering collections by their bbox_shape field.
+
+    Args:
+        bbox: The bounding box parameter. Can be:
+            - A string of comma-separated coordinates (from GET requests)
+            - A list of floats [minx, miny, maxx, maxy] for 2D bbox
+            - None if no bbox filter is provided
+
+    Returns:
+        Optional[Dict[str, Dict]]: A dictionary containing the geo_shape filter configuration
+            that can be used with Elasticsearch/OpenSearch queries, or None if bbox is invalid.
+            Example return value:
+            {
+                "geo_shape": {
+                    "bbox_shape": {
+                        "shape": {
+                            "type": "Polygon",
+                            "coordinates": [[[minx, miny], [maxx, miny], [maxx, maxy], [minx, maxy], [minx, miny]]]
+                        },
+                        "relation": "intersects"
+                    }
+                }
+            }
+
+    Notes:
+        - This function is specifically for filtering collections by their spatial extent
+        - It queries the bbox_shape field (not the geometry field used for items)
+        - The bbox is expected to be 2D (4 values) after any 3D to 2D conversion in the API layer
+    """
+    logger = logging.getLogger(__name__)
+
+    if not bbox:
+        return None
+
+    # Parse bbox if it's a string (from GET requests)
+    if isinstance(bbox, str):
+        try:
+            bbox = [float(x.strip()) for x in bbox.split(",")]
+        except (ValueError, AttributeError) as e:
+            logger.error(f"Invalid bbox format: {bbox}, error: {e}")
+            return None
+
+    if not bbox or len(bbox) != 4:
+        if bbox:
+            logger.warning(
+                f"bbox has incorrect number of coordinates (length={len(bbox)}), expected 4 (2D bbox)"
+            )
+        return None
+
+    # Convert bbox to a polygon for geo_shape query
+    bbox_polygon = {
+        "type": "Polygon",
+        "coordinates": bbox2polygon(bbox[0], bbox[1], bbox[2], bbox[3]),
+    }
+
+    # Return geo_shape query for bbox_shape field
+    return {
+        "geo_shape": {
+            "bbox_shape": {
+                "shape": bbox_polygon,
+                "relation": "intersects",
+            }
+        }
+    }
+
+
+def populate_sort_shared(sortby: List) -> Optional[Dict[str, Dict[str, str]]]:
+    """Create a sort configuration for Elasticsearch/OpenSearch queries.
+
+    Args:
+        sortby (List): A list of sort specifications, each containing a field and direction.
+
+    Returns:
+        Optional[Dict[str, Dict[str, str]]]: A dictionary mapping field names to sort direction
+            configurations, or None if no sort was specified.
+
+    Notes:
+        This function transforms a list of sort specifications into the format required by
+        Elasticsearch/OpenSearch for sorting query results. The returned dictionary can be
+        directly used in search requests.
+        Always includes 'id' as secondary sort to ensure unique pagination tokens.
+    """
+    if sortby:
+        sort_config = {s.field: {"order": s.direction} for s in sortby}
+        sort_config.setdefault("id", {"order": "asc"})
+        return sort_config
+    else:
+        return {"id": {"order": "asc"}}
+
+
+def add_collections_to_body(
+    collection_ids: List[str], query: Optional[Dict[str, Any]]
+) -> Dict[str, Any]:
+    """Add a list of collection ids to the body of a query.
+
+    Args:
+        collection_ids (List[str]): A list of collections ids.
+        query (Optional[Dict[str, Any]]): The query to add collections to. If none, create a query that filters
+        the collection ids.
+
+    Returns:
+        Dict[str, Any]: A query that contains a filter on the given collection ids.
+
+    Notes:
+        This function is needed in the execute_search function when the size of the URL path will exceed the maximum of ES.
+    """
+    index_filter = {"terms": {"collection": collection_ids}}
+    if query is None:
+        query = {"query": {}}
+    if "bool" not in query:
+        query["bool"] = {}
+    if "filter" not in query["bool"]:
+        query["bool"]["filter"] = []
+
+    filters = query["bool"]["filter"]
+    if index_filter not in filters:
+        filters.append(index_filter)
+    return query