feat: build out the root endpoint (#33)

- Closes #26

Author: gadomski

.env.local

@@ -0,0 +1,2 @@
+TISTAC_CATALOG_ID="tistac"
+TISTAC_CATALOG_DESCRIPTION="A lightweight STAC API server built on FastAPI"

.github/workflows/ci.yml

@@ -17,6 +17,8 @@ jobs:
         run: sudo apt-get install postgis
       - name: Install
         run: scripts/install --dev
+      - name: Copy env file
+        run: cp .env.local .env
       - name: Lint
         run: scripts/lint
       - name: Test

README.md

@@ -6,12 +6,13 @@ We're building a service to search [stac-geoparquet](https://github.com/stac-uti
 
 ## Usage
 
-Get [uv](https://docs.astral.sh/uv/getting-started/installation/)
+Get [uv](https://docs.astral.sh/uv/getting-started/installation/), then:
 
 ```shell
 git clone [email protected]:developmentseed/labs-375-stac-geoparquet-backend.git
 cd labs-375-stac-geoparquet-backend
 scripts/install
+cp .env.local .env
 ```
 
 Then:

pyproject.toml

@@ -9,6 +9,7 @@ dependencies = [
     "pgstacrs>=0.1.0",
     "pydantic>=2.10.4",
     "pydantic-settings>=2.7.1",
+    "pystac>=1.11.0",
     "stacrs>=0.3.0",
 ]
 
@@ -17,7 +18,7 @@ dev = [
     "mypy>=1.14.1",
     "psycopg[pool]>=3.2.3",
     "pypgstac>=0.9.2",
-    "pystac>=1.11.0",
+    "pystac[validation]>=1.11.0",
     "pytest>=8.3.4",
     "pytest-asyncio>=0.25.1",
     "pytest-postgresql>=6.1.1",
@@ -27,6 +28,7 @@ dev = [
 [tool.mypy]
 strict = true
 files = ["**/*.py"]
+plugins = "pydantic.mypy"
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"

scripts/dev

@@ -2,4 +2,4 @@
 
 set -e
 
-TISTAC_BACKEND=data/naip.parquet uv run fastapi dev src/tistac/main.py
+uv run fastapi dev src/tistac/main.py

src/tistac/backends/__init__.py

@@ -1,12 +1,19 @@
 from abc import ABC, abstractmethod
 
-from tistac.models.item_collection import ItemCollection
-from tistac.models.search import Search
+from tistac.models import Collection, ItemCollection, Search
 
 
 class Backend(ABC):
     """A TiStac backend."""
 
+    @abstractmethod
+    async def get_collections(self) -> list[Collection]:
+        """Returns all collections in this backend."""
+
+    @abstractmethod
+    async def get_collection(self, collection_id: str) -> Collection | None:
+        """Returns a collection."""
+
     @abstractmethod
     async def search(self, search: Search) -> ItemCollection:
         """Searches this backend."""

src/tistac/backends/pgstac.py

@@ -3,8 +3,7 @@
 from pgstacrs import Client
 
 from tistac.backends import Backend
-from tistac.models.item_collection import ItemCollection
-from tistac.models.search import Search
+from tistac.models import Collection, ItemCollection, Search
 
 
 class PgstacBackend(Backend):
@@ -18,6 +17,17 @@ async def open(cls, dsn: str) -> PgstacBackend:
     def __init__(self, client: Client) -> None:
         self.client = client
 
+    async def get_collections(self) -> list[Collection]:
+        return [
+            Collection.model_validate(d) for d in await self.client.all_collections()
+        ]
+
+    async def get_collection(self, collection_id: str) -> Collection | None:
+        if d := await self.client.get_collection(collection_id):
+            return Collection.model_validate(d)
+        else:
+            return None
+
     async def search(self, search: Search) -> ItemCollection:
         item_collection = await self.client.search(limit=search.limit)
         return ItemCollection.model_validate(item_collection)

src/tistac/backends/stac_geoparquet.py

@@ -1,16 +1,47 @@
 import stacrs
+from pystac import Collection as PystacCollection
+from pystac import Extent, Item
 
 from tistac.backends import Backend
-from tistac.models.item_collection import ItemCollection
-from tistac.models.search import Search
+from tistac.models import Collection, ItemCollection, Search
 
 
 class StacGeoparquetBackend(Backend):
     """A stac-geoparquet backend, using DuckDB under the hood."""
 
     def __init__(self, href: str):
+        # TODO support multiple collections
+        # TODO store collection information in the **stac-geoparquet**
+        items_as_dicts = stacrs.search(href)
+        collection_ids = set()
+        items = list()
+        for item_as_dict in items_as_dicts:
+            item = Item.from_dict(item_as_dict)
+            if item.collection_id:
+                collection_ids.add(item.collection_id)
+            items.append(item)
+        if len(collection_ids) != 1:
+            raise Exception(
+                "Only one collection id is supported by the "
+                f"stac-geoparquet backend: {collection_ids}"
+            )
+        extent = Extent.from_items(items)
+        collection = PystacCollection(
+            id=collection_ids.pop(),
+            description="An auto-generated stac-geoparquet Collection",
+            extent=extent,
+        )
+        d = collection.to_dict(include_self_link=False, transform_hrefs=False)
+        d["stac_version"] = "1.1.0"
+        self.collections = [Collection.model_validate(d)]
         self.href = href
 
+    async def get_collections(self) -> list[Collection]:
+        return self.collections
+
+    async def get_collection(self, collection_id: str) -> Collection | None:
+        return next((c for c in self.collections if c.id == collection_id), None)
+
     async def search(self, search: Search) -> ItemCollection:
         items = stacrs.search(self.href, limit=search.limit)
         return ItemCollection(features=items)

src/tistac/dependencies.py

@@ -9,16 +9,30 @@
 from tistac.backends.stac_geoparquet import StacGeoparquetBackend
 from tistac.settings import Settings
 
+BACKEND: dict[str, Backend] = {}
+
 
 @lru_cache
 def get_settings() -> Settings:
-    return Settings()  # type: ignore
+    return Settings()
 
 
+# I really don't like how this works -- we might want to go back to leaning on
+# the starlette state, like stac-fastapi-pgstac does. It's just tricky to
+# configure settings w/o using the dependency overrides.
 async def get_backend(settings: Annotated[Settings, Depends(get_settings)]) -> Backend:
-    # TODO share the pgstac connection pool
+    global BACKEND
+
     url = urllib.parse.urlparse(settings.backend)
     if url.scheme == "postgresql":
-        return await PgstacBackend.open(settings.backend)
+        if "pgstac" in BACKEND:
+            return BACKEND["pgstac"]
+        else:
+            BACKEND["pgstac"] = await PgstacBackend.open(settings.backend)
+            return BACKEND["pgstac"]
     else:
-        return StacGeoparquetBackend(settings.backend)
+        if "stac-geoparquet" in BACKEND:
+            return BACKEND["stac-geoparquet"]
+        else:
+            BACKEND["stac-geoparquet"] = StacGeoparquetBackend(settings.backend)
+            return BACKEND["stac-geoparquet"]

src/tistac/main.py

@@ -1,6 +1,10 @@
+import importlib.metadata
+
 from fastapi import FastAPI
 
 import tistac.router
 
-app = FastAPI()
+app = FastAPI(
+    version=importlib.metadata.distribution("tistac").version,
+)
 app.include_router(tistac.router.router)