emsarray.cli#

If you want to write command line scripts that use emsarray, refer to the tutorial. This module provides a few helpers that make writing scripts much easier.

console_entrypoint(add_arguments)#

Decorator that turns a function in to a console entrypoint, suitable to use as a main() function. It will automatically set up loggers, make an argument parser, add verbosity flags, and handle unexpected errors.

console_entrypoint() takes one argument, a function that sets up an argparse.ArgumentParser instance. console_entrypoint() will use this to configure an ArgumentParser, parse the command line flags, and pass the options to the decorated function.

Example

This is a complete example of a command line program that will clip an input file using a geometry.

#!/usr/bin/env python3

import emsarray
import tempfile
from emsarray.cli.utils import console_entrypoint, geometry_argument
from pathlib import Path

def command_line_flags(parser: argparse.ArgumentParser) -> None:
    parser.add_argument('input_file', type=Path)
    parser.add_argument('clip', type=geometry_argument)
    parser.add_argument('output_file', type=Path)

@console_entrypoint(command_line_flags)
def main(options: argparse.Namespace) -> None:
    dataset = emsarray.open_dataset(options.input_file)
    with tempfile.TemporaryDirectory() as temp_dir:
        dataset.clip(options.clip, work_dir=Path(temp_dir))
        dataset.ems.to_netcdf(options.output_file)

if __name__ == '__main__':
    main()

This example is more-or-less exactly what the console_entrypoint() decorator does, where the decorated function provides the rest of the implementation.

@nice_console_errors()
def main(argv: Optional[List[str]]) -> None:
    parser = argparse.ArgumentParser()
    add_verbosity_group(parser)
    command_line_flags(parser)
    options = parser.parse_args(argv)
    set_verbosity(options.verbosity)

    ...  # Continue on with the rest of the program

Command line arguments#

The following functions aid in converting command line flags in to useful Python values.

geometry_argument(argument_string)#

Try and make some geometry from an argument. The following things are tried in order:

If the argument consists of four comma separated numbers, this is converted to a bounding box. The numbers are interpreted as (lon min, lat min, lon max, lat max).

If the argument can be parsed as JSON, it is assumed to be geojson and passed to shapely.geometry.shape().

Finally, the argument is interpreted as a file. The file extension is used to guess the type of file. Currently geojson files are the only supported type

Example

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bounds', type=geometry_argument)
>>> options = parser.parse_args(['1,2,3,4'])
>>> print(options.bounds)
POLYGON (( 3 4, 1 4, 1 2, 3 2, 3 4 ))
>>> options = parser.parse_args(['{"type": "Point", "coordinates": [1, 2]}'])
>>> print(options.bounds)
POINT (1 2)
>>> options = parser.parse_args(['./path/to/polygon.geojson'])
>>> print(options.bounds)
POLYGON (( 0 1, 1 0, 2 1, 1 2, 0 1 ))

bounds_argument(bounds_string)#

Parse a comma separated string of (lon_min, lat_min, lon_max, lat_max) in to a shapely.Polygon. Used as an argparse parameter type.

Example

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bounds', type=bounds_argument)
>>> options = parser.parse_args(['1,2,3,4'])
>>> print(options.bounds)
POLYGON (( 3 4, 1 4, 1 2, 3 2, 3 4 ))

Exceptions#

exception CommandException(message, code=1)#: Raise this to exit a command line script gracefully.

See also

utils.console_entrypoint()

emsarray.cli

Contents

emsarray.cli#

Command line arguments#

Exceptions#