CmdLineTask

class lsst.pipe.base.CmdLineTask(config=None, name=None, parentTask=None, log=None)

Bases: lsst.pipe.base.Task

Base class for command-line tasks: tasks that may be executed from the command-line.

Notes

See Overview of the task framework to learn what tasks are and Creating a command-line task for more information about writing command-line tasks.

Subclasses must specify the following class variables:

• ConfigClass: configuration class for your task (a subclass of lsst.pex.config.Config, or if your task needs no configuration, then lsst.pex.config.Config itself).
• _DefaultName: default name used for this task (a str).

Subclasses may also specify the following class variables:

• RunnerClass: a task runner class. The default is TaskRunner, which works for any task with a run method that takes exactly one argument: a data reference. If your task does not meet this requirement then you must supply a variant of TaskRunner; see TaskRunner for more information.
• canMultiprocess: the default is True; set False if your task does not support multiprocessing.

Subclasses must specify a method named run:

• By default run accepts a single butler data reference, but you can specify an alternate task runner (subclass of TaskRunner) as the value of class variable RunnerClass if your run method needs something else.
• run is expected to return its data in a lsst.pipe.base.Struct. This provides safety for evolution of the task since new values may be added without harming existing code.
• The data returned by run must be picklable if your task is to support multiprocessing.

Attributes Summary

canMultiprocess

Methods Summary

applyOverrides(config)	A hook to allow a task to change the values of its config after the camera-specific overrides are loaded but before any command-line overrides are applied.
parseAndRun([args, config, log, doReturnResults])	Parse an argument list and run the command.
writeConfig(butler[, clobber, doBackup])	Write the configuration used for processing the data, or check that an existing one is equal to the new one if present.
writeMetadata(dataRef)	Write the metadata produced from processing the data.
writePackageVersions(butler[, clobber, …])	Compare and write package versions.
writeSchemas(butler[, clobber, doBackup])	Write the schemas returned by lsst.pipe.base.Task.getAllSchemaCatalogs.

Attributes Documentation

canMultiprocess = True

Methods Documentation

classmethod applyOverrides(config)

A hook to allow a task to change the values of its config after the camera-specific overrides are loaded but before any command-line overrides are applied.

Parameters:

config : instance of task’s ConfigClass

Task configuration.

Notes

This is necessary in some cases because the camera-specific overrides may retarget subtasks, wiping out changes made in ConfigClass.setDefaults. See LSST Trac ticket #2282 for more discussion.

Warning

This is called by CmdLineTask.parseAndRun; other ways of constructing a config will not apply these overrides.

classmethod parseAndRun(args=None, config=None, log=None, doReturnResults=False)

Parse an argument list and run the command.

Parameters:

args : list, optional

List of command-line arguments; if None use sys.argv.

config : lsst.pex.config.Config-type, optional

Config for task. If None use Task.ConfigClass.

log : lsst.log.Log-type, optional

Log. If None use the default log.

doReturnResults : bool, optional

If True, return the results of this task. Default is False. This is only intended for unit tests and similar use. It can easily exhaust memory (if the task returns enough data and you call it enough times) and it will fail when using multiprocessing if the returned data cannot be pickled.

Returns:

struct : lsst.pipe.base.Struct

Fields are:

• argumentParser: the argument parser.
• parsedCmd: the parsed command returned by the argument parser’s lsst.pipe.base.ArgumentParser.parse_args method.
• taskRunner: the task runner used to run the task (an instance of Task.RunnerClass).

• resultList: results returned by the task runner’s run method, one entry per invocation.

  This will typically be a list of None unless doReturnResults is True; see Task.RunnerClass (TaskRunner by default) for more information.

Notes

Calling this method with no arguments specified is the standard way to run a command-line task from the command-line. For an example see pipe_tasks bin/makeSkyMap.py or almost any other file in that directory.

If one or more of the dataIds fails then this routine will exit (with a status giving the number of failed dataIds) rather than returning this struct; this behaviour can be overridden by specifying the --noExit command-line option.

writeConfig(butler, clobber=False, doBackup=True)

Write the configuration used for processing the data, or check that an existing one is equal to the new one if present.

Parameters:

butler : lsst.daf.persistence.Butler

Data butler used to write the config. The config is written to dataset type CmdLineTask._getConfigName.

clobber : bool, optional

A boolean flag that controls what happens if a config already has been saved: - True: overwrite or rename the existing config, depending on doBackup. - False: raise TaskError if this config does not match the existing config.

doBackup : bool, optional

Set to True to backup the config files if clobbering.

writeMetadata(dataRef)

Write the metadata produced from processing the data.

Parameters:

dataRef

Butler data reference used to write the metadata. The metadata is written to dataset type CmdLineTask._getMetadataName.

writePackageVersions(butler, clobber=False, doBackup=True, dataset='packages')

Compare and write package versions.

Parameters:

butler : lsst.daf.persistence.Butler

Data butler used to read/write the package versions.

clobber : bool, optional

A boolean flag that controls what happens if versions already have been saved: - True: overwrite or rename the existing version info, depending on doBackup. - False: raise TaskError if this version info does not match the existing.

doBackup : bool, optional

If True and clobbering, old package version files are backed up.

dataset : str, optional

Name of dataset to read/write.

Raises:

TaskError

Raised if there is a version mismatch with current and persisted lists of package versions.

Notes

Note that this operation is subject to a race condition.

writeSchemas(butler, clobber=False, doBackup=True)

Write the schemas returned by lsst.pipe.base.Task.getAllSchemaCatalogs.

Parameters:

butler : lsst.daf.persistence.Butler

Data butler used to write the schema. Each schema is written to the dataset type specified as the key in the dict returned by getAllSchemaCatalogs.

clobber : bool, optional

A boolean flag that controls what happens if a schema already has been saved: - True: overwrite or rename the existing schema, depending on doBackup. - False: raise TaskError if this schema does not match the existing schema.

doBackup : bool, optional

Set to True to backup the schema files if clobbering.

Notes

If clobber is False and an existing schema does not match a current schema, then some schemas may have been saved successfully and others may not, and there is no easy way to tell which is which.