.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/core/command_line_tools.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_core_command_line_tools.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_core_command_line_tools.py:


Creating command-line Tools
===========================

.. GENERATED FROM PYTHON SOURCE LINES 6-20

.. code-block:: Python
   :lineno-start: 7


    from time import sleep

    from ctapipe.core import Component, TelescopeComponent, Tool
    from ctapipe.core.traits import (
        FloatTelescopeParameter,
        Integer,
        Path,
        TraitError,
        observe,
    )
    from ctapipe.instrument import SubarrayDescription
    from ctapipe.utils import get_dataset_path








.. GENERATED FROM PYTHON SOURCE LINES 21-24

.. code-block:: Python
   :lineno-start: 21

    GAMMA_FILE = get_dataset_path("gamma_prod5.simtel.zst")









.. GENERATED FROM PYTHON SOURCE LINES 25-27

see https://github.com/ipython/traitlets/blob/master/examples/myapp.py


.. GENERATED FROM PYTHON SOURCE LINES 30-35

Setup:
------

Create a few ``Component``\ s that we will use later in a ``Tool``:


.. GENERATED FROM PYTHON SOURCE LINES 35-84

.. code-block:: Python
   :lineno-start: 37



    class MyComponent(Component):
        """A Component that does stuff"""

        value = Integer(default_value=-1, help="Value to use").tag(config=True)

        def do_thing(self):
            self.log.debug("Did thing")


    # in order to have 2 of the same components at once
    class SecondaryMyComponent(MyComponent):
        """A second component"""


    class AdvancedComponent(Component):
        """An advanced technique"""

        value1 = Integer(default_value=-1, help="Value to use").tag(config=True)
        infile = Path(
            help="input file name",
            exists=None,  # set to True to require existing, False for requiring non-existing
            directory_ok=False,
        ).tag(config=True)
        outfile = Path(help="output file name", exists=False, directory_ok=False).tag(
            config=True
        )

        def __init__(self, config=None, parent=None, **kwargs):
            super().__init__(config=config, parent=parent, **kwargs)
            # components can have sub components, but these must have
            # then parent=self as argument and be assigned as member
            # so the full config can be received later
            self.subcompent = MyComponent(parent=self)

        @observe("outfile")
        def on_outfile_changed(self, change):
            self.log.warning("Outfile was changed to '{}'".format(change))


    class TelescopeWiseComponent(TelescopeComponent):
        """a component that contains parameters that are per-telescope configurable"""

        param = FloatTelescopeParameter(
            help="Something configurable with telescope patterns", default_value=5.0
        ).tag(config=True)









.. GENERATED FROM PYTHON SOURCE LINES 85-87

.. code-block:: Python
   :lineno-start: 85

    MyComponent()






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div style="border:1px solid black; max-width: 700px; padding:2em; word-wrap:break-word;">
    <b>MyComponent</b>
    <div class="document">
    <p>A Component that does stuff</p>
    </div>

    <table>
        <colgroup>
            <col span='1' style=' '>
            <col span='1' style='width: 20em;'>
            <col span='1' >
        </colgroup>
        <tbody>
    <tr><th>value</th>
    <td style="text-align: left;">-1</td>
    <td style="text-align: left;"><i>Value to use (default: -1)</i></td></tr>
        </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 88-91

.. code-block:: Python
   :lineno-start: 88

    AdvancedComponent(infile="test.foo", outfile="out.foo")






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Outfile was changed to '{'name': 'outfile', 'old': None, 'new': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/out.foo'), 'owner': <__main__.AdvancedComponent object at 0x79f08c4b6ef0>, 'type': 'change'}'


.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div style="border:1px solid black; max-width: 700px; padding:2em; word-wrap:break-word;">
    <b>AdvancedComponent</b>
    <div class="document">
    <p>An advanced technique</p>
    </div>

    <table>
        <colgroup>
            <col span='1' style=' '>
            <col span='1' style='width: 20em;'>
            <col span='1' >
        </colgroup>
        <tbody>
    <tr><th>infile</th>
    <td style="text-align: left;"><span style="color:blue; max-width:30em;">/<wbr>home/<wbr>docs/<wbr>checkouts/<wbr>readthedocs.org/<wbr>user_<wbr>builds/<wbr>ctapipe/<wbr>checkouts/<wbr>2868/<wbr>examples/<wbr>core/<wbr>test.foo</span></td>
    <td style="text-align: left;"><i>input file name (default: None)</i></td></tr>
    <tr><th>outfile</th>
    <td style="text-align: left;"><span style="color:blue; max-width:30em;">/<wbr>home/<wbr>docs/<wbr>checkouts/<wbr>readthedocs.org/<wbr>user_<wbr>builds/<wbr>ctapipe/<wbr>checkouts/<wbr>2868/<wbr>examples/<wbr>core/<wbr>out.foo</span></td>
    <td style="text-align: left;"><i>output file name (default: None)</i></td></tr>
    <tr><th>value1</th>
    <td style="text-align: left;">-1</td>
    <td style="text-align: left;"><i>Value to use (default: -1)</i></td></tr>
        </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 92-97

