| 1 |
.. -*- mode: rst -*- |
| 2 |
.. vi: set ft=rst sts=4 ts=4 sw=4 et tw=79: |
| 3 |
|
| 4 |
.. _chap_design_cli: |
| 5 |
|
| 6 |
********************** |
| 7 |
Command line interface |
| 8 |
********************** |
| 9 |
|
| 10 |
.. topic:: Specification scope and status |
| 11 |
|
| 12 |
This incomplete specification describes the current implementation. |
| 13 |
|
| 14 |
The command line interface (CLI) implementation is located at ``datalad.cli``. |
| 15 |
It provides a console entry point that automatically constructs an |
| 16 |
``argparse``-based command line parser, which is used to make adequately |
| 17 |
parameterized calls to the targeted command implementations. It also performs |
| 18 |
error handling. The CLI automatically supports all commands, regardless of |
| 19 |
whether they are provided by the core package, or by extensions. It only |
| 20 |
requires them to be discoverable via the respective extension entry points, |
| 21 |
and to implement the standard :class:`datalad.interface.base.Interface`. |
| 22 |
|
| 23 |
|
| 24 |
Basic workflow of a command line based command execution |
| 25 |
======================================================== |
| 26 |
|
| 27 |
The functionality of the main command line entrypoint described here is |
| 28 |
implemented in ``datalad.cli.main``. |
| 29 |
|
| 30 |
1. Construct an ``argparse`` parser. |
| 31 |
|
| 32 |
- this is happening with inspection of the actual command line arguments |
| 33 |
in order to avoid needless processing |
| 34 |
|
| 35 |
- when insufficient arguments or other errors are detected, the CLI will |
| 36 |
fail informatively already at this stage |
| 37 |
|
| 38 |
2. Detect argument completions events, and utilize the parser in a optimized |
| 39 |
fashion for this purpose. |
| 40 |
|
| 41 |
3. Determine the to-be-executed command from the given command line arguments. |
| 42 |
|
| 43 |
4. Read any configuration overrides from the command line arguments. |
| 44 |
|
| 45 |
5. Change the process working directory, if requested. |
| 46 |
|
| 47 |
6. Execute the target command in one of two modes: |
| 48 |
|
| 49 |
a. With a basic exception handler |
| 50 |
|
| 51 |
b. With an exception hook setup that enables dropping into a debugger |
| 52 |
for any exception that reaches the command line ``main()`` routine. |
| 53 |
|
| 54 |
7. Unless a debugger is utilized, five error categories are distinguished |
| 55 |
(in the order given below): |
| 56 |
|
| 57 |
1. Insufficient arguments (exit code 2) |
| 58 |
|
| 59 |
A command was called with inadequate or incomplete parameters. |
| 60 |
|
| 61 |
2. Incomplete results (exit code 1) |
| 62 |
|
| 63 |
While processing an error occurred. |
| 64 |
|
| 65 |
3. A specific internal shell command execution failed (exit code relayed |
| 66 |
from underlying command) |
| 67 |
|
| 68 |
The error is reported, as if the command would have been executed |
| 69 |
directly in the command line. Its output is written to the ``stdout``, |
| 70 |
``stderr`` streams, and the exit code of the DataLad process matches |
| 71 |
the exit code of the underlying command. |
| 72 |
|
| 73 |
4. Keyboard interrupt (exit code 3) |
| 74 |
|
| 75 |
The process was interrupted by the equivalent of a user hitting |
| 76 |
``Ctrl+C``. |
| 77 |
|
| 78 |
5. Any other error/exception. |
| 79 |
|
| 80 |
|
| 81 |
Command parser construction by ``Interface`` inspection |
| 82 |
======================================================= |
| 83 |
|
| 84 |
The parser setup described here is implemented in ``datalad.cli.parser``. |
| 85 |
|
| 86 |
A dedicated sub-parser for any relevant DataLad command is constructed. For |
| 87 |
normal execution use cases, only a single subparser for the target command |
| 88 |
will be constructed for speed reasons. However, when the command line help |
| 89 |
system is requested (``--help``) subparsers for all commands (including |
| 90 |
extensions) are constructed. This can take a considerable amount of time |
| 91 |
that grows with the number of installed extensions. |
| 92 |
|
| 93 |
The information necessary to configure a subparser for a DataLad command is |
| 94 |
determined by inspecting the respective |
| 95 |
:class:`~datalad.interface.base.Interface` class for that command, and reusing |
| 96 |
individual components for the parser. This includes: |
| 97 |
|
| 98 |
- the class docstring |
| 99 |
|
| 100 |
- a ``_params_`` member with a dict of parameter definitions |
| 101 |
|
| 102 |
- a ``_examples_`` member, with a list of example definitions |
| 103 |
|
| 104 |
All docstrings used for the parser setup will be processed by applying a |
| 105 |
set of rules to make them more suitable for the command line environment. |
| 106 |
This includes the processing of ``CMD`` markup macros, and stripping their |
| 107 |
``PYTHON`` counter parts. Parameter constraint definition descriptions |
| 108 |
are also altered to exclude Python-specific idioms that have no relevance |
| 109 |
on the command line (e.g., the specification of ``None`` as a default). |
| 110 |
|
| 111 |
|
| 112 |
CLI-based execution of ``Interface`` command |
| 113 |
============================================ |
| 114 |
|
| 115 |
The execution handler described here is implemented in ``datalad.cli.exec``. |
| 116 |
|
| 117 |
Once the main command line entry point determine that a command shall be |
| 118 |
executed, it triggers a handler function that was assigned and parameterized |
| 119 |
with the underlying command :class:`~datalad.interface.base.Interface` during |
| 120 |
parser construction. At the time of execution, this handler is given the result |
| 121 |
of ``argparse``-based command line argument parsing (i.e., a ``Namespace`` |
| 122 |
instance). |
| 123 |
|
| 124 |
From this parser result, the handler constructs positional and keyword |
| 125 |
arguments for the respective ``Interface.__call__()`` execution. It does |
| 126 |
not only process command-specific arguments, but also generic arguments, |
| 127 |
such as those for result filtering and rendering, which influence the central |
| 128 |
processing of result recorded yielded by a command. |
| 129 |
|
| 130 |
If an underlying command returns a Python generator it is unwound to trigger |
| 131 |
the respective underlying processing. The handler performs no error handling. |
| 132 |
This is left to the main command line entry point. |