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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.