Skip to content

Commit fe4d0df

Browse files
rhysrevans3vincentsarago
rhysrevans3
and
vincentsarago
authored
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]>
1 parent c55c253 commit fe4d0df

File tree

8 files changed

+523
-0
lines changed

8 files changed

+523
-0
lines changed

‎CHANGES.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,14 @@
22

33
## [Unreleased] - TBD
44

5+
### Changed
6+
57
* add more openapi metadata in input models [#734](https://github.com/stac-utils/stac-fastapi/pull/734)
68

9+
### Added
10+
11+
* Add Free-text Extension to third party extensions ([#655](https://github.com/stac-utils/stac-fastapi/pull/655))
12+
713
## [3.0.0b2] - 2024-07-09
814

915
### Changed

‎docs/mkdocs.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,10 @@ nav:
3636
- core:
3737
- module: api/stac_fastapi/extensions/core/index.md
3838
- context: api/stac_fastapi/extensions/core/context.md
39+
- free_text:
40+
- module: api/stac_fastapi/extensions/core/free_text/index.md
41+
- free_text: api/stac_fastapi/extensions/core/free_text/free_text.md
42+
- request: api/stac_fastapi/extensions/core/free_text/request.md
3943
- filter:
4044
- module: api/stac_fastapi/extensions/core/filter/index.md
4145
- filter: api/stac_fastapi/extensions/core/filter/filter.md

‎stac_fastapi/api/stac_fastapi/api/config.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ class ApiExtensions(enum.Enum):
1919
sort = "sort"
2020
transaction = "transaction"
2121
aggregation = "aggregation"
22+
free_text = "free-text"
2223

2324

2425
class AddOns(enum.Enum):

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
from .context import ContextExtension
55
from .fields import FieldsExtension
66
from .filter import FilterExtension
7+
from .free_text import FreeTextAdvancedExtension, FreeTextExtension
78
from .pagination import PaginationExtension, TokenPaginationExtension
89
from .query import QueryExtension
910
from .sort import SortExtension
@@ -14,6 +15,8 @@
1415
"ContextExtension",
1516
"FieldsExtension",
1617
"FilterExtension",
18+
"FreeTextExtension",
19+
"FreeTextAdvancedExtension",
1720
"PaginationExtension",
1821
"QueryExtension",
1922
"SortExtension",

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
"""Query extension module."""
2+
3+
from .free_text import (
4+
FreeTextAdvancedExtension,
5+
FreeTextConformanceClasses,
6+
FreeTextExtension,
7+
)
8+
9+
__all__ = [
10+
"FreeTextExtension",
11+
"FreeTextAdvancedExtension",
12+
"FreeTextConformanceClasses",
13+
]

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

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
"""Free-text extension."""
2+
3+
from enum import Enum
4+
from typing import List, Optional
5+
6+
import attr
7+
from fastapi import FastAPI
8+
9+
from stac_fastapi.types.extension import ApiExtension
10+
11+
from .request import (
12+
FreeTextAdvancedExtensionGetRequest,
13+
FreeTextAdvancedExtensionPostRequest,
14+
FreeTextExtensionGetRequest,
15+
FreeTextExtensionPostRequest,
16+
)
17+
18+
19+
class FreeTextConformanceClasses(str, Enum):
20+
"""Conformance classes for the Free-Text extension.
21+
22+
See https://github.com/stac-api-extensions/freetext-search
23+
24+
"""
25+
26+
# https://github.com/stac-api-extensions/freetext-search?tab=readme-ov-file#basic
27+
SEARCH = "https://api.stacspec.org/v1.0.0-rc.1/item-search#free-text"
28+
COLLECTIONS = "https://api.stacspec.org/v1.0.0-rc.1/collection-search#free-text"
29+
ITEMS = "https://api.stacspec.org/v1.0.0-rc.1/ogcapi-features#free-text"
30+
31+
# https://github.com/stac-api-extensions/freetext-search?tab=readme-ov-file#advanced
32+
SEARCH_ADVANCED = (
33+
"https://api.stacspec.org/v1.0.0-rc.1/item-search#advanced-free-text"
34+
)
35+
COLLECTIONS_ADVANCED = (
36+
"https://api.stacspec.org/v1.0.0-rc.1/collection-search#advanced-free-text"
37+
)
38+
ITEMS_ADVANCED = (
39+
"https://api.stacspec.org/v1.0.0-rc.1/ogcapi-features#advanced-free-text"
40+
)
41+
42+
43+
@attr.s
44+
class FreeTextExtension(ApiExtension):
45+
"""Free-text Extension.
46+
47+
The Free-text extension adds an additional `q` parameter to `/search` requests which
48+
allows the caller to perform free-text queries against STAC metadata.
49+
50+
https://github.com/stac-api-extensions/freetext-search?tab=readme-ov-file#basic
51+
52+
"""
53+
54+
GET = FreeTextExtensionGetRequest
55+
POST = FreeTextExtensionPostRequest
56+
57+
conformance_classes: List[str] = attr.ib(
58+
default=[
59+
FreeTextConformanceClasses.SEARCH,
60+
FreeTextConformanceClasses.COLLECTIONS,
61+
FreeTextConformanceClasses.ITEMS,
62+
]
63+
)
64+
schema_href: Optional[str] = attr.ib(default=None)
65+
66+
def register(self, app: FastAPI) -> None:
67+
"""Register the extension with a FastAPI application.
68+
69+
Args:
70+
app: target FastAPI application.
71+
72+
Returns:
73+
None
74+
"""
75+
pass
76+
77+
78+
@attr.s
79+
class FreeTextAdvancedExtension(ApiExtension):
80+
"""Free-text Extension.
81+
82+
The Free-text extension adds an additional `q` parameter to `/search` requests which
83+
allows the caller to perform free-text queries against STAC metadata.
84+
85+
https://github.com/stac-api-extensions/freetext-search?tab=readme-ov-file#advanced
86+
87+
"""
88+
89+
GET = FreeTextAdvancedExtensionGetRequest
90+
POST = FreeTextAdvancedExtensionPostRequest
91+
92+
conformance_classes: List[str] = attr.ib(
93+
default=[
94+
FreeTextConformanceClasses.SEARCH_ADVANCED,
95+
FreeTextConformanceClasses.COLLECTIONS_ADVANCED,
96+
FreeTextConformanceClasses.ITEMS_ADVANCED,
97+
]
98+
)
99+
schema_href: Optional[str] = attr.ib(default=None)
100+
101+
def register(self, app: FastAPI) -> None:
102+
"""Register the extension with a FastAPI application.
103+
104+
Args:
105+
app: target FastAPI application.
106+
107+
Returns:
108+
None
109+
"""
110+
pass

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

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
"""Request model for the Free-text extension."""
2+
3+
from typing import List, Optional
4+
5+
import attr
6+
from fastapi import Query
7+
from pydantic import BaseModel, Field
8+
from typing_extensions import Annotated
9+
10+
from stac_fastapi.types.search import APIRequest, str2list
11+
12+
13+
def _ft_converter(
14+
val: Annotated[
15+
Optional[str],
16+
Query(
17+
description="Parameter to perform free-text queries against STAC metadata",
18+
json_schema_extra={
19+
"example": "ocean,coast",
20+
},
21+
),
22+
] = None,
23+
) -> Optional[List[str]]:
24+
return str2list(val)
25+
26+
27+
@attr.s
28+
class FreeTextExtensionGetRequest(APIRequest):
29+
"""Free-text Extension GET request model."""
30+
31+
q: Optional[List[str]] = attr.ib(default=None, converter=_ft_converter)
32+
33+
34+
class FreeTextExtensionPostRequest(BaseModel):
35+
"""Free-text Extension POST request model."""
36+
37+
q: Optional[List[str]] = Field(
38+
None,
39+
description="Parameter to perform free-text queries against STAC metadata",
40+
)
41+
42+
43+
@attr.s
44+
class FreeTextAdvancedExtensionGetRequest(APIRequest):
45+
"""Free-text Extension GET request model."""
46+
47+
q: Annotated[
48+
Optional[str],
49+
Query(
50+
description="Parameter to perform free-text queries against STAC metadata",
51+
json_schema_extra={
52+
"example": "ocean,coast",
53+
},
54+
),
55+
] = attr.ib(default=None)
56+
57+
58+
class FreeTextAdvancedExtensionPostRequest(BaseModel):
59+
"""Free-text Extension POST request model."""
60+
61+
q: Optional[str] = Field(
62+
None,
63+
description="Parameter to perform free-text queries against STAC metadata",
64+
)

0 commit comments

Comments
 (0)