PyOpenocdClient 0.1.0__tar.gz → 0.1.2__tar.gz

pyopenocdclient-0.1.2/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: PyOpenocdClient
+Version: 0.1.2
+Summary: Library for controlling OpenOCD from Python programs
+Author-email: Jan Matyas <info@janmatyas.net>
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PyOpenocdClient
+
+[![Build documentation](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/build_doc.yml/badge.svg?event=schedule)](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/build_doc.yml)
+[![Code quality checks](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/code_quality.yml/badge.svg?event=schedule)](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/code_quality.yml)
+[![Unit tests](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/unit_tests.yml/badge.svg?event=schedule)](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/unit_tests.yml)
+[![Integration tests](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/integration_tests.yml/badge.svg?event=schedule)](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/integration_tests.yml)
+
+**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, ...
+
+Main features of PyOpenocdClient:
+
+* allow to send any TCL command to OpenOCD and obtain its result;
+
+* shorcuts for quick use of most common OpenOCD commands are provided;
+
+* command failures are detected (and reported as Python exceptions by default);
+
+* the code is fully covered via unit tests;
+
+* automatic integration testing 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).
+
+
+## Quick instructions
+
+Install PyOpenocdClient package using Pip:
+
+```bash
+$ python3 -m pip install PyOpenocdClient
+```
+
+Basic usage:
+
+```python
+from py_openocd_client import PyOpenocdClient
+
+with PyOpenocdClient(host="localhost", port=6666) as ocd:
+
+    ocd.reset_halt()
+    ocd.cmd("load_image path/to/program.elf")
+    ocd.resume()
+    # ...
+```
+
+## Documentation
+
+For full documentation, please visit: https://pyopenocdclient.readthedocs.io/en/latest/
+
+&nbsp;
+
+

pyopenocdclient-0.1.2/README.md

