Skip to main content

ECOv003-exit-codes

Standardized integer exit codes and exception classes for ECOSTRESS Collection 3 Product Generation Executables (PGEs), developed at NASA's Jet Propulsion Laboratory (JPL).

Overview

In the ECOSTRESS Collection 3 Science Data System (SDS), Product Generation Executables—such as ECOv003-L2T-STARS and ECOv003-L3T-L4T-JET—run as standalone command-line processes orchestrated by a workflow scheduler.

ECOv003-exit-codes provides a lightweight, zero-dependency shared contract between PGEs and the SDS orchestrator by pairing integer OS exit codes (0–18) with a structured Python exception hierarchy rooted at ECOSTRESSExitCodeException. This allows the scheduler to distinguish normal completions, expected scientific/spatial filters (e.g., nighttime or ocean-only tiles), transient auxiliary data latency requiring a scheduled retry, and unrecoverable errors.

Author

Gregory H. Halverson
gregory.h.halverson@jpl.nasa.gov
NASA Jet Propulsion Laboratory, California Institute of Technology

Installation

Install from PyPI:

pip install ECOv003-exit-codes

Or install from a local clone for development:

pip install -e ".[dev]"

Requirements: Python $\ge$ 3.10 (no third-party runtime dependencies).

Usage

Raising Exit-Code Exceptions in PGE Modules

Raise the specific ECOSTRESSExitCodeException subclass corresponding to the failure or filter condition encountered:

from os.path import exists
from ECOv003_exit_codes import (
    InputFilesInaccessible,
    LandFilter,
    AuxiliaryLatency,
    BlankOutput,
)

def validate_inputs(l2t_lste_path: str, is_land: bool) -> None:
    if not exists(l2t_lste_path):
        raise InputFilesInaccessible(f"L2T_LSTE file not found: {l2t_lste_path}")

    if not is_land:
        raise LandFilter("Scene rejected: tile contains no land pixels")

Handling Exceptions at the PGE CLI Entry Point

Catch ECOSTRESSExitCodeException at the top level of your PGE entry point to map exceptions directly to their standardized integer return code:

import sys
import logging
from ECOv003_exit_codes import (
    SUCCESS_EXIT_CODE,
    UNCLASSIFIED_FAILURE_EXIT_CODE,
    RUNCONFIG_FILENAME_NOT_SUPPLIED,
    ECOSTRESSExitCodeException,
)

logger = logging.getLogger(__name__)

def run_pge(runconfig_filename: str) -> int:
    try:
        # Execute PGE workflow...
        return SUCCESS_EXIT_CODE
    except ECOSTRESSExitCodeException as exc:
        logger.error(f"PGE exited with code {exc.exit_code}: {exc}")
        return exc.exit_code
    except Exception as exc:
        logger.exception(f"Unhandled error: {exc}")
        return UNCLASSIFIED_FAILURE_EXIT_CODE

def main(argv: list[str] | None = None) -> int:
    args = sys.argv[1:] if argv is None else argv
    if not args:
        return RUNCONFIG_FILENAME_NOT_SUPPLIED
    return run_pge(args[0])

if __name__ == "__main__":
    sys.exit(main())

Exit Codes & Exceptions Reference

All custom exceptions inherit from ECOSTRESSExitCodeException (which defines .exit_code = 1 by default) and expose their corresponding integer exit code via the class attribute ExceptionClass.exit_code.

