Merge branch 'main' of github.com:stac-utils/stac-fastapi into patch_endpoints

Author: rhysrevans3

.github/workflows/cicd.yaml

@@ -55,7 +55,7 @@ jobs:
 
   benchmark:
     needs: [test]
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
     steps:
       - name: Check out repository code
         uses: actions/checkout@v4

.github/workflows/deploy_mkdocs.yml

@@ -33,13 +33,5 @@ jobs:
             stac_fastapi/api[docs] \
             stac_fastapi/extensions[docs] \
 
-      - name: update API docs
-        run: |
-          pdocs as_markdown \
-            --output_dir docs/src/api/ \
-            --exclude_source \
-            --overwrite \
-            stac_fastapi
-
       - name: Deploy docs
         run: mkdocs gh-deploy --force -f docs/mkdocs.yml

CHANGES.md

@@ -4,6 +4,18 @@
 
 * Add Item and Collection `PATCH` endpoints with support for [RFC 6902](https://tools.ietf.org/html/rfc6902) and [RFC 7396](https://tools.ietf.org/html/rfc7386)
 
+## [5.2.0] - 2025-04-18
+
+### Fixed
+
+- Remove defaults in OpenAPI schemas
+- Type Hints for TypedDict
+
+### Added
+
+- add `enable_direct_response` settings to by-pass Pydantic validation and FastAPI serialization for responses
+- add `/_mgmt/health` endpoint (`readiness`) and `health_check: Callable[[], [Dict]` optional attribute in `StacApi` class
+
 ## [5.1.1] - 2025-03-17
 
 ### Fixed
@@ -370,7 +382,7 @@ Full changelog: https://stac-utils.github.io/stac-fastapi/migrations/v3.0.0/#cha
 ### Added
 
 * Nginx service as second docker-compose stack to demonstrate proxy ([#503](https://github.com/stac-utils/stac-fastapi/pull/503))
-* Validation checks in CI using [stac-api-validator](github.com/stac-utils/stac-api-validator) ([#508](https://github.com/stac-utils/stac-fastapi/pull/508))
+* Validation checks in CI using [stac-api-validator](https://github.com/stac-utils/stac-api-validator) ([#508](https://github.com/stac-utils/stac-fastapi/pull/508))
 * Required links to the sqlalchemy ItemCollection endpoint ([#508](https://github.com/stac-utils/stac-fastapi/pull/508))
 * Publication of docker images to GHCR ([#525](https://github.com/stac-utils/stac-fastapi/pull/525))
 
@@ -604,7 +616,8 @@ Full changelog: https://stac-utils.github.io/stac-fastapi/migrations/v3.0.0/#cha
 
 * First PyPi release!
 
-[Unreleased]: <https://github.com/stac-utils/stac-fastapi/compare/5.1.1..main>
+[Unreleased]: <https://github.com/stac-utils/stac-fastapi/compare/5.2.0..main>
+[5.2.0]: <https://github.com/stac-utils/stac-fastapi/compare/5.1.1..5.2.0>
 [5.1.1]: <https://github.com/stac-utils/stac-fastapi/compare/5.1.0..5.1.1>
 [5.1.0]: <https://github.com/stac-utils/stac-fastapi/compare/5.0.3..5.1.0>
 [5.0.3]: <https://github.com/stac-utils/stac-fastapi/compare/5.0.2..5.0.3>

CONTRIBUTING.md

@@ -36,13 +36,6 @@ To manually deploy docs (note you should never need to do this because GitHub
 Actions deploys automatically for new commits.):
 
 ```bash
-Create API documentations
-$ pdocs as_markdown \
-  --output_dir docs/src/api/ \
-  --exclude_source \
-  --overwrite \
-  stac_fastapi
-
 # deploy
 $ mkdocs gh-deploy -f docs/mkdocs.yml
 ```

Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.11-slim as base
+FROM python:3.12-slim AS base
 
 # Any python libraries that require system libraries to be installed will likely
 # need the following packages in order to build
@@ -10,12 +10,13 @@ RUN apt-get update && \
 
 ENV CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
 
-FROM base as builder
+FROM base AS builder
 
 WORKDIR /app
 
 COPY . /app
 
-RUN python -m pip install -e ./stac_fastapi/types[dev] && \
-    python -m pip install -e ./stac_fastapi/api[dev] && \
-    python -m pip install -e ./stac_fastapi/extensions[dev]
+RUN python -m pip install \
+    -e ./stac_fastapi/types[dev] \
+    -e ./stac_fastapi/api[dev] \
+    -e ./stac_fastapi/extensions[dev]

Dockerfile.docs

@@ -1,24 +1,19 @@
-FROM python:3.11-slim
+FROM python:3.12-slim
 
 # build-essential is required to build a wheel for ciso8601
-RUN apt update && apt install -y build-essential
+RUN apt update && apt install -y build-essential && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
 
 RUN python -m pip install --upgrade pip
-RUN python -m pip install mkdocs mkdocs-material pdocs
 
 COPY . /opt/src
 
 WORKDIR /opt/src
 
 RUN python -m pip install \
-    stac_fastapi/types \
-    stac_fastapi/api \
-    stac_fastapi/extensions
+    "stac_fastapi/types[docs]" \
+    "stac_fastapi/api[docs]" \
+    "stac_fastapi/extensions[docs]"
 
-CMD ["pdocs", \
-    "as_markdown", \
-    "--output_dir", \
-    "docs/api/", \
-    "--exclude_source", \
-    "--overwrite", \
-    "stac_fastapi"]
+CMD ["mkdocs", "build", "-f", "docs/mkdocs.yml"]

Makefile

@@ -11,12 +11,12 @@ install:
 
 .PHONY: docs-image
 docs-image:
-	docker compose -f docker-compose.docs.yml \
+	docker compose -f compose.docs.yml \
 		build
 
 .PHONY: docs
 docs: docs-image
-	docker compose -f docker-compose.docs.yml \
+	docker compose -f compose.docs.yml \
 		run docs
 
 .PHONY: test

README.md

@@ -1,7 +1,7 @@
 <!-- markdownlint-disable MD033 MD041 -->
 
 <p align="center">
-  <img src="https://github.com/radiantearth/stac-site/raw/master/images/logo/stac-030-long.png" width=400>
+  <img src="https://github.com/radiantearth/stac-site/raw/master/images/logo/stac-030-long.png" width=400 alt="SpatioTemporal Asset Catalog (STAC) logo">
   <p align="center">FastAPI implemention of the STAC API spec.</p>
 </p>
 <p align="center">
@@ -21,25 +21,35 @@
 
 ---
 
-Python library for building a STAC compliant FastAPI application.  The project is split up into several namespace
-packages:
+Python library for building a STAC-compliant FastAPI application.  
 
-| Package |  Description | Version
-| ------- |------------- | -------
-[**stac_fastapi.api**](https://github.com/stac-utils/stac-fastapi/tree/main/stac_fastapi/api) | An API layer which enforces the [stac-api-spec](https://github.com/radiantearth/stac-api-spec). | [![stac-fastapi.api](https://img.shields.io/pypi/v/stac-fastapi.api?color=%2334D058&label=pypi)](https://pypi.org/project/stac-fastapi.api)
-[**stac_fastapi.extensions**](https://github.com/stac-utils/stac-fastapi/tree/main/stac_fastapi/extensions) | Abstract base classes for [STAC API extensions](https://github.com/radiantearth/stac-api-spec/blob/master/extensions.md) and third-party extensions. | [![stac-fastapi.extensions](https://img.shields.io/pypi/v/stac-fastapi.extensions?color=%2334D058&label=pypi)](https://pypi.org/project/stac-fastapi.extensions)
-[**stac_fastapi.types**](https://github.com/stac-utils/stac-fastapi/tree/main/stac_fastapi/types) | Shared types and abstract base classes used by the library. | [![stac-fastapi.types](https://img.shields.io/pypi/v/stac-fastapi.types?color=%2334D058&label=pypi)](https://pypi.org/project/stac-fastapi.types)
+`stac-fastapi` was initially developed by [arturo-ai](https://github.com/arturo-ai).
+
+The project contains several namespace packages:
+
+| Package |  Description | Version |
+| ------- |------------- | ------- |
+| [**stac_fastapi.api**](https://github.com/stac-utils/stac-fastapi/tree/main/stac_fastapi/api) | An API layer which enforces the [stac-api-spec](https://github.com/radiantearth/stac-api-spec). | [![stac-fastapi.api](https://img.shields.io/pypi/v/stac-fastapi.api?color=%2334D058&label=pypi)](https://pypi.org/project/stac-fastapi.api) |
+| [**stac_fastapi.extensions**](https://github.com/stac-utils/stac-fastapi/tree/main/stac_fastapi/extensions) | Abstract base classes for [STAC API extensions](https://github.com/radiantearth/stac-api-spec/blob/master/extensions.md) and third-party extensions. | [![stac-fastapi.extensions](https://img.shields.io/pypi/v/stac-fastapi.extensions?color=%2334D058&label=pypi)](https://pypi.org/project/stac-fastapi.extensions) |
+| [**stac_fastapi.types**](https://github.com/stac-utils/stac-fastapi/tree/main/stac_fastapi/types) | Shared types and abstract base classes used by the library. | [![stac-fastapi.types](https://img.shields.io/pypi/v/stac-fastapi.types?color=%2334D058&label=pypi)](https://pypi.org/project/stac-fastapi.types) |
 
 #### Backends
 
-Backends are hosted in their own repositories:
+In addition to the packages in this repository, a server implemention will also require the selection of a backend to
+connect with a database for STAC metadata storage. There are several different backend options, and each has their own
+repository.
 
-- [stac-fastapi-pgstac](https://github.com/stac-utils/stac-fastapi-pgstac): Postgres backend implementation with [PgSTAC](https://github.com/stac-utils/pgstac).
-- [stac-fastapi-elasticsearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch): Backend implementation with [Elasticsearch](https://github.com/elastic/elasticsearch).
-- [stac-fastapi-sqlalchemy](https://github.com/stac-utils/stac-fastapi-sqlalchemy): Postgres backend implementation with [sqlalchemy](https://www.sqlalchemy.org/).
+The two most widely-used and supported backends are:
 
-`stac-fastapi` was initially developed by [arturo-ai](https://github.com/arturo-ai).
+- [stac-fastapi-pgstac](https://github.com/stac-utils/stac-fastapi-pgstac): [PostgreSQL](https://github.com/postgres/postgres) + [PostGIS](https://github.com/postgis/postgis) via [PgSTAC](https://github.com/stac-utils/pgstac).
+- [stac-fastapi-elasticsearch-opensearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch): [Elasticsearch](https://github.com/elastic/elasticsearch) or [OpenSearch](https://github.com/opensearch-project/OpenSearch)
 
+Other implementations include:
+
+- [stac-fastapi-mongo](https://github.com/Healy-Hyperspatial/stac-fastapi-mongo): [MongoDB](https://github.com/mongodb/mongo)
+- [stac-fastapi-geoparquet)](https://github.com/stac-utils/stac-fastapi-geoparquet): [GeoParquet](https://geoparquet.org) via [stacrs](https://github.com/stac-utils/stacrs) (experimental)
+- [stac-fastapi-duckdb](https://github.com/Healy-Hyperspatial/stac-fastapi-duckdb): [DuckDB](https://github.com/duckdb/duckdb) (experimental)
+- [stac-fastapi-sqlalchemy](https://github.com/stac-utils/stac-fastapi-sqlalchemy): [PostgreSQL](https://github.com/postgres/postgres) + [PostGIS](https://github.com/postgis/postgis) via [SQLAlchemy](https://www.sqlalchemy.org/) (abandoned in favor of stac-fastapi-pgstac)
 
 ## Response Model Validation
 
@@ -51,16 +61,13 @@ To turn on response validation, set `ENABLE_RESPONSE_MODELS` to `True`. Either a
 
 With the introduction of Pydantic 2, the extra [time it takes to validate models became negatable](https://github.com/stac-utils/stac-fastapi/pull/625#issuecomment-2045824578). While `ENABLE_RESPONSE_MODELS` still defaults to `False` there should be no penalty for users to turn on this feature but users discretion is advised.
 
-
 ## Installation
 
 ```bash
 # Install from PyPI
 python -m pip install stac-fastapi.types stac-fastapi.api stac-fastapi.extensions
 
 # Install a backend of your choice
-python -m pip install stac-fastapi.sqlalchemy
-# or
 python -m pip install stac-fastapi.pgstac
 ```
 
@@ -71,14 +78,18 @@ Other backends may be available from other sources, search [PyPI](https://pypi.o
 Install the packages in editable mode:
 
 ```shell
-python -m pip install -e \
-  'stac_fastapi/types[dev]' \
-  'stac_fastapi/api[dev]' \
-  'stac_fastapi/extensions[dev]'
+python -m pip install \
+  -e 'stac_fastapi/types[dev]' \
+  -e 'stac_fastapi/api[dev]' \
+  -e 'stac_fastapi/extensions[dev]'
 ```
 
 To run the tests:
 
 ```shell
 python -m pytest
 ```
+
+## Releasing
+
+See [RELEASING.md](./RELEASING.md).

VERSION

@@ -1 +1 @@
-5.1.1
+5.2.0

compose.docs.yml

@@ -0,0 +1,9 @@
+services:
+  docs:
+    container_name: stac-fastapi-docs-dev
+    build:
+      context: .
+      dockerfile: Dockerfile.docs
+    platform: linux/amd64
+    volumes:
+      - .:/opt/src

docker-compose.docs.yml

@@ -30,24 +30,39 @@ nav:
           - models: api/stac_fastapi/api/models.md
           - openapi: api/stac_fastapi/api/openapi.md
           - routes: api/stac_fastapi/api/routes.md
-          - version: api/stac_fastapi/api/version.md
       - stac_fastapi.extensions:
           - module: api/stac_fastapi/extensions/index.md
           - 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
-                  - request: api/stac_fastapi/extensions/core/filter/request.md
+              - aggregation:
+                - module: api/stac_fastapi/extensions/core/aggregation/index.md
+                - aggregation: api/stac_fastapi/extensions/core/aggregation/aggregation.md
+                - client: api/stac_fastapi/extensions/core/aggregation/client.md
+                - request: api/stac_fastapi/extensions/core/aggregation/request.md
+                - types: api/stac_fastapi/extensions/core/aggregation/types.md
+              - collection_search:
+                - module: api/stac_fastapi/extensions/core/collection_search/index.md
+                - collection_search: api/stac_fastapi/extensions/core/collection_search/collection_search.md
+                - client: api/stac_fastapi/extensions/core/collection_search/client.md
+                - request: api/stac_fastapi/extensions/core/collection_search/request.md
               - fields:
                   - module: api/stac_fastapi/extensions/core/fields/index.md
                   - fields: api/stac_fastapi/extensions/core/fields/fields.md
                   - request: api/stac_fastapi/extensions/core/fields/request.md
+              - filter:
+                  - module: api/stac_fastapi/extensions/core/filter/index.md
+                  - filter: api/stac_fastapi/extensions/core/filter/filter.md
+                  - request: api/stac_fastapi/extensions/core/filter/request.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
+              - pagination:
+                  - module: api/stac_fastapi/extensions/core/pagination/index.md
+                  - pagination: api/stac_fastapi/extensions/core/pagination/pagination.md
+                  - offset_pagination: api/stac_fastapi/extensions/core/pagination/offset_pagination.md
+                  - token_pagination: api/stac_fastapi/extensions/core/pagination/token_pagination.md
+                  - request: api/stac_fastapi/extensions/core/pagination/request.md
               - query:
                   - module: api/stac_fastapi/extensions/core/query/index.md
                   - query: api/stac_fastapi/extensions/core/query/query.md
@@ -57,14 +72,9 @@ nav:
                   - request: api/stac_fastapi/extensions/core/sort/request.md
                   - sort: api/stac_fastapi/extensions/core/sort/sort.md
               - transaction: api/stac_fastapi/extensions/core/transaction.md
-              - pagination:
-                  - module: api/stac_fastapi/extensions/core/pagination/index.md
-                  - pagination: api/stac_fastapi/extensions/core/pagination/pagination.md
-                  - token_pagination: api/stac_fastapi/extensions/core/pagination/token_pagination.md
-              - version: api/stac_fastapi/extensions/version.md
           - third_party:
+              - module: api/stac_fastapi/extensions/third_party/index.md
               - bulk_transactions: api/stac_fastapi/extensions/third_party/bulk_transactions.md
-              - index: api/stac_fastapi/extensions/third_party/index.md
       - stac_fastapi.types:
           - module: api/stac_fastapi/types/index.md
           - config: api/stac_fastapi/types/config.md
@@ -77,7 +87,6 @@ nav:
           - rfc3339: api/stac_fastapi/types/rfc3339.md
           - search: api/stac_fastapi/types/search.md
           - stac: api/stac_fastapi/types/stac.md
-          - version: api/stac_fastapi/types/version.md
   - Migration Guides:
     - v2.5 -> v3.0: migrations/v3.0.0.md
     - v3.0 -> v4.0: migrations/v4.0.0.md
@@ -87,6 +96,29 @@ nav:
 
 plugins:
   - search
+  - mkdocstrings:
+      enable_inventory: true
+      handlers:
+        python:
+          paths: [src]
+          options:
+            docstring_section_style: list
+            docstring_style: google
+            line_length: 100
+            separate_signature: true
+            show_root_heading: true
+            show_signature_annotations: true
+            show_source: false
+            show_symbol_type_toc: true
+            signature_crossrefs: true
+            extensions:
+              - griffe_inherited_docstrings
+          inventories:
+            - https://docs.python.org/3/objects.inv
+            - https://docs.pydantic.dev/latest/objects.inv
+            - https://fastapi.tiangolo.com/objects.inv
+            - https://www.starlette.io/objects.inv
+            - https://www.attrs.org/en/stable/objects.inv
 
 # Theme
 theme:

docs/mkdocs.yml

@@ -0,0 +1,3 @@
+::: stac_fastapi.api.app
+    options:
+      show_source: true

docs/src/api/stac_fastapi/api/app.md

@@ -0,0 +1,3 @@
+::: stac_fastapi.api.config
+    options:
+      show_source: true

docs/src/api/stac_fastapi/api/config.md

@@ -0,0 +1,3 @@
+::: stac_fastapi.api.errors
+    options:
+      show_source: true