``TelescopeComponents`` need to have a subarray given to them in order
to work (since they need one to turn a ``TelescopeParameter`` into a
concrete list of values for each telescope. Here we will give a dummy
one:


.. GENERATED FROM PYTHON SOURCE LINES 97-102

.. code-block:: Python
   :lineno-start: 99



    subarray = SubarrayDescription.read(GAMMA_FILE)
    subarray.info()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Subarray : MonteCarloArray
    Num Tels : 180
    Footprint: 4.92 km2
    Height   : 2147.00 m
    Lon/Lat  : 0.0 deg, 0.0 deg 

           Type       Count     Tel IDs    
    ----------------- ----- ---------------
       SST_ASTRI_CHEC   120 30-99,131-180  
       LST_LST_LSTCam     4 1-4            
    MST_MST_NectarCam    28 100-124,128-130
     MST_MST_FlashCam    28 5-29,125-127   




.. GENERATED FROM PYTHON SOURCE LINES 103-106

.. code-block:: Python
   :lineno-start: 103

    TelescopeWiseComponent(subarray=subarray)







.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div style="border:1px solid black; max-width: 700px; padding:2em; word-wrap:break-word;">
    <b>TelescopeWiseComponent</b>
    <div class="document">
    <p>a component that contains parameters that are per-telescope configurable</p>
    </div>

    <table>
        <colgroup>
            <col span='1' style=' '>
            <col span='1' style='width: 20em;'>
            <col span='1' >
        </colgroup>
        <tbody>
    <tr><th>param</th>
    <td style="text-align: left;"><span style="color:blue; max-width:30em;">[(&#x27;type&#x27;, &#x27;*&#x27;, 5.0)]</span></td>
    <td style="text-align: left;"><i>Something configurable with telescope patterns.  (default: traitlets.Undefined)</i></td></tr>
        </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 107-118

This TelescopeParameters can then be set using a list of patterns like:


   component.param = [("type", "LST*",3.0),("type", "MST*", 2.0),(id, 25, 4.0)]

These get translated into per-telescope-id values once the subarray is
registered. After that one access the per-telescope id values via:


   component.param.tel[tel_id]


.. GENERATED FROM PYTHON SOURCE LINES 121-127

Now create an executable Tool that contains the Components
----------------------------------------------------------

Note that all the components we wish to be configured via the tool must
be added to the ``classes`` attribute.


.. GENERATED FROM PYTHON SOURCE LINES 127-169

.. code-block:: Python
   :lineno-start: 129



    class MyTool(Tool):
        name = "mytool"
        description = "do some things and stuff"
        aliases = dict(
            infile="AdvancedComponent.infile",
            outfile="AdvancedComponent.outfile",
            iterations="MyTool.iterations",
        )

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

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

        def setup(self):
            self.comp = MyComponent(parent=self)
            self.comp2 = SecondaryMyComponent(parent=self)
            self.comp3 = TelescopeWiseComponent(parent=self, subarray=subarray)
            self.advanced = AdvancedComponent(parent=self)

        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.1)

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









.. GENERATED FROM PYTHON SOURCE LINES 170-181

Get Help info
-------------

The following allows you to print the help info within a Jupyter
notebook, but this same information would be displayed if the user
types:

::

     mytool --help


.. GENERATED FROM PYTHON SOURCE LINES 181-185

.. code-block:: Python
   :lineno-start: 182


    tool = MyTool()
    tool






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div style="border:1px solid black; max-width: 700px; padding:2em; word-wrap:break-word;">
    <b>MyTool</b>
    <div class="document">
    <p>do some things and stuff</p>
    </div>

    <table>
        <colgroup>
            <col span='1' style=' '>
            <col span='1' style='width: 20em;'>
            <col span='1' >
        </colgroup>
        <tbody>
    <tr><th>config_files</th>
    <td style='text-align: left;'><span style='color:blue; max-width:30em;'>[]</span></td>
    <td style='text-align: left;'><i>List of configuration files with parameters to load in addition to command-line parameters. The order listed is the order of precedence (later config parameters overwrite earlier ones), however parameters specified on the command line always have the highest precedence. Config files may be in JSON, YAML, TOML, or Python format (default: traitlets.Undefined)</i></td></tr>
    <tr><th>iterations</th>
    <td style='text-align: left;'>5</td>
    <td style='text-align: left;'><i>Number of times to run (default: 5)</i></td></tr>
    <tr><th>log_config</th>
    <td style='text-align: left;'><span style='color:blue; max-width:30em;'>{}</span></td>
    <td style='text-align: left;'><i> (default: traitlets.Undefined)</i></td></tr>
    <tr><th>log_datefmt</th>
    <td style='text-align: left;'>%Y-%m-%d %H:%M:%S</td>
    <td style='text-align: left;'><i>The date format used by logging formatters for %(asctime)s (default: %Y-%m-%d %H:%M:%S)</i></td></tr>
    <tr><th>log_file</th>
    <td style='text-align: left;'>None</td>
    <td style='text-align: left;'><i>Filename for the log (default: None)</i></td></tr>
    <tr><th>log_file_level</th>
    <td style='text-align: left;'>INFO</td>
    <td style='text-align: left;'><i>Logging Level for File Logging (default: INFO)</i></td></tr>
    <tr><th>log_format</th>
    <td style='text-align: left;'>[%(name)s]%(highlevel)s %(message)s</td>
    <td style='text-align: left;'><i>The Logging format template (default: [%(name)s]%(highlevel)s %(message)s)</i></td></tr>
    <tr><th>log_level</th>
    <td style='text-align: left;'>30</td>
    <td style='text-align: left;'><i>Set the log level by value or name. (default: 30)</i></td></tr>
    <tr><th>logging_config</th>
    <td style='text-align: left;'><span style='color:blue; max-width:30em;'>{}</span></td>
    <td style='text-align: left;'><i>
                Configure additional log handlers.

                The default stderr logs handler is configured by the
                log_level, log_datefmt and log_format settings.

                This configuration can be used to configure additional handlers
                (e.g. to output the log to a file) or for finer control over the
                default handlers.

                If provided this should be a logging configuration dictionary, for
                more information see:
                https://docs.python.org/3/library/logging.config.html#logging-config-dictschema

                This dictionary is merged with the base logging configuration which
                defines the following:

                * A logging formatter intended for interactive use called
                  ``console``.
                * A logging handler that writes to stderr called
                  ``console`` which uses the formatter ``console``.
                * A logger with the name of this application set to ``DEBUG``
                  level.

                This example adds a new handler that writes to a file:

                .. code-block:: python

                   c.Application.logging_config = {
                       &quot;handlers&quot;: {
                           &quot;file&quot;: {
                               &quot;class&quot;: &quot;logging.FileHandler&quot;,
                               &quot;level&quot;: &quot;DEBUG&quot;,
                               &quot;filename&quot;: &quot;&lt;path/to/file&gt;&quot;,
                           }
                       },
                       &quot;loggers&quot;: {
                           &quot;&lt;application-name&gt;&quot;: {
                               &quot;level&quot;: &quot;DEBUG&quot;,
                               # NOTE: if you don&#x27;t list the default &quot;console&quot;
                               # handler here then it will be disabled
                               &quot;handlers&quot;: [&quot;console&quot;, &quot;file&quot;],
                           },
                       },
                   }

             (default: traitlets.Undefined)</i></td></tr>
    <tr><th>overwrite</th>
    <td style='text-align: left;'>False</td>
    <td style='text-align: left;'><i> (default: False)</i></td></tr>
    <tr><th>provenance_log</th>
    <td style='text-align: left;'><span style='color:blue; max-width:30em;'>/<wbr>home/<wbr>docs/<wbr>checkouts/<wbr>readthedocs.org/<wbr>user_<wbr>builds/<wbr>ctapipe/<wbr>checkouts/<wbr>2868/<wbr>docs/<wbr>mytool.provenance.log</span></td>
    <td style='text-align: left;'><i> (default: None)</i></td></tr>
    <tr><th>quiet</th>
    <td style='text-align: left;'>False</td>
    <td style='text-align: left;'><i> (default: False)</i></td></tr>
    <tr><th>show_config</th>
    <td style='text-align: left;'>False</td>
    <td style='text-align: left;'><i>Instead of starting the Application, dump configuration to stdout (default: False)</i></td></tr>
    <tr><th>show_config_json</th>
    <td style='text-align: left;'>False</td>
    <td style='text-align: left;'><i>Instead of starting the Application, dump configuration to stdout (as JSON) (default: False)</i></td></tr>
        </tbody>
    </table>
    <p><b>Components:</b>
    MyTool, MyComponent, AdvancedComponent, SecondaryMyComponent, TelescopeWiseComponent
    </p>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 186-189

.. code-block:: Python
   :lineno-start: 186

    tool.print_help()






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    do some things and stuff

    Options
    =======
    The options below are convenience aliases to configurable class-options,
    as listed in the "Equivalent to" description-line of the aliases.
    To see all configurable class-options for some <cmd>, use:
        <cmd> --help-all

    --debug
        Set log-level to debug, for the most verbose logging.
        Equivalent to: [--Application.log_level=10]
    --show-config
        Show the application's configuration (human-readable format)
        Equivalent to: [--Application.show_config=True]
    --show-config-json
        Show the application's configuration (json format)
        Equivalent to: [--Application.show_config_json=True]
    -q, --quiet
        Disable console logging.
        Equivalent to: [--Tool.quiet=True]
    -v, --verbose
        Set log level to DEBUG
        Equivalent to: [--Tool.log_level=DEBUG]
    --overwrite
        Overwrite existing output files without asking
        Equivalent to: [--Tool.overwrite=True]
    -c, --config=<list-item-1>...
        List of configuration files with parameters to load in addition to command-
        line parameters. The order listed is the order of precedence (later config
        parameters overwrite earlier ones), however parameters specified on the
        command line always have the highest precedence. Config files may be in
        JSON, YAML, TOML, or Python format
        Default: []
        Equivalent to: [--Tool.config_files]
    --log-level=<Enum>
        Set the log level by value or name.
        Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
        Default: 30
        Equivalent to: [--Tool.log_level]
    -l, --log-file=<Path>
        Filename for the log
        Default: None
        Equivalent to: [--Tool.log_file]
    --log-file-level=<Enum>
        Logging Level for File Logging
        Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
        Default: 'INFO'
        Equivalent to: [--Tool.log_file_level]
    --provenance-log=<Path>
        Default: None
        Equivalent to: [--Tool.provenance_log]
    --infile=<Path>
        input file name
        Default: None
        Equivalent to: [--AdvancedComponent.infile]
    --outfile=<Path>
        output file name
        Default: None
        Equivalent to: [--AdvancedComponent.outfile]
    --iterations=<Long>
        Number of times to run
        Default: 5
        Equivalent to: [--MyTool.iterations]

    To see all available configurables, use `--help-all`.





.. GENERATED FROM PYTHON SOURCE LINES 190-192

The following is equivalent to the user typing ``mytool --help-all``


.. GENERATED FROM PYTHON SOURCE LINES 192-196

.. code-block:: Python
   :lineno-start: 193


    tool.print_help(classes=True)






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    do some things and stuff

    Options
    =======
    The options below are convenience aliases to configurable class-options,
    as listed in the "Equivalent to" description-line of the aliases.
    To see all configurable class-options for some <cmd>, use:
        <cmd> --help-all

    --debug
        Set log-level to debug, for the most verbose logging.
        Equivalent to: [--Application.log_level=10]
    --show-config
        Show the application's configuration (human-readable format)
        Equivalent to: [--Application.show_config=True]
    --show-config-json
        Show the application's configuration (json format)
        Equivalent to: [--Application.show_config_json=True]
    -q, --quiet
        Disable console logging.
        Equivalent to: [--Tool.quiet=True]
    -v, --verbose
        Set log level to DEBUG
        Equivalent to: [--Tool.log_level=DEBUG]
    --overwrite
        Overwrite existing output files without asking
        Equivalent to: [--Tool.overwrite=True]
    -c, --config=<list-item-1>...
        List of configuration files with parameters to load in addition to command-
        line parameters. The order listed is the order of precedence (later config
        parameters overwrite earlier ones), however parameters specified on the
        command line always have the highest precedence. Config files may be in
        JSON, YAML, TOML, or Python format
        Default: []
        Equivalent to: [--Tool.config_files]
    --log-level=<Enum>
        Set the log level by value or name.
        Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
        Default: 30
        Equivalent to: [--Tool.log_level]
    -l, --log-file=<Path>
        Filename for the log
        Default: None
        Equivalent to: [--Tool.log_file]
    --log-file-level=<Enum>
        Logging Level for File Logging
        Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
        Default: 'INFO'
        Equivalent to: [--Tool.log_file_level]
    --provenance-log=<Path>
        Default: None
        Equivalent to: [--Tool.provenance_log]
    --infile=<Path>
        input file name
        Default: None
        Equivalent to: [--AdvancedComponent.infile]
    --outfile=<Path>
        output file name
        Default: None
        Equivalent to: [--AdvancedComponent.outfile]
    --iterations=<Long>
        Number of times to run
        Default: 5
        Equivalent to: [--MyTool.iterations]

    Class options
    =============
    The command-line option below sets the respective configurable class-parameter:
        --Class.parameter=value
    This line is evaluated in Python, so simple expressions are allowed.
    For instance, to set `C.a=[0,1,2]`, you may type this:
        --C.a='range(3)'

    Application(SingletonConfigurable) options
    ------------------------------------------
    --Application.log_datefmt=<Unicode>
        The date format used by logging formatters for %(asctime)s
        Default: '%Y-%m-%d %H:%M:%S'
    --Application.log_format=<Unicode>
        The Logging format template
        Default: '[%(name)s]%(highlevel)s %(message)s'
    --Application.log_level=<Enum>
        Set the log level by value or name.
        Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
        Default: 30
    --Application.logging_config=<key-1>=<value-1>...
        Configure additional log handlers.
        The default stderr logs handler is configured by the log_level, log_datefmt
        and log_format settings.
        This configuration can be used to configure additional handlers (e.g. to
        output the log to a file) or for finer control over the default handlers.
        If provided this should be a logging configuration dictionary, for more
        information see:
        https://docs.python.org/3/library/logging.config.html#logging-config-
        dictschema
        This dictionary is merged with the base logging configuration which defines
        the following:
        * A logging formatter intended for interactive use called
          ``console``.
        * A logging handler that writes to stderr called
          ``console`` which uses the formatter ``console``.
        * A logger with the name of this application set to ``DEBUG``
          level.
        This example adds a new handler that writes to a file:
        .. code-block:: python
           c.Application.logging_config = {
               "handlers": {
                   "file": {
                       "class": "logging.FileHandler",
                       "level": "DEBUG",
                       "filename": "<path/to/file>",
                   }
               },
               "loggers": {
                   "<application-name>": {
                       "level": "DEBUG",
                       # NOTE: if you don't list the default "console"
                       # handler here then it will be disabled
                       "handlers": ["console", "file"],
                   },
               },
           }
        Default: {}
    --Application.show_config=<Bool>
        Instead of starting the Application, dump configuration to stdout
        Default: False
    --Application.show_config_json=<Bool>
        Instead of starting the Application, dump configuration to stdout (as JSON)
        Default: False

    Tool(Application) options
    -------------------------
    --Tool.config_files=<list-item-1>...
        List of configuration files with parameters to load in addition to command-
        line parameters. The order listed is the order of precedence (later config
        parameters overwrite earlier ones), however parameters specified on the
        command line always have the highest precedence. Config files may be in
        JSON, YAML, TOML, or Python format
        Default: []
    --Tool.log_config=<key-1>=<value-1>...
        Default: {}
    --Tool.log_datefmt=<Unicode>
        The date format used by logging formatters for %(asctime)s
        Default: '%Y-%m-%d %H:%M:%S'
    --Tool.log_file=<Path>
        Filename for the log
        Default: None
    --Tool.log_file_level=<Enum>
        Logging Level for File Logging
        Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
        Default: 'INFO'
    --Tool.log_format=<Unicode>
        The Logging format template
        Default: '[%(name)s]%(highlevel)s %(message)s'
    --Tool.log_level=<Enum>
        Set the log level by value or name.
        Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
        Default: 30
    --Tool.logging_config=<key-1>=<value-1>...
        Configure additional log handlers.
        The default stderr logs handler is configured by the log_level, log_datefmt
        and log_format settings.
        This configuration can be used to configure additional handlers (e.g. to
        output the log to a file) or for finer control over the default handlers.
        If provided this should be a logging configuration dictionary, for more
        information see:
        https://docs.python.org/3/library/logging.config.html#logging-config-
        dictschema
        This dictionary is merged with the base logging configuration which defines
        the following:
        * A logging formatter intended for interactive use called
          ``console``.
        * A logging handler that writes to stderr called
          ``console`` which uses the formatter ``console``.
        * A logger with the name of this application set to ``DEBUG``
          level.
        This example adds a new handler that writes to a file:
        .. code-block:: python
           c.Application.logging_config = {
               "handlers": {
                   "file": {
                       "class": "logging.FileHandler",
                       "level": "DEBUG",
                       "filename": "<path/to/file>",
                   }
               },
               "loggers": {
                   "<application-name>": {
                       "level": "DEBUG",
                       # NOTE: if you don't list the default "console"
                       # handler here then it will be disabled
                       "handlers": ["console", "file"],
                   },
               },
           }
        Default: {}
    --Tool.overwrite=<Bool>
        Default: False
    --Tool.provenance_log=<Path>
        Default: None
    --Tool.quiet=<Bool>
        Default: False
    --Tool.show_config=<Bool>
        Instead of starting the Application, dump configuration to stdout
        Default: False
    --Tool.show_config_json=<Bool>
        Instead of starting the Application, dump configuration to stdout (as JSON)
        Default: False

    MyTool(Tool) options
    --------------------
    --MyTool.config_files=<list-item-1>...
        List of configuration files with parameters to load in addition to command-
        line parameters. The order listed is the order of precedence (later config
        parameters overwrite earlier ones), however parameters specified on the
        command line always have the highest precedence. Config files may be in
        JSON, YAML, TOML, or Python format
        Default: []
    --MyTool.iterations=<Long>
        Number of times to run
        Default: 5
    --MyTool.log_config=<key-1>=<value-1>...
        Default: {}
    --MyTool.log_datefmt=<Unicode>
        The date format used by logging formatters for %(asctime)s
        Default: '%Y-%m-%d %H:%M:%S'
    --MyTool.log_file=<Path>
        Filename for the log
        Default: None
    --MyTool.log_file_level=<Enum>
        Logging Level for File Logging
        Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
        Default: 'INFO'
    --MyTool.log_format=<Unicode>
        The Logging format template
        Default: '[%(name)s]%(highlevel)s %(message)s'
    --MyTool.log_level=<Enum>
        Set the log level by value or name.
        Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
        Default: 30
    --MyTool.logging_config=<key-1>=<value-1>...
        Configure additional log handlers.
        The default stderr logs handler is configured by the log_level, log_datefmt
        and log_format settings.
        This configuration can be used to configure additional handlers (e.g. to
        output the log to a file) or for finer control over the default handlers.
        If provided this should be a logging configuration dictionary, for more
        information see:
        https://docs.python.org/3/library/logging.config.html#logging-config-
        dictschema
        This dictionary is merged with the base logging configuration which defines
        the following:
        * A logging formatter intended for interactive use called
          ``console``.
        * A logging handler that writes to stderr called
          ``console`` which uses the formatter ``console``.
        * A logger with the name of this application set to ``DEBUG``
          level.
        This example adds a new handler that writes to a file:
        .. code-block:: python
           c.Application.logging_config = {
               "handlers": {
                   "file": {
                       "class": "logging.FileHandler",
                       "level": "DEBUG",
                       "filename": "<path/to/file>",
                   }
               },
               "loggers": {
                   "<application-name>": {
                       "level": "DEBUG",
                       # NOTE: if you don't list the default "console"
                       # handler here then it will be disabled
                       "handlers": ["console", "file"],
                   },
               },
           }
        Default: {}
    --MyTool.overwrite=<Bool>
        Default: False
    --MyTool.provenance_log=<Path>
        Default: None
    --MyTool.quiet=<Bool>
        Default: False
    --MyTool.show_config=<Bool>
        Instead of starting the Application, dump configuration to stdout
        Default: False
    --MyTool.show_config_json=<Bool>
        Instead of starting the Application, dump configuration to stdout (as JSON)
        Default: False

    MyComponent(Component) options
    ------------------------------
    --MyComponent.value=<Long>
        Value to use
        Default: -1

    AdvancedComponent(Component) options
    ------------------------------------
    --AdvancedComponent.infile=<Path>
        input file name
        Default: None
    --AdvancedComponent.outfile=<Path>
        output file name
        Default: None
    --AdvancedComponent.value1=<Long>
        Value to use
        Default: -1

    SecondaryMyComponent(MyComponent) options
    -----------------------------------------
    --SecondaryMyComponent.value=<Long>
        Value to use
        Default: -1

    TelescopeWiseComponent(TelescopeComponent) options
    --------------------------------------------------
    --TelescopeWiseComponent.param=<floattelescopeparameter-item-1>...
        Something configurable with telescope patterns.
        Default: [('type', '*', 5.0)]





.. GENERATED FROM PYTHON SOURCE LINES 197-211

Run the tool
------------

here we pass in argv since it is a Notebook, but if argv is not
specified it’s read from ``sys.argv``, so the following is the same as
running:


   mytool --log_level=INFO --infile gamma_test.simtel.gz --iterations=3

As Tools are intended to be executables, they are raising
``SystemExit`` on exit. Here, we use them to demonstrate how it would
work, so we catch the ``SystemExit``.


.. GENERATED FROM PYTHON SOURCE LINES 211-220

.. code-block:: Python
   :lineno-start: 212


    try:
        tool.run(argv=["--infile", str(GAMMA_FILE), "--outfile", "out.csv"])
    except SystemExit as e:
        assert e.code == 0, f"Tool returned with error status {e}"

    tool.log_format = "%(asctime)s : %(levelname)s [%(name)s %(funcName)s] %(message)s"






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    2025-10-23 07:32:38,181 WARNING [__main__.mytool.AdvancedComponent] (command_line_tools.on_outfile_changed): Outfile was changed to '{'name': 'outfile', 'old': None, 'new': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/out.csv'), 'owner': <__main__.AdvancedComponent object at 0x79f08c4b5ed0>, 'type': 'change'}'
    2025-10-23 07:32:38,683 WARNING [__main__.mytool] (command_line_tools.finish): Shutting down.