Exit Code Constant Name Exception Class Description / Trigger Condition
0 SUCCESS_EXIT_CODE (None) PGE execution completed successfully.
1 UNCLASSIFIED_FAILURE_EXIT_CODE ECOSTRESSExitCodeException Base exception class and fallback for unclassified failures.
2 RUNCONFIG_FILENAME_NOT_SUPPLIED RunConfigFilenameNotSupplied Run-config filename argument was not supplied in the PGE call.
3 UNABLE_TO_OPEN_RUNCONFIG_FILE UnableToOpenRunConfig Run-config file does not exist or cannot be opened.
4 UNABLE_TO_PARSE_RUNCONFIG_FILE UnableToParseRunConfig Run-config XML file could not be parsed.
5 CORRUPTED_RUNCONFIG_STRUCTURE CorruptedRunConfigStructure Structure of the run-config data is corrupted or invalid.
6 MISSING_RUNCONFIG_VALUE MissingRunConfigValue A required group or parameter is missing from the run-config file.
7 FILESYSTEM_INACCESSIBLE FilesystemInaccessible Unable to access a directory listed in StaticAuxiliaryFileGroup / StaticAncillaryFileGroup.
8 INPUT_FILES_INACCESSIBLE InputFilesInaccessible Unable to access input product files listed in InputFileGroup.
9 UNCALIBRATED_GEOLOCATION UncalibratedGeolocation Scene rejected because L1B GEO metadata reports OrbitCorrectionPerformed is false.
10 INVALID_COORDINATES InvalidCoordinates Scene rejected because L1B GEO coordinates fall outside [-90, 90] lat, [-180, 180] lon, or span $> 10^\circ$.
11 LAND_FILTER LandFilter Scene or tile rejected because metadata/grid reports no land pixels covered.
12 DAYTIME_FILTER DaytimeFilter Scene rejected because StandardMetadata/DayNightFlag is not Day (or solar zenith angle $\ge 90^\circ$).
13 CONUS_FILTER CONUSFilter Granule or tile does not cover the Continental United States (CONUS).
14 AUXILIARY_SERVER_UNREACHABLE AuxiliaryServerUnreachable Connection failed to a remote server hosting auxiliary data (e.g., CMR, LP DAAC, GEOS-5 FP).
15 AUXILIARY_LATENCY AuxiliaryLatency Required auxiliary granule (e.g., HLS, VIIRS) is not yet available; signals scheduler to retry later.
16 DOWNLOAD_FAILED DownloadFailed File transfer for an auxiliary dataset from a remote server to the local filesystem failed.
17 BLANK_OUTPUT BlankOutput Output rasters contained only no-data (NaN) values and were not written to a product file.
18 PRODUCT_WRITE_FAILED ProductWriteFailed PGE failed while writing the output product granule or archive to disk.

Development & Testing

Run the test suite with pytest:

pytest

License

Licensed under the Apache License, Version 2.0.

Metadata

Release files for ECOv003-exit-codes 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ECOv003-exit-codes 1.2.0
File Size Uploaded Provenance Actions
ecov003_exit_codes-1.2.0.tar.gz 14.5 kB Without provenance Details for ecov003_exit_codes-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ECOv003-exit-codes 1.2.0
File Interpreter ABI Platform Actions
ecov003_exit_codes-1.2.0-py3-none-any.whl Python 3 none any Details for ecov003_exit_codes-1.2.0-py3-none-any.whl

Total release size: 27.0 kB

Release files / ecov003_exit_codes-1.2.0.tar.gz

Download URL ecov003_exit_codes-1.2.0.tar.gz
Size 14.5 kB
Tags Source
SHA-256 checksum
How to use checksums
df57eae45ab1ff8c60a8a44e5d1c9b24db9d812bd84e3012b067c3a9a5ba09c2
BLAKE2b-256 checksum
How to use checksums
3996af29208aff8b370a126e0eb62f6e14bcc1bf634eb6917a336df68be8e17d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Release files / ecov003_exit_codes-1.2.0-py3-none-any.whl

Download URL ecov003_exit_codes-1.2.0-py3-none-any.whl
Size 12.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dfc24a23d98d6026fed626571cb301581187229574109fdfae65597f1b812997
BLAKE2b-256 checksum
How to use checksums
e579d27657bd41aafa54fc73e788412b302b195dafa510fb96464907d63e6726
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Security for ECOv003-exit-codes 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page