Jean-Pierre MartineauandClaude Opus 5.5
4e22f29a74
It said that grep treats "found nothing" and "worked" as the same result. grep exits with 0 when it finds a line, with 1 when it finds nothing, and with 2 on an error, so it is the usual exception. The text now says so, and it says why MeshTerm uses 5: 1 is already FAILURE. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
81 lines
4.3 KiB
Python
81 lines
4.3 KiB
Python
# SPDX-License-Identifier: Apache-2.0
|
|
"""The exit statuses that ``meshterm`` returns, and the meaning of each status.
|
|
|
|
The return value of a scripted run is its report. The CLI tells what happened in plain
|
|
text on stdout, and it tells if the run was successful in ``$?``. The codes have classes,
|
|
instead of only 0 and 1. Thus a caller can identify each type of failure, and it does not
|
|
have to read the text. For example, it is good to try again after a timeout, but never
|
|
after a bad key.
|
|
|
|
The set is small and closed. A result that does not agree with one of the specific
|
|
causes below is :data:`FAILURE`. No part of MeshTerm makes a new code of its own.
|
|
|
|
+------+--------------+--------------------------------------------------------+
|
|
| Code | Name | Meaning |
|
|
+======+==============+========================================================+
|
|
| 0 | ``OK`` | The command did what it was asked to do. |
|
|
+------+--------------+--------------------------------------------------------+
|
|
| 1 | ``FAILURE`` | It failed for a reason that has no more specific code: |
|
|
| | | a bad config or preference value, a file that cannot |
|
|
| | | be read, or an unhandled fault. |
|
|
+------+--------------+--------------------------------------------------------+
|
|
| 2 | ``USAGE`` | The command line itself was wrong: an unknown flag, a |
|
|
| | | missing argument, or a value that the parser refused. |
|
|
| | | Click returns this code itself. It is in this table so |
|
|
| | | that the table is complete. |
|
|
+------+--------------+--------------------------------------------------------+
|
|
| 3 | ``NO_DEVICE``| No companion could be selected: none is connected, |
|
|
| | | none matches ``--port``/``--ble``/``--tcp``, or the |
|
|
| | | choice was ambiguous. Nothing was transmitted. |
|
|
+------+--------------+--------------------------------------------------------+
|
|
| 4 | ``DEVICE`` | A device was reached, but the operation failed: a |
|
|
| | | command error, a timeout, or a link that was lost |
|
|
| | | during the run. It is reasonable to try again. |
|
|
+------+--------------+--------------------------------------------------------+
|
|
| 5 | ``NO_RESULT``| The command ran and completed, and there was nothing |
|
|
| | | to report: an empty list, a target that never replied, |
|
|
| | | or a conversation with no messages. stdout is empty. |
|
|
| | | This result is not an error. |
|
|
+------+--------------+--------------------------------------------------------+
|
|
|
|
:data:`NO_RESULT` is the code that is most important to explain. A script wants this
|
|
code most, and few tools give it. Most tools exit with 0 when they find nothing, the same
|
|
as when they find something. A caller of such a tool must count the output lines to know
|
|
an empty mesh from a full mesh, thus it must parse the output. ``grep`` is the usual
|
|
exception: it exits with 1 when it finds no line, and with 2 on an error. In MeshTerm,
|
|
1 is already :data:`FAILURE`, so "nothing to report" has a code of its own. With this
|
|
code, the caller can make a branch on the status instead.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
#: The command did what it was asked to do.
|
|
OK = 0
|
|
|
|
#: A failure with no more specific code: a bad value, a file that cannot be read, a fault.
|
|
FAILURE = 1
|
|
|
|
#: The command line was wrong. Click returns this code itself. It is here so that the set
|
|
#: is complete.
|
|
USAGE = 2
|
|
|
|
#: No companion device could be selected. Nothing was transmitted.
|
|
NO_DEVICE = 3
|
|
|
|
#: A device was reached, but the operation failed. It is reasonable to try again.
|
|
DEVICE = 4
|
|
|
|
#: The command completed with nothing to report. This result is not an error. stdout is
|
|
#: empty.
|
|
NO_RESULT = 5
|
|
|
|
#: All the codes, by name, for the ``--help`` epilog and the documentation.
|
|
MEANINGS: dict[int, str] = {
|
|
OK: "success",
|
|
FAILURE: "failure",
|
|
USAGE: "usage error",
|
|
NO_DEVICE: "no device found, or the selection was ambiguous",
|
|
DEVICE: "the device was reached but the operation failed",
|
|
NO_RESULT: "nothing to report (empty result)",
|
|
}
|