ArgumentParser

class lsst.pipe.base.ArgumentParser(name, usage='%(prog)s input [options]', **kwargs)

Bases: argparse.ArgumentParser

Argument parser for command-line tasks that is based on argparse.ArgumentParser.

Parameters:
name : str

Name of top-level task; used to identify camera-specific override files.

usage : str, optional

Command-line usage signature.

**kwargs

Additional keyword arguments for argparse.ArgumentParser.

Notes

Users may wish to add additional arguments before calling parse_args.

Attributes Summary

requireOutput Require an output directory to be specified (bool).

Methods Summary

addReuseOption(choices) Add a “–reuse-outputs-from SUBTASK” option to the argument parser.
add_argument(dest, …[, name, name])
add_argument_group(*args, **kwargs)
add_id_argument(name, datasetType, help[, …]) Add a data ID argument.
add_mutually_exclusive_group(**kwargs)
add_subparsers(**kwargs)
convert_arg_line_to_args(arg_line) Allow files of arguments referenced by @<path> to contain multiple values on each line.
error(message) Prints a usage message incorporating the message to stderr and exits.
exit([status, message])
format_help()
format_usage()
get_default(dest)
handleCamera(namespace) Perform camera-specific operations before parsing the command-line.
parse_args(config[, args, log, override]) Parse arguments for a command-line task.
parse_known_args([args, namespace])
print_help([file])
print_usage([file])
register(registry_name, value, object)
set_defaults(**kwargs)

Attributes Documentation

requireOutput = True

Require an output directory to be specified (bool).

Methods Documentation

addReuseOption(choices)

Add a “–reuse-outputs-from SUBTASK” option to the argument parser.

CmdLineTasks that can be restarted at an intermediate step using outputs from earlier (but still internal) steps should use this method to allow the user to control whether that happens when outputs from earlier steps are present.

Parameters:
choices : sequence

A sequence of string names (by convention, top-level subtasks) that identify the steps that could be skipped when their outputs are already present. The list is ordered, so when the user specifies one step on the command line, all previous steps may be skipped as well. In addition to the choices provided, users may pass “all” to indicate that all steps may be thus skipped.

When this method is called, the ``namespace`` object returned by
``parse_args`` will contain a ``reuse`` attribute containing
a list of all steps that should be skipped if their outputs
are already present.
If no steps should be skipped, the ``reuse`` will be an empty list.
add_argument(dest, ..., name=value, ...) add_argument(option_string, option_string, ..., name=value, ...)
add_argument_group(*args, **kwargs)
add_id_argument(name, datasetType, help, level=None, doMakeDataRefList=True, ContainerClass=<class 'lsst.pipe.base.argumentParser.DataIdContainer'>)

Add a data ID argument.

Parameters:
name : str

Data ID argument (including leading dashes, if wanted).

datasetType : str or DynamicDatasetType-type

Type of dataset. Supply a string for a fixed dataset type. For a dynamically determined dataset type, supply a DynamicDatasetType, such a DatasetArgument.

help : str

Help string for the argument.

level : str

The lowest hierarchy level to descend to for this dataset type, for example "amp" for "raw" or "ccd" for "calexp". Use "" to use the mapper’s default for the dataset type. Some container classes may also support None, which means the level should not be restricted; however the default class, DataIdContainer, does not support None.

doMakeDataRefList : bool, optional

If True (default), construct data references.

ContainerClass : class, optional
Class to contain data IDs and data references; the default class
`DataIdContainer` will work for many, but not all, cases.
For example if the dataset type is specified on the command line
then use `DynamicDatasetType`.

Notes

If datasetType is an instance of DatasetArgument, then add a second argument to specify the dataset type.

The associated data is put into namespace.<dataIdArgument.name> as an instance of ContainerClass; the container includes fields:

  • idList: a list of data ID dicts.
  • refList: a list of Butler
    data references (empty if doMakeDataRefList is False).
add_mutually_exclusive_group(**kwargs)
add_subparsers(**kwargs)
convert_arg_line_to_args(arg_line)

Allow files of arguments referenced by @<path> to contain multiple values on each line.

Parameters:
arg_line : str

Line of text read from an argument file.
error(message: string)

Prints a usage message incorporating the message to stderr and exits.

If you override this in a subclass, it should not return – it should either exit or raise an exception.

exit(status=0, message=None)
format_help()
format_usage()
get_default(dest)
handleCamera(namespace)

Perform camera-specific operations before parsing the command-line.

Parameters:
namespace : argparse.Namespace

Namespace (an ) with the following fields:

  • camera: the camera name.
  • config: the config passed to parse_args, with no overrides applied.
  • obsPkg: the obs_ package for this camera.
  • log: a lsst.log Log.

Notes

The default implementation does nothing.

parse_args(config, args=None, log=None, override=None)

Parse arguments for a command-line task.

Parameters:
config : lsst.pex.config.Config

Config for the task being run.

args : list, optional

Argument list; if None then sys.argv[1:] is used.

log : lsst.log.Log, optional

Log instance; if None use the default log.

override : callable, optional

A config override function. It must take the root config object as its only argument and must modify the config in place. This function is called after camera-specific overrides files are applied, and before command-line config overrides are applied (thus allowing the user the final word).
Returns:
namespace : argparse.Namespace

A Namespace instance containing fields:

  • camera: camera name.

  • config: the supplied config with all overrides applied,

    validated and frozen.

  • butler: a lsst.daf.persistence.Butler for the data.

  • An entry for each of the data ID arguments registered by

    add_id_argument, of the type passed to its ContainerClass keyword (DataIdContainer by default). It includes public elements idList and refList.

  • log: a lsst.log Log.

  • An entry for each command-line argument,

    with the following exceptions:

    • config is the supplied config, suitably updated.
    • configfile, id and loglevel are all missing.

  • obsPkg: name of the obs_ package for this camera.
parse_known_args(args=None, namespace=None)
print_help(file=None)
print_usage(file=None)
register(registry_name, value, object)
set_defaults(**kwargs)