pyserial: Fix read and write methods (#9825)

Author: hamdanal

stubs/pyserial/@tests/stubtest_allowlist.txt

@@ -8,22 +8,15 @@ serial.serialjava  # No Java Communications API implementation found
 # ======================
 # These are positional only argument in the stub because they inherit from io.RawIOBase
 # but at runtime they are normal arguments that don't have consistent names.
-serial.Serial.read
 serial.Serial.write
 serial.SerialBase.readinto
 serial.serialutil.SerialBase.readinto
-serial.rfc2217.Serial.read
 serial.rfc2217.Serial.write
 serial.rs485.RS485.write
-serial.urlhandler.protocol_cp2110.Serial.read
 serial.urlhandler.protocol_cp2110.Serial.write
-serial.urlhandler.protocol_loop.Serial.read
 serial.urlhandler.protocol_loop.Serial.write
-serial.urlhandler.protocol_rfc2217.Serial.read
 serial.urlhandler.protocol_rfc2217.Serial.write
-serial.urlhandler.protocol_socket.Serial.read
 serial.urlhandler.protocol_socket.Serial.write
-serial.urlhandler.protocol_spy.Serial.read
 serial.urlhandler.protocol_spy.Serial.write
 
 # Error: is not present in stub

stubs/pyserial/@tests/stubtest_allowlist_darwin.txt

@@ -9,12 +9,7 @@ serial.tools.list_ports_windows  # Windows only
 # Methods defined with positional-only argument in the stub because they inherit from
 # io.RawIOBase but at runtime they are normal arguments that don't have consistent
 # names.
-serial.PosixPollSerial.read
-serial.VTIMESerial.read
-serial.serialposix.Serial.read
 serial.serialposix.Serial.write
-serial.serialposix.PosixPollSerial.read
-serial.serialposix.VTIMESerial.read
 
 # intended to be private aliases
 serial.tools.list_ports_posix.plat

stubs/pyserial/@tests/stubtest_allowlist_linux.txt

@@ -10,12 +10,7 @@ serial.tools.list_ports_windows  # Windows only
 # Methods defined with positional-only argument in the stub because they inherit from
 # io.RawIOBase but at runtime they are normal arguments that don't have consistent
 # names.
-serial.PosixPollSerial.read
-serial.VTIMESerial.read
-serial.serialposix.Serial.read
 serial.serialposix.Serial.write
-serial.serialposix.PosixPollSerial.read
-serial.serialposix.VTIMESerial.read
 
 # Error: is missing from the stub (intended to be private aliases)
 # ================================================================

stubs/pyserial/@tests/stubtest_allowlist_win32.txt

@@ -9,5 +9,4 @@ serial.tools.list_ports_posix  # Posix only
 # Methods defined with positional-only argument in the stub because they inherit from
 # io.RawIOBase but at runtime they are normal arguments that don't have consistent
 # names.
-serial.serialwin32.Serial.read
 serial.serialwin32.Serial.write

stubs/pyserial/serial/rfc2217.pyi

@@ -1,4 +1,5 @@
 import logging
+from _typeshed import ReadableBuffer
 from collections.abc import Callable, Generator
 from typing import Any
 
@@ -149,6 +150,8 @@ class Serial(SerialBase):
     def from_url(self, url: str) -> tuple[str, int]: ...
     @property
     def in_waiting(self) -> int: ...
+    def read(self, size: int = 1) -> bytes: ...
+    def write(self, __b: ReadableBuffer) -> int | None: ...
     def reset_input_buffer(self) -> None: ...
     def reset_output_buffer(self) -> None: ...
     @property

stubs/pyserial/serial/serialcli.pyi

@@ -1,3 +1,4 @@
+from _typeshed import ReadableBuffer
 from typing import Any
 
 from serial.serialutil import *
@@ -10,6 +11,8 @@ class Serial(SerialBase):
     def open(self) -> None: ...
     @property
     def in_waiting(self) -> int: ...
+    def read(self, size: int = 1) -> bytes: ...
+    def write(self, __b: ReadableBuffer) -> int | None: ...
     def reset_input_buffer(self) -> None: ...
     def reset_output_buffer(self) -> None: ...
     @property

stubs/pyserial/serial/serialjava.pyi

@@ -1,3 +1,4 @@
+from _typeshed import ReadableBuffer
 from collections.abc import Iterable
 from typing import Any
 
@@ -15,6 +16,8 @@ class Serial(SerialBase):
     def open(self) -> None: ...
     @property
     def in_waiting(self) -> int: ...
+    def read(self, size: int = 1) -> bytes: ...
+    def write(self, __b: ReadableBuffer) -> int | None: ...
     def reset_input_buffer(self) -> None: ...
     def reset_output_buffer(self) -> None: ...
     @property

stubs/pyserial/serial/serialposix.pyi

@@ -1,4 +1,5 @@
 import sys
+from _typeshed import ReadableBuffer
 from typing_extensions import Never
 
 from serial.serialutil import SerialBase
@@ -64,8 +65,10 @@ class Serial(SerialBase, PlatformSpecific):
     def open(self) -> None: ...
     @property
     def in_waiting(self) -> int: ...
+    def read(self, size: int = 1) -> bytes: ...
     def cancel_read(self) -> None: ...
     def cancel_write(self) -> None: ...
+    def write(self, __b: ReadableBuffer) -> int | None: ...
     def reset_input_buffer(self) -> None: ...
     def reset_output_buffer(self) -> None: ...
     def send_break(self, duration: float = ...) -> None: ...

stubs/pyserial/serial/serialutil.pyi

@@ -1,4 +1,6 @@
 import io
+from _typeshed import ReadableBuffer, WriteableBuffer
+from abc import abstractmethod
 from collections.abc import Callable, Generator
 from typing import Any
 from typing_extensions import Final
@@ -63,7 +65,21 @@ class SerialBase(io.RawIOBase):
         inter_byte_timeout: float | None = ...,
         exclusive: float | None = ...,
     ) -> None: ...
