Debian Codegraph @

docs/source/design/cli.rst

raw
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.