Debian Codegraph @

docs/source/design/user_messaging.rst

raw
1 .. -*- mode: rst -*-
2 .. vi: set ft=rst sts=4 ts=4 sw=4 et tw=79:
3
4 .. _chap_design_user_messaging:
5
6 *******************************************************
7 User messaging: result records vs exceptions vs logging
8 *******************************************************
9
10 .. topic:: Specification scope and status
11
12 This specification provides a partial overview of the implementation goal.
13
14 Motivation
15 ==========
16
17 This specification delineates the applicable contexts for using
18 :ref:`result records <chap_design_result_records>`, :ref:`exceptions <chap_design_exception_handling>`,
19 :ref:`progress reporting <chap_design_progress_reporting>`, specific :ref:`log levels <chap_design_log_levels>`,
20 or other types of user messaging processes.
21
22
23 Specification
24 =============
25
26 Result records
27 --------------
28
29 **Result records are the only return value format** for all DataLad interfaces.
30
31 Contrasting with classic Python interfaces that return specific non-annotated values,
32 DataLad interfaces (i.e. subclasses of :py:class:`datalad.interface.base.Interface`)
33 implement message passing by yielding :ref:`result records <chap_design_result_records>`
34 that are associated with individual operations. Result records are routinely inspected throughout
35 the code base and their annotations are used to inform general program flow and error handling.
36
37 DataLad interface calls can include an ``on_failure`` parameterization to specify how to
38 proceed with a particular operation if a returned result record is
39 :ref:`classified as a failure result <target-result-status>`. DataLad interface calls can
40 also include a ``result_renderer`` parameterization to explicitly enable or
41 disable the rendering of result records.
42
43 Developers should be aware that external callers will use DataLad interface call parameterizations
44 that can selectively ignore or act on result records, and that the process should therefore
45 yield meaningful result records. If, in turn, the process itself receives a set of result
46 records from a sub-process, these should be inspected individually in order to identify result
47 values that could require re-annotation or status re-classification.
48
49 For user messaging purposes, result records can also be enriched with additional human-readable
50 information on the nature of the result, via the ``message`` key, and human-readable hints to
51 the user, via the ``hints`` key. Both of these are rendered via the `UI Module`_.
52
53
54 Exception handling
55 ------------------
56
57 In general, **exceptions should be raised when there is no way to ignore or recover from
58 the offending action**.
59
60 More specifically, raise an exception when:
61
62 1. A DataLad interface's parameter specifications are violated
63 2. An additional requirement (beyond parameters) for the meaningful continuation of a
64 DataLad interface, function, or process is not met
65
66 It must be made clear to the user/caller what the exact cause of the exception
67 is, given the context within which the user/caller triggered the action.
68 This is achieved directly via a (re)raised exception, as opposed to logging messages or
69 results records which could be ignored or unseen by the user.
70
71 .. note::
72 In the case of a complex set of dependent actions it could be expensive to
73 confirm parameter violations. In such cases, initial sub-routines might already generate
74 result records that have to be inspected by the caller, and it could be practically better
75 to yield a result record (with ``status=[error|impossible]``) to communicate the failure.
76 It would then be up to the upstream caller to decide whether to specify
77 ``on_failure='ignore'`` or whether to inspect individual result records and turn them
78 into exceptions or not.
79
80
81 Logging
82 -------
83
84 Logging provides developers with additional means to describe steps in a process,
85 so as to **allow insight into the program flow during debugging** or analysis of e.g.
86 usage patterns. Logging can be turned off externally, filtered, and redirected. Apart from
87 the :ref:`log-level <chap_design_log_levels>` and message, it is not inspectable and
88 cannot be used to control the logic or flow of a program.
89
90 Importantly, logging should not be the primary user messaging method for command outcomes,
91 Therefore:
92
93 1. No interface should rely solely on logging for user communication
94 2. Use logging for in-progress user communication via the mechanism for :ref:`progress reporting <chap_design_progress_reporting>`
95 3. Use logging to inform debugging processes
96
97
98 UI Module
99 ---------
100
101 The :mod:`~datalad.ui` module provides the means to communicate information
102 to the user in a user-interface-specific manner, e.g. via a console, dialog, or an iPython interface.
103 Internally, all DataLad results processed by the result renderer are passed through the UI module.
104
105 Therefore: unless the criteria for logging apply, and unless the message to be delivered to the user
106 is specified via the ``message`` key of a result record, developers should let explicit user communication
107 happen through the UI module as it provides the flexibility to adjust to the present UI.
108 Specifically, :py:func:`datalad.ui.message` allows passing a simple message via the UI module.
109
110
111 Examples
112 ========
113
114 The following links point to actual code implementations of the respective user
115 messaging methods:
116
117 - `Result yielding`_
118 - `Exception handling`_
119 - `Logging`_
120 - `UI messaging`_
121
122 .. _Result yielding: https://github.com/datalad/datalad/blob/a8d7c63b763aacfbca15925bb1562a62b4448ea6/datalad/core/local/status.py#L402-L426
123 .. _Exception handling: https://github.com/datalad/datalad/blob/a8d7c63b763aacfbca15925bb1562a62b4448ea6/datalad/core/local/status.py#L149-L150
124 .. _Logging: https://github.com/datalad/datalad/blob/a8d7c63b763aacfbca15925bb1562a62b4448ea6/datalad/core/local/status.py#L158
125 .. _UI messaging: https://github.com/datalad/datalad/blob/a8d7c63b763aacfbca15925bb1562a62b4448ea6/datalad/core/local/status.py#L438-L457