PyOpenocdClient 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

py_openocd_client/__init__.py

@@ -6,6 +6,7 @@ from .errors import (  # noqa: F401
     OcdCommandFailedError,
     OcdCommandTimeoutError,
     OcdConnectionError,
+    OcdEmptyResponseError,
     OcdInvalidResponseError,
 )
 from .types import BpInfo, BpType, OcdCommandResult, WpInfo, WpType  # noqa: F401

py_openocd_client/cli.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: MIT
+
+import argparse
+import sys
+
+from .client import PyOpenocdClient
+from .errors import OcdCommandTimeoutError, OcdConnectionError, OcdInvalidResponseError
+
+_DEFAULT_HOST = "127.0.0.1"
+_DEFAULT_PORT = 6666
+_DEFAULT_TIMEOUT = 5.0
+
+_EXIT_CODE_CONNECTION_ERROR = 91
+_EXIT_CODE_INVALID_RESPONSE = 92
+_EXIT_CODE_COMMAND_TIMEOUT = 93
+
+
+def eprint(s: str) -> None:
+    print("error: " + s, file=sys.stderr)
+
+
+def parse_args() -> argparse.Namespace:
+    desc = (
+        "Command-line utility that sends a single Tcl command to OpenOCD\n"
+        "through its Tcl-RPC interface."
+    )
+    epilog = (
+        "If the Tcl command completes successfully, this tool exits with code 0.\n"
+        "Connection errors or command execution errors cause it to exit with\n"
+        "a non-zero code.\n\n"
+        "All the output of the Tcl command is written to stdout.\n"
+        "Any error messages coming from this tool are written to stderr."
+    )
+    parser = argparse.ArgumentParser(
+        description=desc,
+        epilog=epilog,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.color = False
+
+    parser.add_argument(
+        "--host",
+        default=_DEFAULT_HOST,
+        help=(
+            "Hostname or address of the machine where OpenOCD is running "
+            f"(default: {_DEFAULT_HOST})"
+        ),
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=_DEFAULT_PORT,
+        help=f"OpenOCD's Tcl-RPC server port number (default: {_DEFAULT_PORT})",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=_DEFAULT_TIMEOUT,
+        help=(
+            "Timeout for the command execution in seconds "
+            f"(default: {_DEFAULT_TIMEOUT:.1f})"
+        ),
+    )
+    parser.add_argument(
+        "command",
+        help="The Tcl command to send to OpenOCD",
+    )
+
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+
+    try:
+        with PyOpenocdClient(args.host, args.port) as ocd:
+            ocd.set_default_timeout(args.timeout)
+            result = ocd.cmd(args.command, throw=False)
+            print(result.out)
+
+            if result.retcode != 0:
+                eprint(f"The command has failed (return code: {result.retcode}).")
+            return result.retcode
+
+    except OcdConnectionError as e:
+        eprint(str(e))
+        return _EXIT_CODE_CONNECTION_ERROR
+
+    except OcdInvalidResponseError as e:
+        eprint("OpenOCD responded unexpectedly: " + str(e))
+        return _EXIT_CODE_INVALID_RESPONSE
+
+    except OcdCommandTimeoutError as e:
+        eprint(f"Timeout: The command did not complete within {e.timeout:.1f} seconds.")
+        return _EXIT_CODE_COMMAND_TIMEOUT
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

py_openocd_client/client.py

@@ -7,7 +7,12 @@ from typing import Any, List, Optional, Tuple, Type
 
 from .baseclient import _PyOpenocdBaseClient
 from .bp_parser import _BpParser
-from .errors import OcdCommandFailedError, OcdInvalidResponseError, _OcdParsingError
+from .errors import (
+    OcdCommandFailedError,
+    OcdEmptyResponseError,
+    OcdInvalidResponseError,
+    _OcdParsingError,
+)
 from .types import BpInfo, OcdCommandResult, WpInfo, WpType
 from .wp_parser import _WpParser
 
@@ -227,6 +232,14 @@ class PyOpenocdClient:
                 and re.match(r"^<-?\d+,", s) is not None
             )
 
