API Reference

This section contains the API reference for the FLUXNET Shuttle Library.

fluxnet_shuttle package

module:

fluxnet_shuttle

synopsis:

Main library package for FLUXNET Shuttle operations with plugin system

module author:

Gilberto Pastorello <gzpastorello@lbl.gov>

module author:

Dario Papale <darpap@unitus.it>

platform:

Unix, Windows

created:

2024-10-31

updated:

2025-12-09

FLUXNET Shuttle Library provides functionality for discovering and downloading FLUXNET data from multiple data hubs, including AmeriFlux and ICOS.

The library offers both synchronous and asynchronous Python APIs with a plugin-based architecture for extending to new FLUXNET data hubs.

Features

  • Plugin-based architecture for easy extensibility

  • Both sync and async APIs using decorators to reduce duplication

  • Error collection and isolation across plugins

  • Unified configuration system

  • Type-safe API with Pydantic models

  • Comprehensive logging and error handling

License See LICENSE file.

Submodules

core

Core framework components for FLUXNET Shuttle Library

models

Pydantic Schema Models for FLUXNET Shuttle Library

plugins

Data hub-specific plugins for FLUXNET Shuttle Library

shuttle

Core functionality for FLUXNET Shuttle operations

Overview

add_file_log(filename[, level, log_fmt, ...])

Setup root logger and handlers for log file and STDOUT

log_config([level, filename, ...])

Setup root logger and handlers for log file and STDOUT

log_trace(exception[, level, log, output_fmt])

Logs exception including stack traceback into log, formatting trace as single line

download([site_ids, snapshot_file, output_dir])

Download FLUXNET data for specified sites using configuration from a snapshot file.

listall([data_hubs, output_dir])

List all available FLUXNET data from specified data hubs.
exception fluxnet_shuttle.FLUXNETShuttleError[source]

Bases: Exception

Base error/exception class for FLUXNET Shuttle

fluxnet_shuttle.add_file_log(filename, level=10, log_fmt='%(asctime)s.%(msecs)03d [%(levelname)-8s] %(message)s [%(name)s]', log_datefmt='%Y-%m-%d %H:%M:%S')[source]

Setup root logger and handlers for log file and STDOUT

Parameters:

  • filename (str) – name of log file

  • level (int) – logging level (from logging library)

  • log_fmt (str) – log output formatting

  • log_datefmt (str) – log date-time output formatting

Return type:

logging.FileHandler

fluxnet_shuttle.download(site_ids=None, snapshot_file='', output_dir='.', **kwargs)[source]

Download FLUXNET data for specified sites using configuration from a snapshot file.

Downloads are performed concurrently.

Parameters:

  • site_ids (Optional[List[str]]) – List of site IDs to download data for. If None or empty, downloads all sites from snapshot file.

  • snapshot_file (str) – Path to CSV snapshot file containing site configuration

  • output_dir (str) – Directory to save downloaded files (default: current directory)

  • kwargs (Any) – Additional keyword arguments passed to _download_dataset. - user_info: Dictionary with plugin-specific user info (e.g., {“ameriflux”: {…}})

Returns:

List of downloaded filenames

Return type:

list

Raises:

FLUXNETShuttleError – If snapshot_file is invalid or sites not found

fluxnet_shuttle.listall(data_hubs=None, output_dir='.')[source]

List all available FLUXNET data from specified data hubs.

Parameters:

  • data_hubs (Optional[List[str]]) – List of data hub plugin names to include (e.g., [“ameriflux”, “icos”]). If None or empty, all available data hub plugins are included.

  • output_dir (str) – Directory to save the snapshot file (default: current directory)

Returns:

CSV filename containing data availability information

Return type:

str

fluxnet_shuttle.log_config(level=10, filename=None, filename_level=None, std=True, std_level=None, log_fmt='%(asctime)s.%(msecs)03d [%(levelname)-8s] %(message)s [%(name)s]', log_datefmt='%Y-%m-%d %H:%M:%S')[source]

Setup root logger and handlers for log file and STDOUT

Parameters:

  • level (int) – logging level (from logging library)

  • filename (str) – name of log file

  • filename_level (int) – logging level for file log (same as level if None)

  • std (boolean) – if True, sys.stderr will show log messages

  • std_level (int) – logging level for std log (same as level if None)

  • log_fmt (str) – log output formatting

  • log_datefmt (str) – log date-time output formatting

Return type:

None

fluxnet_shuttle.log_trace(exception, level=40, log=<Logger fluxnet_shuttle (WARNING)>, output_fmt='std')[source]

Logs exception including stack traceback into log, formatting trace as single line

Parameters:

  • exception (Exception) – exception object to be handled

  • level (int) – logging severity level

  • log (logging.Logger) – logger to use for logging trace

  • output_fmt (str) – output format: std (like Python traceback) or alt (‘;’-separated single line)

Return type:

str

>>> # N.B.: careful when catching Exception class,
>>> #       this can mask virtually any error in Python
>>> try:
>>>     raise Exception('Test exception')
>>> except Exception as e:
>>>     msg = log_trace(exception=e, level=logging.CRITICAL)
>>>     sys.exit(msg)
fluxnet_shuttle.main()[source]

Main CLI entry point.

Return type:

None