Merge #536

536: pyvisa.utils: add support for "s" and "p" format r=MatthieuDartiailh a=MatthieuDartiailh

- [x] Closes #532 
- [x] Executed ``black . && isort -c . && flake8`` with no errors
- [x] The change is fully covered by automated unit tests
- [ ] Documented in docs/ as appropriate
- [ ] Added an entry to the CHANGES file


Co-authored-by: MatthieuDartiailh <marul@laposte.net>

.github/workflows/docs.yml

@@ -33,9 +33,8 @@ jobs:
       - name: Install graphviz
         uses: kamiazya/setup-graphviz@v1
       - name: Install doc building tools
-        # Skip 3.2 since there is weird issue with " in Parameters
         run: |
-          pip install sphinx!=3.2 sphinx_rtd_theme
+          pip install sphinx sphinx_rtd_theme
       - name: Build documentation
         run: |
           mkdir docs_output;

CHANGES

@@ -26,6 +26,8 @@ to be removed  in 1.10:
   the ascii or binary variant of the function (`read_xxxx_values`, `write_xxxx_values`,
   `query_xxxx_values`)
 
+- Add support for "s" and "p" binary format which can be used to retrieve binary files
+  from instruments. PR #536
 - Convert the testsuite to use pytest PR #531
   This is motivated by the possibility to re-use it in PyVISA-py. However since
   unittest use inheritance to detect tests, doing so would have been clunky, pytest

azure-pipelines.yml

@@ -57,7 +57,7 @@ steps:
     echo Install codecov
     pip install codecov
     echo Run codecov
-    codecov --file coverage.xml --token $(CODECOV_TOKEN) --env PYVISA_KEYSIGHT_VIRTUAL_INSTR --tries 5 --required -F unittest --name codecov-umbrella
+    codecov --file coverage.xml --token $(CODECOV_TOKEN) --env PYVISA_KEYSIGHT_VIRTUAL_INSTR --tries 5 --required -F unittests --name codecov-umbrella
   displayName: 'Upload test coverage results'
 
 - script: |

docs/source/introduction/rvalues.rst

@@ -118,6 +118,9 @@ many bytes to expect. For those case, you can pass the expected number of
 points using the ``data_points`` keyword argument. The number of bytes will be
 inferred from the datatype of the block.
 
+Finally if you are reading a file for example and simply want to extract a bytes
+object, you can use the ``"s"`` datatype and pass ``bytes`` as container.
+
 
 Writing ASCII values
 --------------------
@@ -159,6 +162,8 @@ Again you can specify the ``datatype`` and ``endianness``.
 
     >>> inst.write_binary_values('WLISt:WAVeform:DATA somename,', values, datatype='d', is_big_endian=False)
 
+If your data are already in a ``bytes`` object you can use the ``"s"`` format.
+
 
 When things are not what they should be
 ---------------------------------------

pyvisa/testsuite/test_util.py

@@ -275,6 +275,19 @@ def test_noninteger_binary_block(self):
                     fblock = lambda block, cont: fb(block, fmt, endi, cont)
                     self.round_trip_block_conversion(values, tblock, fblock, msg)
 
+    def test_bytes_binary_block(self):
+        values = b"dbslbw cj saj \x00\x76"
+        for block, tb, fb in zip(
+            ("ieee", "hp"),
+            (util.to_ieee_block, util.to_hp_block),
+            (util.from_ieee_block, util.from_hp_block),
+        ):
+            for fmt in "sp":
+                block = tb(values, datatype="s")
+                print(block)
+                rt = fb(block, datatype="s", container=bytes)
+                assert values == rt
+
     def test_malformed_binary_block_header(self):
         values = list(range(10))
         for header, tb, fb in zip(

pyvisa/util.py

@@ -692,10 +692,15 @@ def from_binary_block(
     fullfmt = "%s%d%s" % (endianess, array_length, datatype)
 
     try:
-        return container(struct.unpack_from(fullfmt, block, offset))
+        raw_data = struct.unpack_from(fullfmt, block, offset)
     except struct.error:
         raise ValueError("Binary data was malformed")
 
+    if datatype in "sp":
+        raw_data = raw_data[0]
+
+    return container(raw_data)
+
 
 def to_binary_block(
     iterable: Sequence[Union[int, float]],
@@ -723,14 +728,19 @@ def to_binary_block(
 
     """
     array_length = len(iterable)
-
     endianess = ">" if is_big_endian else "<"
     fullfmt = "%s%d%s" % (endianess, array_length, datatype)
 
     if isinstance(header, str):
         header = bytes(header, "ascii")
 
-    return header + struct.pack(fullfmt, *iterable)
+    if datatype in ("s", "p"):
+        block = struct.pack(fullfmt, iterable)
+
+    else:
+        block = struct.pack(fullfmt, *iterable)
+
+    return header + block
 
 
 def to_ieee_block(