@@ -0,0 +1,57 @@
+# PyOpenocdClient
+
+[![Build documentation](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/build_doc.yml/badge.svg?event=schedule)](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/build_doc.yml)
+[![Code quality checks](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/code_quality.yml/badge.svg?event=schedule)](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/code_quality.yml)
+[![Unit tests](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/unit_tests.yml/badge.svg?event=schedule)](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/unit_tests.yml)
+[![Integration tests](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/integration_tests.yml/badge.svg?event=schedule)](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/integration_tests.yml)
+
+**PyOpenocdClient** is a Python library for controlling [OpenOCD](https://openocd.org)
+software tool.
+
+It allows to send TCL commands from Python programs to OpenOCD — for instance commands like halt execution of the program, view data in memory, place breakpoints, single-step, ...
+
+Main features of PyOpenocdClient:
+
+* allow to send any TCL command to OpenOCD and obtain its result;
+
+* shorcuts for quick use of most common OpenOCD commands are provided;
+
+* command failures are detected (and reported as Python exceptions by default);
+
+* the code is fully covered via unit tests;
+
+* automatic integration testing against multiple versions of OpenOCD;
+
+* the code is multiplatform and portable — it does not have any dependencies except for the Python's standard library;
+
+* fully open-source under a permissive license (MIT license).
+
+
+## Quick instructions
+
+Install PyOpenocdClient package using Pip:
+
+```bash
+$ python3 -m pip install PyOpenocdClient
+```
+
+Basic usage:
+
+```python
+from py_openocd_client import PyOpenocdClient
+
+with PyOpenocdClient(host="localhost", port=6666) as ocd:
+
+    ocd.reset_halt()
+    ocd.cmd("load_image path/to/program.elf")
+    ocd.resume()
+    # ...
+```
+
+## Documentation
+
+For full documentation, please visit: https://pyopenocdclient.readthedocs.io/en/latest/
+
+ 
+
+

{pyopenocdclient-0.1.0 → pyopenocdclient-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "PyOpenocdClient"
-version = "0.1.0"
+version = "0.1.2"
 authors = [
   { name="Jan Matyas", email="info@janmatyas.net" },
 ]

pyopenocdclient-0.1.2/src/PyOpenocdClient.egg-info/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: PyOpenocdClient
+Version: 0.1.2
+Summary: Library for controlling OpenOCD from Python programs
+Author-email: Jan Matyas <info@janmatyas.net>
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PyOpenocdClient
+
+[![Build documentation](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/build_doc.yml/badge.svg?event=schedule)](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/build_doc.yml)
+[![Code quality checks](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/code_quality.yml/badge.svg?event=schedule)](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/code_quality.yml)
+[![Unit tests](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/unit_tests.yml/badge.svg?event=schedule)](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/unit_tests.yml)
+[![Integration tests](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/integration_tests.yml/badge.svg?event=schedule)](https://github.com/HonzaMat/PyOpenocdClient/actions/workflows/integration_tests.yml)
+
+**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, ...
+
+Main features of PyOpenocdClient:
+
+* allow to send any TCL command to OpenOCD and obtain its result;
+
+* shorcuts for quick use of most common OpenOCD commands are provided;
+
+* command failures are detected (and reported as Python exceptions by default);
+
+* the code is fully covered via unit tests;
+
+* automatic integration testing 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).
+
+
+## Quick instructions
+
+Install PyOpenocdClient package using Pip:
+
+```bash
+$ python3 -m pip install PyOpenocdClient
+```
+
+Basic usage:
+
+```python
+from py_openocd_client import PyOpenocdClient
+
+with PyOpenocdClient(host="localhost", port=6666) as ocd:
+
+    ocd.reset_halt()
+    ocd.cmd("load_image path/to/program.elf")
+    ocd.resume()
+    # ...
+```
+
+## Documentation
+
+For full documentation, please visit: https://pyopenocdclient.readthedocs.io/en/latest/
+
+&nbsp;
+
+

{pyopenocdclient-0.1.0 → pyopenocdclient-0.1.2}/src/py_openocd_client/baseclient.py

@@ -94,10 +94,35 @@ class _PyOpenocdBaseClient:
             raise ValueError("Timeout must be greater than zero")
         self._default_recv_timeout = timeout
 
-    def _check_no_premature_recvd_bytes(self) -> None:
+    def _check_connection_before_command(self) -> None:
         assert self._socket is not None
         rd, _, _ = select.select([self._socket], [], [], 0)  # Don't block, just poll
-        if len(rd) > 0:
+
+        if len(rd) == 0:
+            # The socket is not ready for recv() now, which is the expected state.
+            # Success.
+            return
+
+        # The socket is ready for recv(). This is unexpected at this point
+        # and always means an error. Try receive from the socket to find out
+        # what happened:
+        try:
+            recvd_data = self._socket.recv(128)
+        except OSError as e:
+            # This is unlikely to happen: It would mean that the socket is ready
+            # for recv() but then recv() failed.
+            raise OcdConnectionError(
+                "Connection to OpenOCD broken for an unknown reason"
+            ) from e
+
+        if len(recvd_data) == 0:
+            # Empty received data means that the connection got closed by OpenOCD
+            # in the meanwhile.
+            raise OcdConnectionError("Connection closed by OpenOCD")
+        else:
+            # It looks like OpenOCD sent us some extra, unsolicited bytes (without us
+            # sending any command to OpenOCD). This is a violation of the communication
+            # protocol.
             raise OcdConnectionError(
                 "Received unexpected bytes from OpenOCD before "
                 "the command was even sent."
@@ -107,12 +132,27 @@ class _PyOpenocdBaseClient:
         assert self.is_connected()
         assert self._socket is not None
 
-        # Safety:
-        self._check_no_premature_recvd_bytes()
+        # Perform basic connection check before sending a command.
+        # Note that this is merely a safety/correctness check which itself
+        # does not guarantee that the subsequent send() and recv() calls
+        # will succeed.
+        self._check_connection_before_command()
 
         data = raw_cmd.encode(self.CHARSET) + self.COMMAND_DELIMITER
-        self._socket.settimeout(self.SEND_TIMEOUT)
-        self._socket.send(data)
+
+        try:
+            self._socket.settimeout(self.SEND_TIMEOUT)
+        except OSError as e:
+            raise OcdConnectionError(
+                "Could not send a command to OpenOCD, failed to set socket timeout"
+            ) from e
+
+        try:
+            self._socket.send(data)
+        except OSError as e:
+            raise OcdConnectionError(
+                "Could not send a command to OpenOCD, socket error occurred"
+            ) from e
 
     def _do_recv_response(self, raw_cmd: str, timeout: Optional[float] = None) -> str:
         assert self.is_connected()
@@ -123,7 +163,13 @@ class _PyOpenocdBaseClient:
             timeout if timeout is not None else self._default_recv_timeout
         )
 
-        self._socket.settimeout(self.RECV_POLL_TIMEOUT)
+        try:
+            self._socket.settimeout(self.RECV_POLL_TIMEOUT)
+        except OSError as e:
+            raise OcdConnectionError(
+                "Could not receive a response from OpenOCD, "
+                "failed to set socket timeout"
+            ) from e
 
         time_start = time.time()
         while time.time() < (time_start + effective_timeout):
@@ -131,6 +177,10 @@ class _PyOpenocdBaseClient:
                 d = self._socket.recv(self.RECV_BLOCK_SIZE)
             except socket.timeout:
                 continue
+            except OSError as e:
+                raise OcdConnectionError(
+                    "Could not receive a response from OpenOCD, socket error occurred"
+                ) from e
 
             if d == b"":
                 raise OcdConnectionError("Connection closed by OpenOCD")

{pyopenocdclient-0.1.0 → pyopenocdclient-0.1.2}/src/py_openocd_client/client.py

@@ -22,8 +22,8 @@ class PyOpenocdClient:
 
     - :meth:`cmd` method to send any TCL command to OpenOCD and obtain
       the command result,
-    - convenience methods to issue some of the most common OpenOCD commands --
-      :meth:`halt`, :meth:`resume`, :meth:`read_memory`, :meth:`get_reg`, ..., etc.
+    - convenience methods (shortcuts) to issue some of the most common OpenOCD commands
+      -- :meth:`halt`, :meth:`resume`, :meth:`read_memory`, :meth:`get_reg`, ..., etc.
 
     Basic usage:
 
@@ -211,25 +211,34 @@ class PyOpenocdClient:
             raw_cmd = cmd
 
         raw_cmd = "set CMD_RETCODE [ catch { " + raw_cmd + " } CMD_OUTPUT ] ; "
-        raw_cmd += 'return "$CMD_RETCODE $CMD_OUTPUT" ; '
+
+        # Older OpenOCD versions - prior to 93f16eed4(*) - incorrectly trimmed trailing
+        # whitespace from the string passed to the return command. Work around this bug
+        # by wrapping the string by non-whitespace characters.
+        # (*): https://review.openocd.org/c/openocd/+/9084
+        raw_cmd += 'return "<$CMD_RETCODE,$CMD_OUTPUT>" ; '
 
         raw_result = self.raw_cmd(raw_cmd, timeout=timeout)
 
-        # Verify the raw output from OpenOCD the has the expected format. It can be:
-        #
-        # - Command return code (positive or negative decimal number) and that's it.
-        #
-        # - Or, command return code (positive or negative decimal number) followed by
-        #   a space character and optionally followed by the command's textual output.
-        if re.match(r"^-?\d+($| )", raw_result) is None:
+        def is_expected_raw_result(s: str) -> bool:
+            return (
+                s.startswith("<")
+                and s.endswith(">")
+                and re.match(r"^<-?\d+,", s) is not None
+            )
+
+        if not is_expected_raw_result(raw_result):
             msg = (
                 "Received unexpected response from OpenOCD. "
                 "It looks like OpenOCD misbehaves. "
             )
             raise OcdInvalidResponseError(msg, raw_cmd, raw_result)
 
-        raw_result_parts = raw_result.split(" ", maxsplit=1)
-        assert len(raw_result_parts) in [1, 2]
+        # Remove leading "<" and trailing ">"
+        raw_result = raw_result[1:-1]
+        raw_result_parts = raw_result.split(",", maxsplit=1)
+        assert len(raw_result_parts) == 2
+
         retcode = int(raw_result_parts[0], 10)
         out = raw_result_parts[1] if len(raw_result_parts) == 2 else ""
 
@@ -298,8 +307,8 @@ class PyOpenocdClient:
 
     def curstate(self) -> str:
         """
-        Determinte the state of the currently selected target via the `currstate`
-        command. Return the state as a string.
+        Determinte the state of the currently selected target via
+        the ``<target_name> curstate`` command. Return the state as a string.
         """
         return self.cmd("[target current] curstate").out.strip()
 
@@ -666,11 +675,24 @@ class PyOpenocdClient:
     def shutdown(self) -> None:
         """
         Shut down the OpenOCD process by sending the ``shutdown`` command to it.
-        Then terminate the connection.
+        PyOpenocd client also gets immediately disconnected from OpenOCD.
         """
-        # OpenOCD's shutdown command returns a non-zero error code (which is expected).
-        # For that reason, throw=False is used.
-        self.cmd("shutdown", throw=False)
+        # Different OpenOCD versions respond to "shutdown" command differently:
+        #
+        # - OpenOCD 0.12.0 and older:
+        #   The "shutdown" command results in a non-zero TCL return code,
+        #   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"):
+        #   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()
 
     def raw_cmd(self, raw_cmd: str, timeout: Optional[float] = None) -> str:

pyopenocdclient-0.1.0/PKG-INFO

@@ -1,50 +0,0 @@
-Metadata-Version: 2.1
-Name: PyOpenocdClient
-Version: 0.1.0
-Summary: Library for controlling OpenOCD from Python programs
-Author-email: Jan Matyas <info@janmatyas.net>
-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
-Description-Content-Type: text/markdown
-License-File: LICENSE
-
-# PyOpenocdClient
-
-**PyOpenocdClient** is a Python library for controlling [OpenOCD](https://openocd.org)
-software tool.
-
-It allows to send any TCL commands from Python programs to OpenOCD and receive results of these commands (for instance commands like halt execution of the program, view data in memory, place breakpoints, single-step, ...).
-
-## Quick instructions
-
-Install PyOpenocdClient package using Pip:
-
-```bash
-$ python3 -m pip install PyOpenocdClient
-```
-
-Basic usage:
-
-```python
-from py_openocd_client import PyOpenocdClient
-
-with PyOpenocdClient(host="localhost", port=6666) as ocd:
-
-    ocd.reset_halt()
-    ocd.cmd("load_image path/to/program.elf")
-    ocd.resume()
-    # ...
-```
-
-## Documentation
-
-For full documentation, please visit: https://pyopenocdclient.readthedocs.io/en/latest/
-
-&nbsp;
-
-

pyopenocdclient-0.1.0/README.md

@@ -1,35 +0,0 @@
-# PyOpenocdClient
-
-**PyOpenocdClient** is a Python library for controlling [OpenOCD](https://openocd.org)
-software tool.
-
-It allows to send any TCL commands from Python programs to OpenOCD and receive results of these commands (for instance commands like halt execution of the program, view data in memory, place breakpoints, single-step, ...).
-
-## Quick instructions
-
-Install PyOpenocdClient package using Pip:
-
-```bash
-$ python3 -m pip install PyOpenocdClient
-```
-
-Basic usage:
-
-```python
-from py_openocd_client import PyOpenocdClient
-
-with PyOpenocdClient(host="localhost", port=6666) as ocd:
-
-    ocd.reset_halt()
-    ocd.cmd("load_image path/to/program.elf")
-    ocd.resume()
-    # ...
-```
-
-## Documentation
-
-For full documentation, please visit: https://pyopenocdclient.readthedocs.io/en/latest/
-
- 
-
-

pyopenocdclient-0.1.0/src/PyOpenocdClient.egg-info/PKG-INFO

@@ -1,50 +0,0 @@
-Metadata-Version: 2.1
-Name: PyOpenocdClient
-Version: 0.1.0
-Summary: Library for controlling OpenOCD from Python programs
-Author-email: Jan Matyas <info@janmatyas.net>
-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
-Description-Content-Type: text/markdown
-License-File: LICENSE
-
-# PyOpenocdClient
-
-**PyOpenocdClient** is a Python library for controlling [OpenOCD](https://openocd.org)
-software tool.
-
-It allows to send any TCL commands from Python programs to OpenOCD and receive results of these commands (for instance commands like halt execution of the program, view data in memory, place breakpoints, single-step, ...).
-
-## Quick instructions
-
-Install PyOpenocdClient package using Pip:
-
-```bash
-$ python3 -m pip install PyOpenocdClient
-```
-
-Basic usage:
-
-```python
-from py_openocd_client import PyOpenocdClient
-
-with PyOpenocdClient(host="localhost", port=6666) as ocd:
-
-    ocd.reset_halt()
-    ocd.cmd("load_image path/to/program.elf")
-    ocd.resume()
-    # ...
-```
-
-## Documentation
-
-For full documentation, please visit: https://pyopenocdclient.readthedocs.io/en/latest/
-
-&nbsp;
-
-