.. GENERATED FROM PYTHON SOURCE LINES 221-238

.. code-block:: Python
   :lineno-start: 221

    try:
        tool.run(
            argv=[
                "--log-level",
                "INFO",
                "--infile",
                str(GAMMA_FILE),
                "--outfile",
                "out.csv",
                "--iterations",
                "3",
            ]
        )
    except SystemExit as e:
        assert e.code == 0, f"Tool returned with error status {e}"






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    2025-10-23 07:32:38,879 INFO [__main__.mytool] (tool.initialize): Loading config from '[]'
    2025-10-23 07:32:38,881 INFO [__main__.mytool] (tool.initialize): ctapipe version 0.27.1.dev15+g1af6977ab
    2025-10-23 07:32:38,883 WARNING [__main__.mytool.AdvancedComponent] (command_line_tools.on_outfile_changed): Outfile was changed to '{'name': 'outfile', 'old': None, 'new': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/out.csv'), 'owner': <__main__.AdvancedComponent object at 0x79f08c4b7970>, 'type': 'change'}'
    2025-10-23 07:32:38,883 INFO [__main__.mytool] (command_line_tools.start): Performing 3 iterations...
    2025-10-23 07:32:38,883 INFO [__main__.mytool] (command_line_tools.start): ITERATION 0
    2025-10-23 07:32:38,983 INFO [__main__.mytool] (command_line_tools.start): ITERATION 1
    2025-10-23 07:32:39,084 INFO [__main__.mytool] (command_line_tools.start): ITERATION 2
    2025-10-23 07:32:39,184 WARNING [__main__.mytool] (command_line_tools.finish): Shutting down.
    2025-10-23 07:32:39,185 INFO [__main__.mytool] (tool.write_provenance): Output: 
    2025-10-23 07:32:39,185 INFO [__main__.mytool] (tool.write_provenance): Output: 
    2025-10-23 07:32:39,188 INFO [__main__.mytool] (tool.run): Finished mytool




