Add terrascope module for Terrascope STAC API integration by giswqs · Pull Request #1294 · opengeos/leafmap

giswqs · 2026-02-08T06:06:55Z

Summary

Adds a new leafmap.terrascope module for seamless integration with the Terrascope STAC API.

Features

OAuth2 authentication with automatic token refresh (background thread)
Token caching to ~/.terrascope_tokens.json for persistence across sessions
STAC search helpers: search(), search_ndvi(), list_collections()
Visualization helpers: create_time_layers() for time slider
Utility functions: cleanup_tile_servers(), get_asset_urls(), get_item_dates()

Usage

import leafmap
import leafmap.terrascope as terrascope

# Authenticate (uses TERRASCOPE_USERNAME/PASSWORD env vars)
terrascope.login()

# Search for NDVI data
items = terrascope.search_ndvi(
    bbox=[5.0, 51.2, 5.1, 51.3],
    start="2025-05-01",
    end="2025-06-01",
    max_cloud_cover=10,
)

# Visualize
m = leafmap.Map()
m.add_raster(items[0].assets["NDVI"].href, colormap="RdYlGn")

Files Added

leafmap/terrascope.py - Main module
docs/notebooks/115_terrascope.ipynb - Example notebook
docs/terrascope.md - API documentation

Reference

- Add leafmap/terrascope.py with OAuth2 auth, token caching, and STAC search - Add docs/notebooks/115_terrascope.ipynb example notebook - Add API documentation - Update mkdocs.yml

for more information, see https://pre-commit.ci

leafmap/terrascope.py

Copilot

Pull request overview

Adds a new leafmap.terrascope module to integrate with the Terrascope STAC API, including OAuth2 token management, STAC search helpers, and visualization utilities, along with documentation and an example notebook.

Changes:

Added leafmap.terrascope with OAuth2 login/token caching/refresh and STAC helper utilities.
Added API docs page and a new example notebook demonstrating authentication, search, and visualization.
Updated MkDocs navigation to include the new module docs and notebook.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 10 comments.

File	Description
`mkdocs.yml`	Adds the Terrascope module doc page and notebook to the site navigation.
`leafmap/terrascope.py`	Implements Terrascope auth/token handling, STAC search helpers, and visualization utilities.
`docs/terrascope.md`	Adds mkdocstrings-based API reference page for `leafmap.terrascope`.
`docs/notebooks/115_terrascope.ipynb`	Provides an end-to-end usage example (login, search, map viz, basic analysis).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-08T06:12:16Z

leafmap/terrascope.py

+
+
+def _background_refresher() -> None:
+    """Background thread that refreshes token periodically."""
+    while not _refresh_stop.wait(REFRESH_INTERVAL):


The background refresh thread calls get_token() while other code can also call get_token()/logout(), but _token_cache and the token/header files are mutated without any synchronization. This can lead to races (e.g., logout() deleting files while the refresher rewrites them). Add a threading.Lock (or similar) around token cache + file read/write operations, and coordinate shutdown with the refresher.

Copilot · 2026-02-08T06:12:16Z

leafmap/terrascope.py

