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