From ff7e8e50b03609d870a63766dbb3489a013d7361 Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Thu, 18 Apr 2024 08:02:34 +0200 Subject: [PATCH 1/3] work around errors in docstrings --- .../Lakeshore/Lakeshore_model_325.py | 67 ++++++++++++++++++- 1 file changed, 66 insertions(+), 1 deletion(-) diff --git a/src/qcodes/instrument_drivers/Lakeshore/Lakeshore_model_325.py b/src/qcodes/instrument_drivers/Lakeshore/Lakeshore_model_325.py index c91132c2594..a209828912f 100644 --- a/src/qcodes/instrument_drivers/Lakeshore/Lakeshore_model_325.py +++ b/src/qcodes/instrument_drivers/Lakeshore/Lakeshore_model_325.py @@ -1,6 +1,15 @@ from enum import IntFlag from itertools import takewhile -from typing import TYPE_CHECKING, Any, Optional, TextIO, cast +from typing import ( + TYPE_CHECKING, + Any, + Literal, + Optional, + SupportsBytes, + SupportsIndex, + TextIO, + cast, +) from qcodes.instrument import ChannelList, InstrumentChannel, VisaInstrument from qcodes.parameters import Group, GroupParameter @@ -9,6 +18,8 @@ if TYPE_CHECKING: from collections.abc import Iterable + from typing_extensions import Buffer, Self + def _read_curve_file(curve_file: TextIO) -> dict[Any, Any]: """ @@ -79,6 +90,60 @@ class LakeshoreModel325Status(IntFlag): temp_underrange = 16 invalid_reading = 1 + # we reimplement from_bytes and to_bytes in order to fix docstrings that are incorrectly formatted + # this in turn will enable us to build docs with warnings as errors. + # This can be removed for python versions where https://github.com/python/cpython/pull/117847 + # is merged + @classmethod + def from_bytes( + cls: "type[Self]", + bytes: "Iterable[SupportsIndex] | SupportsBytes | Buffer", + byteorder: Literal["big", "little"] = "big", + *, + signed: bool = False, + ) -> "Self": + """ + Return the integer represented by the given array of bytes. + + Args: + bytes: Holds the array of bytes to convert. The argument must either + support the buffer protocol or be an iterable object producing bytes. + Bytes and bytearray are examples of built-in objects that support the + buffer protocol. + byteorder: The byte order used to represent the integer. If byteorder is 'big', + the most significant byte is at the beginning of the byte array. If + byteorder is 'little', the most significant byte is at the end of the + byte array. To request the native byte order of the host system, use + `sys.byteorder` as the byte order value. Default is to use 'big'. + signed: Indicates whether two\'s complement is used to represent the integer. + """ + return super().from_bytes(bytes, byteorder, signed=signed) + + def to_bytes( + self, + length: SupportsIndex = 1, + byteorder: Literal["little"] | Literal["big"] = "big", + *, + signed: bool = False, + ) -> bytes: + """ + Return an array of bytes representing an integer. + + Args: + length: Length of bytes object to use. An OverflowError is raised if the + integer is not representable with the given number of bytes. Default + is length 1. + byteorder: The byte order used to represent the integer. If byteorder is \'big\', + the most significant byte is at the beginning of the byte array. If + byteorder is \'little\', the most significant byte is at the end of the + byte array. To request the native byte order of the host system, use + `sys.byteorder` as the byte order value. Default is to use \'big\'. + signed: Determines whether two\'s complement is used to represent the integer. + If signed is False and a negative integer is given, an OverflowError + is raised. + """ + return super().to_bytes(length, byteorder, signed=signed) + class LakeshoreModel325Curve(InstrumentChannel): """ From b700090f90c59e2d29f70dd5f248ef7104b23db6 Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Thu, 18 Apr 2024 08:06:08 +0200 Subject: [PATCH 2/3] reenable warnings as errors in docs --- .github/workflows/docs.yaml | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 8fa03b83906..dd114e554a2 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -39,12 +39,7 @@ jobs: python-version: 3.11 env: OS: ${{ matrix.os }} - # The std-lib docstring of Int is not valid - # causing errors like in the docstring of from_bytes (from Int) - # WARNING: Inline interpreted text or phrase reference start-string without end-string. - # when documenting subclasses of IntFlag such as in the lakeshore driver. - # see https://github.com/python/cpython/pull/117847 - SPHINX_WARNINGS_AS_ERROR: false + SPHINX_WARNINGS_AS_ERROR: true SPHINX_OPTS: "-v -j 2" steps: - name: Harden Runner From 185b68864b466c8fcf2fd2ede11d8203fc66d8f3 Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Thu, 18 Apr 2024 08:23:47 +0200 Subject: [PATCH 3/3] restore 3.9 compatiblility --- .../instrument_drivers/Lakeshore/Lakeshore_model_325.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/qcodes/instrument_drivers/Lakeshore/Lakeshore_model_325.py b/src/qcodes/instrument_drivers/Lakeshore/Lakeshore_model_325.py index a209828912f..0231e1bb307 100644 --- a/src/qcodes/instrument_drivers/Lakeshore/Lakeshore_model_325.py +++ b/src/qcodes/instrument_drivers/Lakeshore/Lakeshore_model_325.py @@ -8,6 +8,7 @@ SupportsBytes, SupportsIndex, TextIO, + Union, cast, ) @@ -97,7 +98,7 @@ class LakeshoreModel325Status(IntFlag): @classmethod def from_bytes( cls: "type[Self]", - bytes: "Iterable[SupportsIndex] | SupportsBytes | Buffer", + bytes: "Union[Iterable[SupportsIndex], SupportsBytes, Buffer]", byteorder: Literal["big", "little"] = "big", *, signed: bool = False, @@ -122,7 +123,7 @@ def from_bytes( def to_bytes( self, length: SupportsIndex = 1, - byteorder: Literal["little"] | Literal["big"] = "big", + byteorder: Literal["little", "big"] = "big", *, signed: bool = False, ) -> bytes: