Tool

class ctapipe.core.tool.Tool(**kwargs: Any)

Bases: traitlets.config.application.Application

A base class for all executable tools (applications) that handles configuration loading/saving, logging, command-line processing, and provenance meta-data handling. It is based on traitlets.config.Application. Tools may contain configurable ctapipe.core.Component classes that do work, and their configuration parameters will propagate automatically to the Tool.

Tool developers should create sub-classes, and a name, description, usage examples should be added by defining the name, description and examples class attributes as strings. The aliases attribute can be set to cause a lower-level Component parameter to become a high-level command-line parameter (See example below). The setup, start, and finish methods should be defined in the sub-class.

Additionally, any ctapipe.core.Component used within the Tool should have their class in a list in the classes attribute, which will automatically add their configuration parameters to the tool.

Once a tool is constructed and the virtual methods defined, the user can call the run method to setup and start it.

from ctapipe.core import Tool
from traitlets import (Integer, Float, Dict, Unicode)

class MyTool(Tool):
    name = "mytool"
    description = "do some things and stuff"
    aliases = Dict({'infile': 'AdvancedComponent.infile',
                    'iterations': 'MyTool.iterations'})

    # Which classes are registered for configuration
    classes = [MyComponent, AdvancedComponent, SecondaryMyComponent]

    # local configuration parameters
    iterations = Integer(5,help="Number of times to run",
                         allow_none=False).tag(config=True)

    def setup_comp(self):
        self.comp = MyComponent(self, parent=self)
        self.comp2 = SecondaryMyComponent(self, parent=self)

    def setup_advanced(self):
        self.advanced = AdvancedComponent(self, parent=self)

    def setup(self):
        self.setup_comp()
        self.setup_advanced()

    def start(self):
        self.log.info("Performing {} iterations..."                              .format(self.iterations))
        for ii in range(self.iterations):
            self.log.info("ITERATION {}".format(ii))
            self.comp.do_thing()
            self.comp2.do_thing()
            sleep(0.5)

    def finish(self):
        self.log.warning("Shutting down.")

def main():
    tool = MyTool()
    tool.run()

if __name__ == "main":
   main()

If this main() function is registered in setup.py under entry_points, it will become a command-line tool (see examples in the ctapipe/tools subdirectory).

Attributes Summary

config_files	An instance of a Python list.
log_config	An instance of a Python dict.
log_file	A path Trait for input/output files.
log_file_level	An enum whose value must be in a given sequence.
provenance_log	A path Trait for input/output files.
quiet	A boolean (True, False) trait.
version_string	a formatted version string with version, release, and git hash

Methods Summary

add_component(component_instance)	constructs and adds a component to the list of registered components, so that later we can ask for the current configuration of all instances, e.g.
finish()	finish up (override in subclass).
get_current_config()	return the current configuration as a dict (e.g.
initialize([argv])	handle config and any other low-level setup
load_config_file(path)	Load a configuration file in one of the supported formats, and merge it with the current config if it exists.
run([argv, raises])	Run the tool.
setup()	set up the tool (override in subclass).
start()	main body of tool (override in subclass).
update_logging_config()	Update the configuration of loggers.
write_provenance()

Attributes Documentation

config_files

An instance of a Python list.

log_config

An instance of a Python dict.

One or more traits can be passed to the constructor to validate the keys and/or values of the dict. If you need more detailed validation, you may use a custom validator method.

Changed in version 5.0: Added key_trait for validating dict keys.

Changed in version 5.0: Deprecated ambiguous trait, traits args in favor of value_trait, per_key_traits.

log_file

A path Trait for input/output files.

Attributes

exists: boolean or None

If True, path must exist, if False path must not exist

directory_ok: boolean

If False, path must not be a directory

file_ok: boolean

If False, path must not be a file

log_file_level

An enum whose value must be in a given sequence.

provenance_log

A path Trait for input/output files.

Attributes

exists: boolean or None

If True, path must exist, if False path must not exist

directory_ok: boolean

If False, path must not be a directory

file_ok: boolean

If False, path must not be a file

quiet

A boolean (True, False) trait.

version_string

a formatted version string with version, release, and git hash

Methods Documentation

add_component(component_instance)

constructs and adds a component to the list of registered components, so that later we can ask for the current configuration of all instances, e.g. in`get_full_config()`. All sub-components of a tool should be constructed using this function, in order to ensure the configuration is properly traced.

Parameters

component_instance: Component

constructed instance of a component

Returns

Component:

the same component instance that was passed in, so that the call can be chained.

Examples

self.mycomp = self.add_component(MyComponent(parent=self))

abstract finish()

finish up (override in subclass). This is called automatically after Tool.start when Tool.run is called.

get_current_config()

return the current configuration as a dict (e.g. the values of all traits, even if they were not set during configuration)

initialize(argv=None)

handle config and any other low-level setup

load_config_file(path: Union[str, pathlib.Path]) → None

Load a configuration file in one of the supported formats, and merge it with the current config if it exists.

Parameters

path: Union[str, pathlib.Path]

config file to load. [yaml, toml, json, py] formats are supported

run(argv=None, raises=False)

Run the tool. This automatically calls initialize(), start() and finish()

Parameters

argv: list(str)

command-line arguments, or None to get them from sys.argv automatically

abstract setup()

set up the tool (override in subclass). Here the user should construct all Components and open files, etc.

abstract start()

main body of tool (override in subclass). This is automatically called after Tool.initialize when the Tool.run is called.

update_logging_config()

Update the configuration of loggers.

write_provenance()