Typing stubs for pyserial

Warnings

• gotcha The PyPI package name is `types-pyserial`, but the runtime library is imported as `serial` (i.e., `import serial`). Confusing these can lead to `ModuleNotFoundError` or incorrect type checking behavior if an unrelated `serial` package is installed.
  Fix: Always use `pip install types-pyserial` for the stubs and `from serial import ...` in your Python code. Ensure `pyserial` is also installed via `pip install pyserial`.
• breaking Type stub versions are primarily tied to the major.minor version of the runtime package they describe. For example, `types-pyserial==3.5.*` targets `pyserial==3.5.*`. If `pyserial` updates its API (especially in a major or minor release), the corresponding `types-pyserial` stubs will also update, potentially causing new type-checking errors if your application's code relies on older APIs.
  Fix: Pin `types-pyserial` to the specific major.minor version of `pyserial` you are using (e.g., `pyserial~=3.5, types-pyserial~=3.5`). Regularly review and update both packages together to stay compatible and benefit from the latest type definitions.
• gotcha `types-pyserial` is a stub-only package and provides no runtime functionality. It is solely used by static type checkers. If `pyserial` (the actual runtime library) is not installed, your code will fail at runtime with an `ImportError`, even if `types-pyserial` is present.
  Fix: Always install both the runtime library and its corresponding stubs: `pip install pyserial types-pyserial`.
• gotcha Typeshed stub packages are automatically released, sometimes as frequently as once a day. While this ensures up-to-date annotations, it means `types-pyserial` can update more frequently than your runtime `pyserial` package or your type checker, potentially introducing new type errors due to changes in stub definitions or reliance on newer typing features.
  Fix: Pin `types-pyserial` to a specific version or a tighter range (e.g., `types-pyserial==3.5.0.20260408`) and update it deliberately, especially when upgrading your type checker or the `pyserial` runtime library. Always test type checking in your CI/CD pipeline.
• gotcha Typeshed (and thus `types-pyserial`) generally supports a range of recent Python versions. Ensure your Python environment is within the supported range (e.g., 3.10 to 3.14 for current typeshed) to guarantee correct stub interpretation by your type checker.
  Fix: Upgrade your Python environment to a version supported by the latest typeshed stubs (currently Python 3.10+).

Install

• pip install types-pyserial Install types-pyserial

Imports

• Serial

  from serial import Serial

  The runtime library is installed via `pip install pyserial` but imported as `serial`. The `types-pyserial` package provides stubs for this `serial` module.

Quickstart

This quickstart demonstrates basic serial communication using `pyserial`. With `types-pyserial` installed, a type checker will provide accurate type hints and catch errors for functions, classes, and methods imported from the `serial` module, such as `Serial`, `write`, `readline`, and `is_open`. The `SERIAL_PORT` environment variable is used for demonstration, but you should replace it with your device's actual serial port.

import os
from serial import Serial

# Replace with your actual serial port name (e.g., 'COM1' on Windows, '/dev/ttyUSB0' on Linux)
SERIAL_PORT = os.environ.get('SERIAL_PORT', '/dev/ttyUSB0')
BAUDRATE = 9600

def communicate_with_serial(port: str, baud: int) -> None:
    ser: Serial | None = None
    try:
        # The `Serial` class is correctly typed by types-pyserial
        ser = Serial(port, baud)
        print(f"Opened serial port {port} at {baud} baud.")

        # Example: Write data
        message_to_send = b"Hello, device!\n"
        ser.write(message_to_send)
        print(f"Sent: {message_to_send.decode().strip()}")

        # Example: Read data (with a timeout)
        ser.timeout = 1 # seconds
        received_data = ser.readline()
        if received_data:
            print(f"Received: {received_data.decode().strip()}")
        else:
            print("No data received within timeout.")

    except Exception as e:
        print(f"Error during serial communication: {e}")
    finally:
        if ser and ser.is_open:
            ser.close()
            print(f"Closed serial port {port}.")

if __name__ == "__main__":
    communicate_with_serial(SERIAL_PORT, BAUDRATE)