+    """Get new tokens using password grant."""
+    _check_dependencies()
+    response = requests.post(
+        TOKEN_URL,
+        data={


Token requests use requests.post(...) without a timeout. If the network hangs, login()/get_token() can block indefinitely. Please provide a reasonable timeout (and consider surfacing a clearer error on timeout).

Copilot · 2026-02-08T06:12:16Z

leafmap/terrascope.py

+    """Get new access token using refresh token."""
+    _check_dependencies()
+    response = requests.post(
+        TOKEN_URL,
+        data={


Token refresh requests use requests.post(...) without a timeout, which can block the refresh thread (and potentially get_token()) indefinitely on network hangs. Please add a timeout here as well.

Copilot · 2026-02-08T06:12:16Z

leafmap/terrascope.py

+    cached expired tokens.
+    """
+    try:
+        subprocess.run(["pkill", "-f", "localtileserver"], capture_output=True)


cleanup_tile_servers() runs pkill -f localtileserver, which will terminate any matching process on the machine (not just ones started by this session) and is OS-specific. Consider narrowing the kill criteria (e.g., track PIDs started by leafmap/localtileserver, or use psutil to filter by current user/parent) and returning a status so callers can tell whether anything was stopped.

Copilot · 2026-02-08T06:12:17Z

leafmap/terrascope.py

+    from pystac import ItemCollection
+except ImportError:
+    Client = None
+    ItemCollection = None


ItemCollection is imported but never used in this module, which will trigger a linter error (e.g., flake8 F401). Please remove the unused import (and the corresponding ItemCollection = None fallback) or start using it.

Suggested change

from pystac import ItemCollection

except ImportError:

Client = None

ItemCollection = None

except ImportError:

Client = None

Copilot · 2026-02-08T06:12:17Z

leafmap/terrascope.py

+    _update_header_file(token)
+


login() overwrites process-wide GDAL environment variables (GDAL_HTTP_HEADER_FILE, GDAL_DISABLE_READDIR_ON_OPEN) without preserving previous values. This can unexpectedly affect other raster/GDAL usage in the same process; consider saving the prior values and restoring them in logout() (or using a scoped context manager).

Copilot · 2026-02-08T06:12:17Z

leafmap/terrascope.py

+        os.remove(TOKEN_CACHE_PATH)
+    if os.path.exists(HEADER_FILE_PATH):
+        os.remove(HEADER_FILE_PATH)
+


logout() removes the header file but does not unset/restore GDAL_HTTP_HEADER_FILE (and GDAL_DISABLE_READDIR_ON_OPEN). After logout, GDAL may still try to read a non-existent header file, causing confusing failures elsewhere. Please unset or restore these environment variables when logging out.

Suggested change

# Unset GDAL environment variables configured in login()

os.environ.pop("GDAL_HTTP_HEADER_FILE", None)

os.environ.pop("GDAL_DISABLE_READDIR_ON_OPEN", None)

Copilot · 2026-02-08T06:12:17Z

leafmap/terrascope.py

+    while not _refresh_stop.wait(REFRESH_INTERVAL):
+        try:
+            token = get_token()
+            _update_header_file(token)
+        except Exception:


The background refresher suppresses all exceptions (except Exception: pass), which makes token refresh failures very hard to diagnose and can leave the GDAL header token stale. Consider logging the exception (at least at debug/warn level) and/or exposing the last refresh error to callers.

Copilot · 2026-02-08T06:12:17Z

leafmap/terrascope.py

+
+
+def get_token(
+    username: str | None = None,
+    password: str | None = None,
+) -> str:
+    """
+    Get a valid Terrascope access token.
+
+    Attempts to get a token in this order:


This new module introduces non-trivial auth/token caching + refresh behavior, but there are no unit tests covering it. Consider adding tests that mock requests.post and validate: cache read/write behavior, refresh vs password fallback logic, and that logout() cleans up state (thread stop + env vars).

Copilot · 2026-02-08T06:12:18Z

leafmap/terrascope.py

+    """
+    try:
+        subprocess.run(["pkill", "-f", "localtileserver"], capture_output=True)
+    except Exception:


'except' clause does nothing but pass and there is no explanatory comment.

Suggested change

except Exception:

except Exception:

# Ignore errors from pkill: this cleanup is best-effort and may fail

# if the command is unavailable or no matching processes are found.

github-actions · 2026-02-08T06:12:40Z

🚀 Deployed on https://69882daa18e0635e029bcf76--opengeos.netlify.app

- Add threading.Lock for token cache thread safety - Add REQUEST_TIMEOUT (30s) to all requests.post calls - Remove unused ItemCollection import - Add logging for background refresh errors - Unset GDAL env vars in logout() - Add explanatory comments for exception handling - Document OAuth2 password grant security in docstrings

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-08T06:23:38Z

leafmap/terrascope.py

+def get_token(
+    username: str | None = None,
+    password: str | None = None,
+) -> str:
+    """
+    Get a valid Terrascope access token.
+
+    Attempts to get a token in this order:
+    1. Return cached token if still valid
+    2. Refresh using refresh token if available
+    3. Login with username/password
+
+    Args:
+        username: Terrascope username. Defaults to TERRASCOPE_USERNAME env var.
+        password: Terrascope password. Defaults to TERRASCOPE_PASSWORD env var.
+
+    Returns:
+        Valid access token string.
+
+    Raises:
+        ValueError: If credentials are not provided and not in environment.
+        requests.HTTPError: If authentication fails.
+    """
+    global _token_cache
+    _check_dependencies()
+
+    with _token_lock:
+        if not _token_cache:
+            _load_cached_tokens()
+
+        now = time.time()
+
+        # Check if access token is still valid
+        if _token_cache.get("access_expires_at", 0) > now:
+            return _token_cache["access_token"]
+
+        # Try to refresh if refresh token is still valid
+        if _token_cache.get("refresh_expires_at", 0) > now:
+            try:
+                return _refresh_access_token(_token_cache["refresh_token"])
+            except Exception:
+                # Fall through to password auth
+                pass
+
+        # Need fresh login with credentials
+        username = username or os.environ.get("TERRASCOPE_USERNAME")
+        password = password or os.environ.get("TERRASCOPE_PASSWORD")
+        if not username or not password:
+            raise ValueError(
+                "Terrascope credentials required. Either pass username/password "
+                "or set TERRASCOPE_USERNAME and TERRASCOPE_PASSWORD environment "
+                "variables."
+            )
+        return _get_token_with_password(username, password)
+


This module introduces substantial new behavior (OAuth token caching/refresh, STAC search helpers). The repo has an existing test suite, but there are no tests added for these new functions. Add unit tests that cover token cache load/save behavior, refresh vs password flow selection, and search() query construction (e.g., datetime ranges and cloud-cover filtering) using mocked HTTP/STAC client responses.

Copilot · 2026-02-08T06:23:38Z

leafmap/terrascope.py

+        _refresh_thread.join(timeout=1)
+        _refresh_thread = None


logout() joins the refresh thread with timeout=1 and then unconditionally sets _refresh_thread=None. If the thread is in the middle of a network refresh (or otherwise takes >1s), it may still be running while tokens/header files are being deleted, causing races and confusing state. Consider joining without a timeout, or checking is_alive() and only clearing the reference once the thread has actually stopped (and/or increasing the timeout).

Suggested change

_refresh_thread.join(timeout=1)

_refresh_thread = None

# Give the refresh thread a chance to terminate cleanly.

_refresh_thread.join(timeout=5)

if _refresh_thread.is_alive():

logging.warning(

"Terrascope token refresh thread did not stop within the logout timeout."

)

else:

_refresh_thread = None

Copilot · 2026-02-08T06:23:38Z

leafmap/terrascope.py

+            with _token_lock:
+                token = get_token()


_background_refresher() acquires _token_lock and then calls get_token(), which also acquires _token_lock. This will deadlock the background refresh thread the first time it runs. Remove the outer lock and rely on get_token()'s internal locking, or refactor to fetch the token outside the lock and only lock around updating shared state/files.

Suggested change

with _token_lock:

token = get_token()

token = get_token()

with _token_lock:

Copilot · 2026-02-08T06:23:39Z

leafmap/terrascope.py

+    try:
+        import leafmap
+    except ImportError:
+        raise ImportError("leafmap is required: pip install leafmap")
+
+    layers = {}
+    for item in items:
+        if asset_key not in item.assets:
+            continue
+        date_str = item.datetime.strftime("%Y-%m-%d")
+        tile_layer = leafmap.get_local_tile_layer(
+            item.assets[asset_key].href,
+            layer_name=date_str,
+            colormap=colormap,
+            vmin=vmin,
+            vmax=vmax,
+        )


create_time_layers() calls leafmap.get_local_tile_layer(), but leafmap.init only re-exports get_local_tile_layer in some backends (e.g., ipyleaflet via leafmap/leafmap.py). In folium/mkdocs mode it isn’t exported, so this will raise AttributeError. Import and call get_local_tile_layer from leafmap.common (or use a relative import from .common) to make this backend-independent.

for more information, see https://pre-commit.ci

Add terrascope module for Terrascope STAC API integration

00c5e15

- Add leafmap/terrascope.py with OAuth2 auth, token caching, and STAC search - Add docs/notebooks/115_terrascope.ipynb example notebook - Add API documentation - Update mkdocs.yml

Copilot AI review requested due to automatic review settings February 8, 2026 06:06

[pre-commit.ci] auto fixes from pre-commit.com hooks

b656961

for more information, see https://pre-commit.ci

Copilot started reviewing on behalf of giswqs February 8, 2026 06:07 View session

github-advanced-security bot found potential problems Feb 8, 2026

View reviewed changes

leafmap/terrascope.py Dismissed Show dismissed Hide dismissed

Copilot AI reviewed Feb 8, 2026

View reviewed changes

github-actions bot temporarily deployed to pull request February 8, 2026 06:13 Inactive

giswqs added 2 commits February 8, 2026 01:14

Update notebook

fdc0cbd

giswqs requested a review from Copilot February 8, 2026 06:19

Copilot started reviewing on behalf of giswqs February 8, 2026 06:19 View session

Copilot AI reviewed Feb 8, 2026

View reviewed changes

github-actions bot temporarily deployed to pull request February 8, 2026 06:23 Inactive

giswqs and others added 2 commits February 8, 2026 01:24

Update notebook

8304ed7

[pre-commit.ci] auto fixes from pre-commit.com hooks

c2b9c52

for more information, see https://pre-commit.ci

giswqs merged commit 3e28dcd into master Feb 8, 2026
14 checks passed

giswqs deleted the add-terrascope-module branch February 8, 2026 06:26

github-actions bot temporarily deployed to pull request February 8, 2026 06:31 Inactive

+    # Unset GDAL environment variables configured in login()
+    os.environ.pop("GDAL_HTTP_HEADER_FILE", None)
+    os.environ.pop("GDAL_DISABLE_READDIR_ON_OPEN", None)

-        _refresh_thread.join(timeout=1)
-        _refresh_thread = None
+        # Give the refresh thread a chance to terminate cleanly.
+        _refresh_thread.join(timeout=5)
+        if _refresh_thread.is_alive():
+            logging.warning(
+                "Terrascope token refresh thread did not stop within the logout timeout."
+            )
+        else:
+            _refresh_thread = None

Uh oh!

Comments

Conversation

giswqs commented Feb 8, 2026

Summary

Features

Usage

Files Added

Reference

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Feb 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

github-actions bot commented Feb 8, 2026 •

edited

Loading