.. GENERATED FROM PYTHON SOURCE LINES 239-241

here we change the log-level to DEBUG:


.. GENERATED FROM PYTHON SOURCE LINES 241-257

.. code-block:: Python
   :lineno-start: 242


    try:
        tool.run(
            argv=[
                "--log-level",
                "DEBUG",
                "--infile",
                str(GAMMA_FILE),
                "--outfile",
                "out.csv",
            ]
        )
    except SystemExit as e:
        assert e.code == 0, f"Tool returned with error status {e}"






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    2025-10-23 07:32:39,188 INFO [__main__.mytool] (tool.run): Starting: mytool
    2025-10-23 07:32:39,382 INFO [__main__.mytool] (tool.initialize): Loading config from '[]'
    2025-10-23 07:32:39,384 INFO [__main__.mytool] (tool.initialize): ctapipe version 0.27.1.dev15+g1af6977ab
    2025-10-23 07:32:39,385 WARNING [__main__.mytool.AdvancedComponent] (command_line_tools.on_outfile_changed): Outfile was changed to '{'name': 'outfile', 'old': None, 'new': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/out.csv'), 'owner': <__main__.AdvancedComponent object at 0x79f08c4b78e0>, 'type': 'change'}'
    2025-10-23 07:32:39,386 DEBUG [__main__.mytool] (tool.run): CONFIG: {'MyTool': {'config_files': [], 'iterations': 3, 'log_config': {}, 'log_datefmt': '%Y-%m-%d %H:%M:%S', 'log_file': None, 'log_file_level': 'INFO', 'log_format': '%(asctime)s : %(levelname)s [%(name)s %(funcName)s] %(message)s', 'log_level': 10, 'logging_config': {}, 'overwrite': False, 'provenance_log': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/docs/mytool.provenance.log'), 'quiet': False, 'show_config': False, 'show_config_json': False, 'MyComponent': {'value': -1}, 'SecondaryMyComponent': {'value': -1}, 'TelescopeWiseComponent': {'param': [('type', '*', 5.0)]}, 'AdvancedComponent': {'infile': PosixPath('/home/docs/.cache/ctapipe/minio-cta.zeuthen.desy.de/dpps-testdata-public/data/ctapipe-test-data/v1.1.0/gamma_prod5.simtel.zst'), 'outfile': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/out.csv'), 'value1': -1, 'MyComponent': {'value': -1}}}}
    2025-10-23 07:32:39,386 INFO [__main__.mytool] (command_line_tools.start): Performing 3 iterations...
    2025-10-23 07:32:39,386 INFO [__main__.mytool] (command_line_tools.start): ITERATION 0
    2025-10-23 07:32:39,386 DEBUG [__main__.mytool.MyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:39,386 DEBUG [__main__.mytool.SecondaryMyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:39,486 INFO [__main__.mytool] (command_line_tools.start): ITERATION 1
    2025-10-23 07:32:39,486 DEBUG [__main__.mytool.MyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:39,486 DEBUG [__main__.mytool.SecondaryMyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:39,587 INFO [__main__.mytool] (command_line_tools.start): ITERATION 2
    2025-10-23 07:32:39,587 DEBUG [__main__.mytool.MyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:39,587 DEBUG [__main__.mytool.SecondaryMyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:39,687 WARNING [__main__.mytool] (command_line_tools.finish): Shutting down.
    2025-10-23 07:32:39,688 INFO [__main__.mytool] (tool.write_provenance): Output: 
    2025-10-23 07:32:39,688 INFO [__main__.mytool] (tool.write_provenance): Output: 
    2025-10-23 07:32:39,688 INFO [__main__.mytool] (tool.write_provenance): Output: 
    2025-10-23 07:32:39,688 DEBUG [__main__.mytool] (tool.write_provenance): PROVENANCE: 'Details about provenance is found in /home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/docs/mytool.provenance.log'
    2025-10-23 07:32:39,692 INFO [__main__.mytool] (tool.run): Finished mytool
    2025-10-23 07:32:39,692 DEBUG [__main__.mytool] (application.exit): Exiting application: mytool




.. GENERATED FROM PYTHON SOURCE LINES 258-262

you can also set parameters directly in the class, rather than using the
argument/configfile parser. This is useful if you are calling the Tool
from a script rather than the command-line


.. GENERATED FROM PYTHON SOURCE LINES 262-272

.. code-block:: Python
   :lineno-start: 263


    tool.iterations = 1
    tool.log_level = 0

    try:
        tool.run(["--infile", str(GAMMA_FILE), "--outfile", "out.csv"])
    except SystemExit as e:
        assert e.code == 0, f"Tool returned with error status {e}"






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    2025-10-23 07:32:39,693 INFO [__main__.mytool] (tool.run): Starting: mytool
    2025-10-23 07:32:39,889 WARNING [__main__.mytool.AdvancedComponent] (command_line_tools.on_outfile_changed): Outfile was changed to '{'name': 'outfile', 'old': None, 'new': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/out.csv'), 'owner': <__main__.AdvancedComponent object at 0x79f09fae65f0>, 'type': 'change'}'
    2025-10-23 07:32:39,989 WARNING [__main__.mytool] (command_line_tools.finish): Shutting down.




.. GENERATED FROM PYTHON SOURCE LINES 273-275

see what happens when a value is set that is not of the correct type:


.. GENERATED FROM PYTHON SOURCE LINES 275-284

.. code-block:: Python
   :lineno-start: 276


    try:
        tool.iterations = "badval"
    except TraitError as E:
        print("bad value:", E)
    except SystemExit as e:
        assert e.code == 0, f"Tool returned with error status {e}"






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    bad value: The 'iterations' trait of a MyTool instance expected an int, not the str 'badval'.




.. GENERATED FROM PYTHON SOURCE LINES 285-288

Example of what happens when you change a parameter that is being
“observed” in a class. It’s handler is called:


.. GENERATED FROM PYTHON SOURCE LINES 288-292

.. code-block:: Python
   :lineno-start: 289


    tool.advanced.outfile = "Another.txt"






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    2025-10-23 07:32:39,995 WARNING [__main__.mytool.AdvancedComponent] (command_line_tools.on_outfile_changed): Outfile was changed to '{'name': 'outfile', 'old': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/out.csv'), 'new': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/Another.txt'), 'owner': <__main__.AdvancedComponent object at 0x79f09fae65f0>, 'type': 'change'}'




.. GENERATED FROM PYTHON SOURCE LINES 293-296

we see that the handler for ``outfile`` was called, and it receive a
change dict that shows the old and new values.


.. GENERATED FROM PYTHON SOURCE LINES 299-301

create a tool using a config file:


.. GENERATED FROM PYTHON SOURCE LINES 301-304

.. code-block:: Python
   :lineno-start: 302


    tool2 = MyTool()








.. GENERATED FROM PYTHON SOURCE LINES 305-310

.. code-block:: Python
   :lineno-start: 305

    try:
        tool2.run(argv=["--config", "config.json"])
    except SystemExit as e:
        assert e.code == 0, f"Tool returned with error status {e}"





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    2025-10-23 07:32:40,192 INFO [__main__.mytool] (tool.initialize): ctapipe version 0.27.1.dev15+g1af6977ab
    2025-10-23 07:32:40,194 WARNING [__main__.mytool.AdvancedComponent] (command_line_tools.on_outfile_changed): Outfile was changed to '{'name': 'outfile', 'old': None, 'new': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/foo.txt'), 'owner': <__main__.AdvancedComponent object at 0x79f08ae15d20>, 'type': 'change'}'
    2025-10-23 07:32:40,194 DEBUG [__main__.mytool] (tool.run): CONFIG: {'MyTool': {'config_files': [PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/config.json')], 'iterations': 5, 'log_config': {}, 'log_datefmt': '%Y-%m-%d %H:%M:%S', 'log_file': None, 'log_file_level': 'INFO', 'log_format': '[%(name)s]%(highlevel)s %(message)s', 'log_level': 10, 'logging_config': {}, 'overwrite': False, 'provenance_log': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/mytool.provenance.log'), 'quiet': False, 'show_config': False, 'show_config_json': False, 'MyComponent': {'value': -1}, 'SecondaryMyComponent': {'value': -1}, 'TelescopeWiseComponent': {'param': [('type', '*', 5.0)]}, 'AdvancedComponent': {'infile': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/something.txt'), 'outfile': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/foo.txt'), 'value1': -1, 'MyComponent': {'value': -1}}}}
    2025-10-23 07:32:40,194 INFO [__main__.mytool] (command_line_tools.start): Performing 5 iterations...
    2025-10-23 07:32:40,194 INFO [__main__.mytool] (command_line_tools.start): ITERATION 0
    2025-10-23 07:32:40,194 DEBUG [__main__.mytool.MyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:40,194 DEBUG [__main__.mytool.SecondaryMyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:40,295 INFO [__main__.mytool] (command_line_tools.start): ITERATION 1
    2025-10-23 07:32:40,295 DEBUG [__main__.mytool.MyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:40,295 DEBUG [__main__.mytool.SecondaryMyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:40,395 INFO [__main__.mytool] (command_line_tools.start): ITERATION 2
    2025-10-23 07:32:40,395 DEBUG [__main__.mytool.MyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:40,395 DEBUG [__main__.mytool.SecondaryMyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:40,495 INFO [__main__.mytool] (command_line_tools.start): ITERATION 3
    2025-10-23 07:32:40,496 DEBUG [__main__.mytool.MyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:40,496 DEBUG [__main__.mytool.SecondaryMyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:40,596 INFO [__main__.mytool] (command_line_tools.start): ITERATION 4
    2025-10-23 07:32:40,596 DEBUG [__main__.mytool.MyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:40,596 DEBUG [__main__.mytool.SecondaryMyComponent] (command_line_tools.do_thing): Did thing
    2025-10-23 07:32:40,696 WARNING [__main__.mytool] (command_line_tools.finish): Shutting down.
    2025-10-23 07:32:40,698 INFO [__main__.mytool] (tool.write_provenance): Output: 
    2025-10-23 07:32:40,698 INFO [__main__.mytool] (tool.write_provenance): Output: 
    2025-10-23 07:32:40,698 INFO [__main__.mytool] (tool.write_provenance): Output: 
    2025-10-23 07:32:40,698 INFO [__main__.mytool] (tool.write_provenance): Output: 
    2025-10-23 07:32:40,698 INFO [__main__.mytool] (tool.write_provenance): Output: 
    2025-10-23 07:32:40,698 DEBUG [__main__.mytool] (tool.write_provenance): PROVENANCE: 'Details about provenance is found in /home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/mytool.provenance.log'
    2025-10-23 07:32:40,703 INFO [__main__.mytool] (tool.run): Finished mytool
    2025-10-23 07:32:40,703 DEBUG [__main__.mytool] (application.exit): Exiting application: mytool




.. GENERATED FROM PYTHON SOURCE LINES 311-313

.. code-block:: Python
   :lineno-start: 311

    print(tool2.advanced.infile)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    /home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/something.txt




.. GENERATED FROM PYTHON SOURCE LINES 314-316

.. code-block:: Python
   :lineno-start: 314

    print(tool2.config)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    {'MyTool': {'config_files': ['config.json'], 'log_level': 'DEBUG'}, 'AdvancedComponent': {'infile': 'something.txt', 'outfile': 'foo.txt'}}




.. GENERATED FROM PYTHON SOURCE LINES 317-319

.. code-block:: Python
   :lineno-start: 317

    tool2.is_setup





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    True



.. GENERATED FROM PYTHON SOURCE LINES 320-322

.. code-block:: Python
   :lineno-start: 320

    tool3 = MyTool()








.. GENERATED FROM PYTHON SOURCE LINES 323-325

.. code-block:: Python
   :lineno-start: 323

    tool3.is_setup





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    False



.. GENERATED FROM PYTHON SOURCE LINES 326-328

.. code-block:: Python
   :lineno-start: 326

    tool3.initialize(argv=[])








.. GENERATED FROM PYTHON SOURCE LINES 329-331

.. code-block:: Python
   :lineno-start: 329

    tool3.is_setup





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    False



.. GENERATED FROM PYTHON SOURCE LINES 332-334

.. code-block:: Python
   :lineno-start: 332

    tool3






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div style="border:1px solid black; max-width: 700px; padding:2em; word-wrap:break-word;">
    <b>MyTool</b>
    <div class="document">
    <p>do some things and stuff</p>
    </div>

    <table>
        <colgroup>
            <col span='1' style=' '>
            <col span='1' style='width: 20em;'>
            <col span='1' >
        </colgroup>
        <tbody>
    <tr><th>config_files</th>
    <td style='text-align: left;'><span style='color:blue; max-width:30em;'>[]</span></td>
    <td style='text-align: left;'><i>List of configuration files with parameters to load in addition to command-line parameters. The order listed is the order of precedence (later config parameters overwrite earlier ones), however parameters specified on the command line always have the highest precedence. Config files may be in JSON, YAML, TOML, or Python format (default: traitlets.Undefined)</i></td></tr>
    <tr><th>iterations</th>
    <td style='text-align: left;'>5</td>
    <td style='text-align: left;'><i>Number of times to run (default: 5)</i></td></tr>
    <tr><th>log_config</th>
    <td style='text-align: left;'><span style='color:blue; max-width:30em;'>{}</span></td>
    <td style='text-align: left;'><i> (default: traitlets.Undefined)</i></td></tr>
    <tr><th>log_datefmt</th>
    <td style='text-align: left;'>%Y-%m-%d %H:%M:%S</td>
    <td style='text-align: left;'><i>The date format used by logging formatters for %(asctime)s (default: %Y-%m-%d %H:%M:%S)</i></td></tr>
    <tr><th>log_file</th>
    <td style='text-align: left;'>None</td>
    <td style='text-align: left;'><i>Filename for the log (default: None)</i></td></tr>
    <tr><th>log_file_level</th>
    <td style='text-align: left;'>INFO</td>
    <td style='text-align: left;'><i>Logging Level for File Logging (default: INFO)</i></td></tr>
    <tr><th>log_format</th>
    <td style='text-align: left;'>[%(name)s]%(highlevel)s %(message)s</td>
    <td style='text-align: left;'><i>The Logging format template (default: [%(name)s]%(highlevel)s %(message)s)</i></td></tr>
    <tr><th>log_level</th>
    <td style='text-align: left;'>30</td>
    <td style='text-align: left;'><i>Set the log level by value or name. (default: 30)</i></td></tr>
    <tr><th>logging_config</th>
    <td style='text-align: left;'><span style='color:blue; max-width:30em;'>{}</span></td>
    <td style='text-align: left;'><i>
                Configure additional log handlers.

                The default stderr logs handler is configured by the
                log_level, log_datefmt and log_format settings.

                This configuration can be used to configure additional handlers
                (e.g. to output the log to a file) or for finer control over the
                default handlers.

                If provided this should be a logging configuration dictionary, for
                more information see:
                https://docs.python.org/3/library/logging.config.html#logging-config-dictschema

                This dictionary is merged with the base logging configuration which
                defines the following:

                * A logging formatter intended for interactive use called
                  ``console``.
                * A logging handler that writes to stderr called
                  ``console`` which uses the formatter ``console``.
                * A logger with the name of this application set to ``DEBUG``
                  level.

                This example adds a new handler that writes to a file:

                .. code-block:: python

                   c.Application.logging_config = {
                       &quot;handlers&quot;: {
                           &quot;file&quot;: {
                               &quot;class&quot;: &quot;logging.FileHandler&quot;,
                               &quot;level&quot;: &quot;DEBUG&quot;,
                               &quot;filename&quot;: &quot;&lt;path/to/file&gt;&quot;,
                           }
                       },
                       &quot;loggers&quot;: {
                           &quot;&lt;application-name&gt;&quot;: {
                               &quot;level&quot;: &quot;DEBUG&quot;,
                               # NOTE: if you don&#x27;t list the default &quot;console&quot;
                               # handler here then it will be disabled
                               &quot;handlers&quot;: [&quot;console&quot;, &quot;file&quot;],
                           },
                       },
                   }

             (default: traitlets.Undefined)</i></td></tr>
    <tr><th>overwrite</th>
    <td style='text-align: left;'>False</td>
    <td style='text-align: left;'><i> (default: False)</i></td></tr>
    <tr><th>provenance_log</th>
    <td style='text-align: left;'><span style='color:blue; max-width:30em;'>/<wbr>home/<wbr>docs/<wbr>checkouts/<wbr>readthedocs.org/<wbr>user_<wbr>builds/<wbr>ctapipe/<wbr>checkouts/<wbr>2868/<wbr>docs/<wbr>mytool.provenance.log</span></td>
    <td style='text-align: left;'><i> (default: None)</i></td></tr>
    <tr><th>quiet</th>
    <td style='text-align: left;'>False</td>
    <td style='text-align: left;'><i> (default: False)</i></td></tr>
    <tr><th>show_config</th>
    <td style='text-align: left;'>False</td>
    <td style='text-align: left;'><i>Instead of starting the Application, dump configuration to stdout (default: False)</i></td></tr>
    <tr><th>show_config_json</th>
    <td style='text-align: left;'>False</td>
    <td style='text-align: left;'><i>Instead of starting the Application, dump configuration to stdout (as JSON) (default: False)</i></td></tr>
        </tbody>
    </table>
    <p><b>Components:</b>
    MyTool, MyComponent, AdvancedComponent, SecondaryMyComponent, TelescopeWiseComponent
    </p>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 335-338

.. code-block:: Python
   :lineno-start: 335

    tool.setup()
    tool





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    2025-10-23 07:32:40,713 WARNING [__main__.mytool.AdvancedComponent] (command_line_tools.on_outfile_changed): Outfile was changed to '{'name': 'outfile', 'old': None, 'new': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/out.csv'), 'owner': <__main__.AdvancedComponent object at 0x79f09fae5f00>, 'type': 'change'}'


.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div style="border:1px solid black; max-width: 700px; padding:2em; word-wrap:break-word;">
    <b>MyTool</b>
    <div class="document">
    <p>do some things and stuff</p>
    </div>

    <table>
        <colgroup>
            <col span='1' style=' '>
            <col span='1' style='width: 20em;'>
            <col span='1' >
        </colgroup>
        <tbody>
    <tr><th>config_files</th>
    <td style='text-align: left;'><span style='color:blue; max-width:30em;'>[]</span></td>
    <td style='text-align: left;'><i>List of configuration files with parameters to load in addition to command-line parameters. The order listed is the order of precedence (later config parameters overwrite earlier ones), however parameters specified on the command line always have the highest precedence. Config files may be in JSON, YAML, TOML, or Python format (default: traitlets.Undefined)</i></td></tr>
    <tr><th>iterations</th>
    <td style='text-align: left;'><span style='color:blue; max-width:30em;'>1</span></td>
    <td style='text-align: left;'><i>Number of times to run (default: 5)</i></td></tr>
    <tr><th>log_config</th>
    <td style='text-align: left;'><span style='color:blue; max-width:30em;'>{}</span></td>
    <td style='text-align: left;'><i> (default: traitlets.Undefined)</i></td></tr>
    <tr><th>log_datefmt</th>
    <td style='text-align: left;'>%Y-%m-%d %H:%M:%S</td>
    <td style='text-align: left;'><i>The date format used by logging formatters for %(asctime)s (default: %Y-%m-%d %H:%M:%S)</i></td></tr>
    <tr><th>log_file</th>
    <td style='text-align: left;'>None</td>
    <td style='text-align: left;'><i>Filename for the log (default: None)</i></td></tr>
    <tr><th>log_file_level</th>
    <td style='text-align: left;'>INFO</td>
    <td style='text-align: left;'><i>Logging Level for File Logging (default: INFO)</i></td></tr>
    <tr><th>log_format</th>
    <td style='text-align: left;'><span style='color:blue; max-width:30em;'>%(asctime)s : %(levelname)s [%(name)s %(funcName)s] %(message)s</span></td>
    <td style='text-align: left;'><i>The Logging format template (default: [%(name)s]%(highlevel)s %(message)s)</i></td></tr>
    <tr><th>log_level</th>
    <td style='text-align: left;'><span style='color:blue; max-width:30em;'>0</span></td>
    <td style='text-align: left;'><i>Set the log level by value or name. (default: 30)</i></td></tr>
    <tr><th>logging_config</th>
    <td style='text-align: left;'><span style='color:blue; max-width:30em;'>{}</span></td>
    <td style='text-align: left;'><i>
                Configure additional log handlers.

                The default stderr logs handler is configured by the
                log_level, log_datefmt and log_format settings.

                This configuration can be used to configure additional handlers
                (e.g. to output the log to a file) or for finer control over the
                default handlers.

                If provided this should be a logging configuration dictionary, for
                more information see:
                https://docs.python.org/3/library/logging.config.html#logging-config-dictschema

                This dictionary is merged with the base logging configuration which
                defines the following:

                * A logging formatter intended for interactive use called
                  ``console``.
                * A logging handler that writes to stderr called
                  ``console`` which uses the formatter ``console``.
                * A logger with the name of this application set to ``DEBUG``
                  level.

                This example adds a new handler that writes to a file:

                .. code-block:: python

                   c.Application.logging_config = {
                       &quot;handlers&quot;: {
                           &quot;file&quot;: {
                               &quot;class&quot;: &quot;logging.FileHandler&quot;,
                               &quot;level&quot;: &quot;DEBUG&quot;,
                               &quot;filename&quot;: &quot;&lt;path/to/file&gt;&quot;,
                           }
                       },
                       &quot;loggers&quot;: {
                           &quot;&lt;application-name&gt;&quot;: {
                               &quot;level&quot;: &quot;DEBUG&quot;,
                               # NOTE: if you don&#x27;t list the default &quot;console&quot;
                               # handler here then it will be disabled
                               &quot;handlers&quot;: [&quot;console&quot;, &quot;file&quot;],
                           },
                       },
                   }

             (default: traitlets.Undefined)</i></td></tr>
    <tr><th>overwrite</th>
    <td style='text-align: left;'>False</td>
    <td style='text-align: left;'><i> (default: False)</i></td></tr>
    <tr><th>provenance_log</th>
    <td style='text-align: left;'><span style='color:blue; max-width:30em;'>/<wbr>home/<wbr>docs/<wbr>checkouts/<wbr>readthedocs.org/<wbr>user_<wbr>builds/<wbr>ctapipe/<wbr>checkouts/<wbr>2868/<wbr>docs/<wbr>mytool.provenance.log</span></td>
    <td style='text-align: left;'><i> (default: None)</i></td></tr>
    <tr><th>quiet</th>
    <td style='text-align: left;'>False</td>
    <td style='text-align: left;'><i> (default: False)</i></td></tr>
    <tr><th>show_config</th>
    <td style='text-align: left;'>False</td>
    <td style='text-align: left;'><i>Instead of starting the Application, dump configuration to stdout (default: False)</i></td></tr>
    <tr><th>show_config_json</th>
    <td style='text-align: left;'>False</td>
    <td style='text-align: left;'><i>Instead of starting the Application, dump configuration to stdout (as JSON) (default: False)</i></td></tr>
        </tbody>
    </table>
    <p><b>Components:</b>
    MyTool, MyComponent, AdvancedComponent, SecondaryMyComponent, TelescopeWiseComponent
    </p>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 339-342

.. code-block:: Python
   :lineno-start: 339

    tool.comp2







.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div style="border:1px solid black; max-width: 700px; padding:2em; word-wrap:break-word;">
    <b>SecondaryMyComponent</b>
    <div class="document">
    <p>A second component</p>
    </div>

    <table>
        <colgroup>
            <col span='1' style=' '>
            <col span='1' style='width: 20em;'>
            <col span='1' >
        </colgroup>
        <tbody>
    <tr><th>value</th>
    <td style="text-align: left;">-1</td>
    <td style="text-align: left;"><i>Value to use (default: -1)</i></td></tr>
        </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 343-346

Getting the configuration of an instance
----------------------------------------


.. GENERATED FROM PYTHON SOURCE LINES 346-349

.. code-block:: Python
   :lineno-start: 347


    tool.get_current_config()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    {'MyTool': {'config_files': [], 'iterations': 1, 'log_config': {}, 'log_datefmt': '%Y-%m-%d %H:%M:%S', 'log_file': None, 'log_file_level': 'INFO', 'log_format': '%(asctime)s : %(levelname)s [%(name)s %(funcName)s] %(message)s', 'log_level': 0, 'logging_config': {}, 'overwrite': False, 'provenance_log': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/docs/mytool.provenance.log'), 'quiet': False, 'show_config': False, 'show_config_json': False, 'MyComponent': {'value': -1}, 'SecondaryMyComponent': {'value': -1}, 'TelescopeWiseComponent': {'param': [('type', '*', 5.0)]}, 'AdvancedComponent': {'infile': PosixPath('/home/docs/.cache/ctapipe/minio-cta.zeuthen.desy.de/dpps-testdata-public/data/ctapipe-test-data/v1.1.0/gamma_prod5.simtel.zst'), 'outfile': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/out.csv'), 'value1': -1, 'MyComponent': {'value': -1}}}}



.. GENERATED FROM PYTHON SOURCE LINES 350-354

.. code-block:: Python
   :lineno-start: 350

    tool.iterations = 12
    tool.get_current_config()






.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    {'MyTool': {'config_files': [], 'iterations': 12, 'log_config': {}, 'log_datefmt': '%Y-%m-%d %H:%M:%S', 'log_file': None, 'log_file_level': 'INFO', 'log_format': '%(asctime)s : %(levelname)s [%(name)s %(funcName)s] %(message)s', 'log_level': 0, 'logging_config': {}, 'overwrite': False, 'provenance_log': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/docs/mytool.provenance.log'), 'quiet': False, 'show_config': False, 'show_config_json': False, 'MyComponent': {'value': -1}, 'SecondaryMyComponent': {'value': -1}, 'TelescopeWiseComponent': {'param': [('type', '*', 5.0)]}, 'AdvancedComponent': {'infile': PosixPath('/home/docs/.cache/ctapipe/minio-cta.zeuthen.desy.de/dpps-testdata-public/data/ctapipe-test-data/v1.1.0/gamma_prod5.simtel.zst'), 'outfile': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/ctapipe/checkouts/2868/examples/core/out.csv'), 'value1': -1, 'MyComponent': {'value': -1}}}}



.. GENERATED FROM PYTHON SOURCE LINES 355-358

Writing a Sample Config File
----------------------------


.. GENERATED FROM PYTHON SOURCE LINES 358-360

.. code-block:: Python
   :lineno-start: 359


    print(tool.generate_config_file())




.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    # Configuration file for mytool.

    c = get_config()  #noqa

    #------------------------------------------------------------------------------
    # Application(SingletonConfigurable) configuration
    #------------------------------------------------------------------------------
    ## This is an application.

    ## The date format used by logging formatters for %(asctime)s
    #  Default: '%Y-%m-%d %H:%M:%S'
    # c.Application.log_datefmt = '%Y-%m-%d %H:%M:%S'

    ## The Logging format template
    #  Default: '[%(name)s]%(highlevel)s %(message)s'
    # c.Application.log_format = '[%(name)s]%(highlevel)s %(message)s'

    ## Set the log level by value or name.
    #  Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
    #  Default: 30
    # c.Application.log_level = 30

    ## Configure additional log handlers.
    #  
    #  The default stderr logs handler is configured by the log_level, log_datefmt
    #  and log_format settings.
    #  
    #  This configuration can be used to configure additional handlers (e.g. to
    #  output the log to a file) or for finer control over the default handlers.
    #  
    #  If provided this should be a logging configuration dictionary, for more
    #  information see:
    #  https://docs.python.org/3/library/logging.config.html#logging-config-
    #  dictschema
    #  
    #  This dictionary is merged with the base logging configuration which defines
    #  the following:
    #  
    #  * A logging formatter intended for interactive use called
    #    ``console``.
    #  * A logging handler that writes to stderr called
    #    ``console`` which uses the formatter ``console``.
    #  * A logger with the name of this application set to ``DEBUG``
    #    level.
    #  
    #  This example adds a new handler that writes to a file:
    #  
    #  .. code-block:: python
    #  
    #     c.Application.logging_config = {
    #         "handlers": {
    #             "file": {
    #                 "class": "logging.FileHandler",
    #                 "level": "DEBUG",
    #                 "filename": "<path/to/file>",
    #             }
    #         },
    #         "loggers": {
    #             "<application-name>": {
    #                 "level": "DEBUG",
    #                 # NOTE: if you don't list the default "console"
    #                 # handler here then it will be disabled
    #                 "handlers": ["console", "file"],
    #             },
    #         },
    #     }
    #  Default: {}
    # c.Application.logging_config = {}

    ## Instead of starting the Application, dump configuration to stdout
    #  Default: False
    # c.Application.show_config = False

    ## Instead of starting the Application, dump configuration to stdout (as JSON)
    #  Default: False
    # c.Application.show_config_json = False

    #------------------------------------------------------------------------------
    # Tool(Application) configuration
    #------------------------------------------------------------------------------
    ## This is an application.

    ## List of configuration files with parameters to load in addition to command-
    #  line parameters. The order listed is the order of precedence (later config
    #  parameters overwrite earlier ones), however parameters specified on the
    #  command line always have the highest precedence. Config files may be in JSON,
    #  YAML, TOML, or Python format
    #  Default: []
    # c.Tool.config_files = []

    #  Default: {}
    # c.Tool.log_config = {}

    ## The date format used by logging formatters for %(asctime)s
    #  See also: Application.log_datefmt
    # c.Tool.log_datefmt = '%Y-%m-%d %H:%M:%S'

    ## Filename for the log
    #  Default: None
    # c.Tool.log_file = None

    ## Logging Level for File Logging
    #  Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']
    #  Default: 'INFO'
    # c.Tool.log_file_level = 'INFO'

    ## The Logging format template
    #  See also: Application.log_format
    # c.Tool.log_format = '[%(name)s]%(highlevel)s %(message)s'

    ## Set the log level by value or name.
    #  See also: Application.log_level
    # c.Tool.log_level = 30

    ## 
    #  See also: Application.logging_config
    # c.Tool.logging_config = {}

    #  Default: False
    # c.Tool.overwrite = False

    #  Default: None
    # c.Tool.provenance_log = None

    #  Default: False
    # c.Tool.quiet = False

    ## Instead of starting the Application, dump configuration to stdout
    #  See also: Application.show_config
    # c.Tool.show_config = False

    ## Instead of starting the Application, dump configuration to stdout (as JSON)
    #  See also: Application.show_config_json
    # c.Tool.show_config_json = False

    #------------------------------------------------------------------------------
    # MyTool(Tool) configuration
    #------------------------------------------------------------------------------
    ## List of configuration files with parameters to load in addition to command-
    #  line parameters. The order listed is the order of precedence (later config
    #  parameters overwrite earlier ones), however parameters specified on the
    #  command line always have the highest precedence. Config files may be in JSON,
    #  YAML, TOML, or Python format
    #  See also: Tool.config_files
    # c.MyTool.config_files = []

    ## Number of times to run
    #  Default: 5
    # c.MyTool.iterations = 5

    #  See also: Tool.log_config
    # c.MyTool.log_config = {}

    ## The date format used by logging formatters for %(asctime)s
    #  See also: Application.log_datefmt
    # c.MyTool.log_datefmt = '%Y-%m-%d %H:%M:%S'

    ## Filename for the log
    #  See also: Tool.log_file
    # c.MyTool.log_file = None

    ## Logging Level for File Logging
    #  See also: Tool.log_file_level
    # c.MyTool.log_file_level = 'INFO'

    ## The Logging format template
    #  See also: Application.log_format
    # c.MyTool.log_format = '[%(name)s]%(highlevel)s %(message)s'

    ## Set the log level by value or name.
    #  See also: Application.log_level
    # c.MyTool.log_level = 30

    ## 
    #  See also: Application.logging_config
    # c.MyTool.logging_config = {}

    #  See also: Tool.overwrite
    # c.MyTool.overwrite = False

    #  See also: Tool.provenance_log
    # c.MyTool.provenance_log = None

    #  See also: Tool.quiet
    # c.MyTool.quiet = False

    ## Instead of starting the Application, dump configuration to stdout
    #  See also: Application.show_config
    # c.MyTool.show_config = False

    ## Instead of starting the Application, dump configuration to stdout (as JSON)
    #  See also: Application.show_config_json
    # c.MyTool.show_config_json = False

    #------------------------------------------------------------------------------
    # MyComponent(Component) configuration
    #------------------------------------------------------------------------------
    ## A Component that does stuff

    ## Value to use
    #  Default: -1
    # c.MyComponent.value = -1

    #------------------------------------------------------------------------------
    # AdvancedComponent(Component) configuration
    #------------------------------------------------------------------------------
    ## An advanced technique

    ## input file name
    #  Default: None
    # c.AdvancedComponent.infile = None

    ## output file name
    #  Default: None
    # c.AdvancedComponent.outfile = None

    ## Value to use
    #  Default: -1
    # c.AdvancedComponent.value1 = -1

    #------------------------------------------------------------------------------
    # SecondaryMyComponent(MyComponent) configuration
    #------------------------------------------------------------------------------
    ## A second component

    ## Value to use
    #  See also: MyComponent.value
    # c.SecondaryMyComponent.value = -1

    #------------------------------------------------------------------------------
    # TelescopeWiseComponent(TelescopeComponent) configuration
    #------------------------------------------------------------------------------
    ## a component that contains parameters that are per-telescope configurable

    ## Something configurable with telescope patterns.
    #  Default: [('type', '*', 5.0)]
    # c.TelescopeWiseComponent.param = [('type', '*', 5.0)]






.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 3.766 seconds)


.. _sphx_glr_download_auto_examples_core_command_line_tools.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: command_line_tools.ipynb <command_line_tools.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: command_line_tools.py <command_line_tools.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: command_line_tools.zip <command_line_tools.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_