+        if len(raw_result) == 0:
+            msg = (
+                "Received empty response from OpenOCD. "
+                "(This is OK for 'shutdown' or 'exit' commands but unexpected "
+                "for any other command.) "
+            )
+            raise OcdEmptyResponseError(msg, raw_cmd, raw_result)
+
         if not is_expected_raw_result(raw_result):
             msg = (
                 "Received unexpected response from OpenOCD. "
@@ -672,11 +685,37 @@ class PyOpenocdClient:
         """
         self.disconnect()
 
-    def shutdown(self) -> None:
+    def _shutdown_supports_any_exit_code(self) -> bool:
+        return "shutdown ['error'|exit_code]" in self.cmd("help shutdown").out
+
+    def shutdown(self, exit_code: int = 0) -> None:
         """
-        Shut down the OpenOCD process by sending the ``shutdown`` command to it.
-        PyOpenocd client also gets immediately disconnected from OpenOCD.
+        Shut down (terminate) the OpenOCD process by sending the ``shutdown``
+        command to it. PyOpenocdClient also immediately disconnects from OpenOCD.
+
+        The optional argument ``exit_code`` allows to set the exit code
+        of the OpenOCD process. Default is 0 (success).
+
+        .. versionadded:: 0.2.0
+           Argument ``exit_code``.
         """
+        if not (0 <= exit_code <= 255):
+            raise ValueError("The exit_status must be in range 0..255.")
+
+        # For compatibility with older OpenOCD, prefer:
+        # - "shutdown" over "shutdown 0"
+        # - "shutdown error" over "shutdown 1"
+        if exit_code == 0:
+            cmd = "shutdown"
+        elif exit_code == 1:
+            cmd = "shutdown error"
+        else:
+            if not self._shutdown_supports_any_exit_code():
+                raise ValueError(
+                    "This version of OpenOCD supports exit code 0 or 1 only"
+                )
+            cmd = f"shutdown {exit_code}"
+
         # Different OpenOCD versions respond to "shutdown" command differently:
         #
         # - OpenOCD 0.12.0 and older:
@@ -684,16 +723,19 @@ class PyOpenocdClient:
         #   which can be obtained normally as for any other TCL command -
         #   e.g. via the "catch" command.
         #
-        # - OpenOCD 0.13.0-dev and newer (from to commit "93f16eed4"):
+        # - OpenOCD 0.13.0-dev and newer (starting from commit "93f16eed4"):
         #   The "shutdown" command immediately ends the TCL processing and
         #   an empty response is sent back to the TCL client.
 
-        # For the above reasons, send the shutdown command via raw_cmd() and:
-        # - don't wrap "shutdown" into any other TCL commands,
-        # - don't expect any particular response.
-        self.raw_cmd("shutdown")
-
-        self.disconnect()
+        # Tolerate both the above scenarios:
+        try:
+            self.cmd(cmd)
+        except OcdCommandFailedError:
+            pass
+        except OcdEmptyResponseError:
+            pass
+        finally:
+            self.disconnect()
 
     def raw_cmd(self, raw_cmd: str, timeout: Optional[float] = None) -> str:
         """

py_openocd_client/errors.py

@@ -1,5 +1,7 @@
 # SPDX-License-Identifier: MIT
 
+import warnings
+
 from .types import OcdCommandResult
 
 
@@ -87,9 +89,9 @@ class OcdInvalidResponseError(OcdBaseException):
     That is, PyOpenocdClient could not parse and/or interpret that command output.
     """
 
-    def __init__(self, msg: str, raw_cmd: str, out: str):
+    def __init__(self, msg: str, raw_cmd: str, raw_out: str):
         self._raw_cmd = raw_cmd
-        self._out = out
+        self._raw_out = raw_out
         super().__init__(msg)
 
     @property
@@ -99,12 +101,44 @@ class OcdInvalidResponseError(OcdBaseException):
         """
         return self._raw_cmd
 
+    @property
+    def raw_out(self) -> str:
+        """
+        The actual raw command's output that was unexpected
+        (that could not be understood or parsed).
+
+        .. versionadded:: 0.2.0
+        """
+        return self._raw_out
+
     @property
     def out(self) -> str:
         """
-        The actual invalid response of the command.
+        Deprecated alias for ``raw_out``, kept just for compatibility.
+
+        .. deprecated:: 0.2.0
         """
-        return self._out
+        warnings.warn(
+            "OcdInvalidResponseError.out is deprecated. "
+            "Please use OcdInvalidResponseError.raw_out instead.",
+            DeprecationWarning,
+        )
+        return self._raw_out
+
+
+class OcdEmptyResponseError(OcdInvalidResponseError):
+    """
+    Exception which denotes that a TCL command produced an empty response.
+    It is a sub-class of :py:class:`py_openocd_client.OcdInvalidResponseError`.
+
+    Empty responses occur for commands ``exit`` and ``shutdown``, that is, commands
+    that immediately terminate the TCL session. For other commands, empty responses are
+    unexpected and would mean that OpenOCD mis-behaves.
+
+    .. versionadded:: 0.2.0
+    """
+
+    pass
 
 
 class OcdConnectionError(OcdBaseException):

{pyopenocdclient-0.1.2.dist-info → pyopenocdclient-0.2.0.dist-info}/METADATA

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: PyOpenocdClient
-Version: 0.1.2
+Version: 0.2.0
 Summary: Library for controlling OpenOCD from Python programs
 Author-email: Jan Matyas <info@janmatyas.net>
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/HonzaMat/PyOpenocdClient
 Project-URL: Issues, https://github.com/HonzaMat/PyOpenocdClient/issues
 Project-URL: Documentation, https://pyopenocdclient.readthedocs.io/en/latest/
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.7
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Dynamic: license-file
@@ -24,11 +24,13 @@ Dynamic: license-file
 **PyOpenocdClient** is a Python library for controlling [OpenOCD](https://openocd.org)
 software tool.
 
-It allows to send TCL commands from Python programs to OpenOCD &mdash; for instance commands like halt execution of the program, view data in memory, place breakpoints, single-step, ...
+It allows to send Tcl commands from Python programs to OpenOCD &mdash; for instance commands like halt execution of the program, view data in memory, place breakpoints, single-step, ...
+
+In addition, a console utility is included with PyOpenocdClient that can be used to send Tcl commands to OpenOCD from non-Python software, such as shell scripts.
 
 Main features of PyOpenocdClient:
 
-* allow to send any TCL command to OpenOCD and obtain its result;
+* you can send any Tcl command to OpenOCD and obtain its result;
 
 * shorcuts for quick use of most common OpenOCD commands are provided;
 
@@ -36,11 +38,11 @@ Main features of PyOpenocdClient:
 
 * the code is fully covered via unit tests;
 
-* automatic integration testing against multiple versions of OpenOCD;
+* integration testing regularly runs against multiple versions of OpenOCD;
 
 * the code is multiplatform and portable &mdash; it does not have any dependencies except for the Python's standard library;
 
-* fully open-source under a permissive license (MIT license).
+* the library is fully open-source under a permissive license (MIT license).
 
 
 ## Quick instructions
@@ -51,7 +53,7 @@ Install PyOpenocdClient package using Pip:
 $ python3 -m pip install PyOpenocdClient
 ```
 
-Basic usage:
+Basic usage from Python:
 
 ```python
 from py_openocd_client import PyOpenocdClient
@@ -64,6 +66,18 @@ with PyOpenocdClient(host="localhost", port=6666) as ocd:
     # ...
 ```
 
+Basic usage from a command-line or shell scripts:
+
+```bash
+
+$ openocd_cmd --host 127.0.0.1 --port 6666 version
+Open On-Chip Debugger 0.12.0+dev-02634-g390b9d731 (2026-08-29-14:15)
+
+$ openocd_cmd --host 127.0.0.1 --port 6666 "reset halt ; reg pc"
+pc (/32): 0x08001234
+
+```
+
 ## Documentation
 
 For full documentation, please visit: https://pyopenocdclient.readthedocs.io/en/latest/

pyopenocdclient-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+py_openocd_client/__init__.py,sha256=1vwYXd_WD5F35hhS4lF8BkE_aPo6xpnIGaHlEjkUPkM,359
+py_openocd_client/baseclient.py,sha256=BkwX79VqrZkZ_vGk4QnnD9PXGKn8erueMuwDpcAD7GA,9103
+py_openocd_client/bp_parser.py,sha256=yQw8qrK6GmZhR5sIdzjD90zW0StQVUkgAerwqiB08pg,4013
+py_openocd_client/cli.py,sha256=MVtIAIj-60ZPfDKJmOgQTg8YAYTOUtdLkS6CQQTKM74,2815
+py_openocd_client/client.py,sha256=RlZCx6Cf3HdLpfIjBFvz8oNyz6GXYKc4g2LObedXhjw,27760
+py_openocd_client/errors.py,sha256=7uEneGsOgwkwGDKteTPv79Y1REdb0ZU-sALzJK8wZe0,4712
+py_openocd_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+py_openocd_client/types.py,sha256=gOoND2jpGqfAqKDE-LwowTL6eHlTd9GHNsAJQvl8C5o,2204
+py_openocd_client/wp_parser.py,sha256=gcwewLfMus26vve7yPDZnW7kQKvnZpWFJ-CnxPw1Acc,1583
+pyopenocdclient-0.2.0.dist-info/licenses/LICENSE,sha256=LQ4E7j3KmZ2D4Bx0cNd7_k39v0KJlF72VjOAl6k5Aas,1094
+pyopenocdclient-0.2.0.dist-info/METADATA,sha256=2ZbRgwjIgQyhlEUsCI3Tm2U-pTi4GP25eRkf4rRoXB8,3245
+pyopenocdclient-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pyopenocdclient-0.2.0.dist-info/entry_points.txt,sha256=iViuS3xCpmJHGh4vtSWX7IlczcwCSC9gzxH_6BKqAwM,59
+pyopenocdclient-0.2.0.dist-info/top_level.txt,sha256=YzDCf323Zc2HbUuT7wyJ2IHg8vlELGt9Ve0k_u3lhMk,18
+pyopenocdclient-0.2.0.dist-info/RECORD,,

{pyopenocdclient-0.1.2.dist-info → pyopenocdclient-0.2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.1)
+Generator: setuptools (84.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

pyopenocdclient-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+openocd_cmd = py_openocd_client.cli:main

pyopenocdclient-0.1.2.dist-info/RECORD

@@ -1,12 +0,0 @@
-py_openocd_client/__init__.py,sha256=THbr8De7S91EatjLlLIDbkWNLoGAQf5j6kn69xOqGHg,332
-py_openocd_client/baseclient.py,sha256=BkwX79VqrZkZ_vGk4QnnD9PXGKn8erueMuwDpcAD7GA,9103
-py_openocd_client/bp_parser.py,sha256=yQw8qrK6GmZhR5sIdzjD90zW0StQVUkgAerwqiB08pg,4013
-py_openocd_client/client.py,sha256=BuqJfL_DF_vpvnS8m-BVugUx6GQbEy4qV7jKGk0ov64,26424
-py_openocd_client/errors.py,sha256=9K48w4rVgaOkCF4q3ORp3KxH31DVQL0JNXoGktgE-H0,3703
-py_openocd_client/types.py,sha256=gOoND2jpGqfAqKDE-LwowTL6eHlTd9GHNsAJQvl8C5o,2204
-py_openocd_client/wp_parser.py,sha256=gcwewLfMus26vve7yPDZnW7kQKvnZpWFJ-CnxPw1Acc,1583
-pyopenocdclient-0.1.2.dist-info/licenses/LICENSE,sha256=LQ4E7j3KmZ2D4Bx0cNd7_k39v0KJlF72VjOAl6k5Aas,1094
-pyopenocdclient-0.1.2.dist-info/METADATA,sha256=00dFEgphjGU15wTOueEC9g7RXsqf3rmxqxbuLC1VmQg,2804
-pyopenocdclient-0.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-pyopenocdclient-0.1.2.dist-info/top_level.txt,sha256=YzDCf323Zc2HbUuT7wyJ2IHg8vlELGt9Ve0k_u3lhMk,18
-pyopenocdclient-0.1.2.dist-info/RECORD,,