Adding free-text extension. (#655)

* Adding free-text extension.

* Adding pull request to change log.

* q parameter should be string for post.

* Removing unneeded imports.

* split free-text ext

---------

Co-authored-by: vincentsarago <[email protected]>

CHANGES.md

@@ -2,8 +2,14 @@
 
 ## [Unreleased] - TBD
 
+### Changed
+
 * add more openapi metadata in input models [#734](https://github.com/stac-utils/stac-fastapi/pull/734)
 
+### Added
+
+* Add Free-text Extension to third party extensions ([#655](https://github.com/stac-utils/stac-fastapi/pull/655))
+
 ## [3.0.0b2] - 2024-07-09
 
 ### Changed

docs/mkdocs.yml

@@ -36,6 +36,10 @@ nav:
           - core:
               - module: api/stac_fastapi/extensions/core/index.md
               - context: api/stac_fastapi/extensions/core/context.md
+              - free_text:
+                - module: api/stac_fastapi/extensions/core/free_text/index.md
+                - free_text: api/stac_fastapi/extensions/core/free_text/free_text.md
+                - request: api/stac_fastapi/extensions/core/free_text/request.md
               - filter:
                   - module: api/stac_fastapi/extensions/core/filter/index.md
                   - filter: api/stac_fastapi/extensions/core/filter/filter.md

stac_fastapi/api/stac_fastapi/api/config.py

@@ -19,6 +19,7 @@ class ApiExtensions(enum.Enum):
     sort = "sort"
     transaction = "transaction"
     aggregation = "aggregation"
+    free_text = "free-text"
 
 
 class AddOns(enum.Enum):

stac_fastapi/extensions/stac_fastapi/extensions/core/__init__.py

@@ -4,6 +4,7 @@
 from .context import ContextExtension
 from .fields import FieldsExtension
 from .filter import FilterExtension
+from .free_text import FreeTextAdvancedExtension, FreeTextExtension
 from .pagination import PaginationExtension, TokenPaginationExtension
 from .query import QueryExtension
 from .sort import SortExtension
@@ -14,6 +15,8 @@
     "ContextExtension",
     "FieldsExtension",
     "FilterExtension",
+    "FreeTextExtension",
+    "FreeTextAdvancedExtension",
     "PaginationExtension",
     "QueryExtension",
     "SortExtension",

stac_fastapi/extensions/stac_fastapi/extensions/core/free_text/__init__.py

@@ -0,0 +1,13 @@
+"""Query extension module."""
+
+from .free_text import (
+    FreeTextAdvancedExtension,
+    FreeTextConformanceClasses,
+    FreeTextExtension,
+)
+
+__all__ = [
+    "FreeTextExtension",
+    "FreeTextAdvancedExtension",
+    "FreeTextConformanceClasses",
+]

stac_fastapi/extensions/stac_fastapi/extensions/core/free_text/free_text.py

@@ -0,0 +1,110 @@
+"""Free-text extension."""
+
+from enum import Enum
+from typing import List, Optional
+
+import attr
+from fastapi import FastAPI
+
+from stac_fastapi.types.extension import ApiExtension
+
+from .request import (
+    FreeTextAdvancedExtensionGetRequest,
+    FreeTextAdvancedExtensionPostRequest,
+    FreeTextExtensionGetRequest,
+    FreeTextExtensionPostRequest,
+)
+
+
+class FreeTextConformanceClasses(str, Enum):
+    """Conformance classes for the Free-Text extension.
+
+    See https://github.com/stac-api-extensions/freetext-search
+
+    """
+
+    # https://github.com/stac-api-extensions/freetext-search?tab=readme-ov-file#basic
+    SEARCH = "https://api.stacspec.org/v1.0.0-rc.1/item-search#free-text"
+    COLLECTIONS = "https://api.stacspec.org/v1.0.0-rc.1/collection-search#free-text"
+    ITEMS = "https://api.stacspec.org/v1.0.0-rc.1/ogcapi-features#free-text"
+
+    # https://github.com/stac-api-extensions/freetext-search?tab=readme-ov-file#advanced
+    SEARCH_ADVANCED = (
+        "https://api.stacspec.org/v1.0.0-rc.1/item-search#advanced-free-text"
+    )
+    COLLECTIONS_ADVANCED = (
+        "https://api.stacspec.org/v1.0.0-rc.1/collection-search#advanced-free-text"
+    )
+    ITEMS_ADVANCED = (
+        "https://api.stacspec.org/v1.0.0-rc.1/ogcapi-features#advanced-free-text"
+    )
+
+
+@attr.s
+class FreeTextExtension(ApiExtension):
+    """Free-text Extension.
+
+    The Free-text extension adds an additional `q` parameter to `/search` requests which
+    allows the caller to perform free-text queries against STAC metadata.
+
+    https://github.com/stac-api-extensions/freetext-search?tab=readme-ov-file#basic
+
+    """
+
+    GET = FreeTextExtensionGetRequest
+    POST = FreeTextExtensionPostRequest
+
+    conformance_classes: List[str] = attr.ib(
+        default=[
+            FreeTextConformanceClasses.SEARCH,
+            FreeTextConformanceClasses.COLLECTIONS,
+            FreeTextConformanceClasses.ITEMS,
+        ]
+    )
+    schema_href: Optional[str] = attr.ib(default=None)
+
+    def register(self, app: FastAPI) -> None:
+        """Register the extension with a FastAPI application.
+
+        Args:
+            app: target FastAPI application.
+
+        Returns:
+            None
+        """
+        pass
+
+
+@attr.s
+class FreeTextAdvancedExtension(ApiExtension):
+    """Free-text Extension.
+
+    The Free-text extension adds an additional `q` parameter to `/search` requests which
+    allows the caller to perform free-text queries against STAC metadata.
+
+    https://github.com/stac-api-extensions/freetext-search?tab=readme-ov-file#advanced
+
+    """
+
+    GET = FreeTextAdvancedExtensionGetRequest
+    POST = FreeTextAdvancedExtensionPostRequest
+
+    conformance_classes: List[str] = attr.ib(
+        default=[
+            FreeTextConformanceClasses.SEARCH_ADVANCED,
+            FreeTextConformanceClasses.COLLECTIONS_ADVANCED,
+            FreeTextConformanceClasses.ITEMS_ADVANCED,
+        ]
+    )
+    schema_href: Optional[str] = attr.ib(default=None)
+
+    def register(self, app: FastAPI) -> None:
+        """Register the extension with a FastAPI application.
+
+        Args:
+            app: target FastAPI application.
+
+        Returns:
+            None
+        """
+        pass

stac_fastapi/extensions/stac_fastapi/extensions/core/free_text/request.py

@@ -0,0 +1,64 @@
+"""Request model for the Free-text extension."""
+
+from typing import List, Optional
+
+import attr
+from fastapi import Query
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated
+
+from stac_fastapi.types.search import APIRequest, str2list
+
+
+def _ft_converter(
+    val: Annotated[
+        Optional[str],
+        Query(
+            description="Parameter to perform free-text queries against STAC metadata",
+            json_schema_extra={
+                "example": "ocean,coast",
+            },
+        ),
+    ] = None,
+) -> Optional[List[str]]:
+    return str2list(val)
+
+
+@attr.s
+class FreeTextExtensionGetRequest(APIRequest):
+    """Free-text Extension GET request model."""
+
+    q: Optional[List[str]] = attr.ib(default=None, converter=_ft_converter)
+
+
+class FreeTextExtensionPostRequest(BaseModel):
+    """Free-text Extension POST request model."""
+
+    q: Optional[List[str]] = Field(
+        None,
+        description="Parameter to perform free-text queries against STAC metadata",
+    )
+
+
+@attr.s
+class FreeTextAdvancedExtensionGetRequest(APIRequest):
+    """Free-text Extension GET request model."""
+
+    q: Annotated[
+        Optional[str],
+        Query(
+            description="Parameter to perform free-text queries against STAC metadata",
+            json_schema_extra={
+                "example": "ocean,coast",
+            },
+        ),
+    ] = attr.ib(default=None)
+
+
+class FreeTextAdvancedExtensionPostRequest(BaseModel):
+    """Free-text Extension POST request model."""
+
+    q: Optional[str] = Field(
+        None,
+        description="Parameter to perform free-text queries against STAC metadata",
+    )