-    def read(self, __size: int = ...) -> bytes: ...  # same as io.RawIOBase.read but always returns bytes
+
+    # Return type:
+    # ------------
+    # `io.RawIOBase`, the super class, declares the return type of read as `-> bytes | None`.
+    # `SerialBase` does not define `read` at runtime but REQUIRES subclasses to implement it and
+    # require it to return `bytes`.
+    # Abstract:
+    # ---------
+    # `io.RawIOBase` implements `read` in terms of `readinto`. `SerialBase` implements `readinto`
+    # in terms of `read`. If subclasses do not implement `read`, any call to `read` or `read_into`
+    # will fail at runtime with a `RecursionError`.
+    @abstractmethod
+    def read(self, __size: int = -1) -> bytes: ...
+    @abstractmethod
+    def write(self, __b: ReadableBuffer) -> int | None: ...
     @property
     def port(self) -> str | None: ...
     @port.setter
@@ -130,6 +146,7 @@ class SerialBase(io.RawIOBase):
     def rs485_mode(self, rs485_settings: RS485Settings | None) -> None: ...
     def get_settings(self) -> dict[str, Any]: ...
     def apply_settings(self, d: dict[str, Any]) -> None: ...
+    def readinto(self, __buffer: WriteableBuffer) -> int: ...  # returns int unlike `io.RawIOBase`
     def send_break(self, duration: float = ...) -> None: ...
     def read_all(self) -> bytes | None: ...
     def read_until(self, expected: bytes = ..., size: int | None = ...) -> bytes: ...

stubs/pyserial/serial/serialwin32.pyi

@@ -1,9 +1,13 @@
+from _typeshed import ReadableBuffer
+
 from serial.serialutil import SerialBase
 
 class Serial(SerialBase):
     def open(self) -> None: ...
     @property
     def in_waiting(self) -> int: ...
+    def read(self, size: int = 1) -> bytes: ...
+    def write(self, __b: ReadableBuffer) -> int | None: ...
     def reset_input_buffer(self) -> None: ...
     def reset_output_buffer(self) -> None: ...
     @property