{"id":3844,"library":"types-pyserial","title":"Typing stubs for pyserial","description":"types-pyserial provides static type annotations for the popular pyserial library. It is part of the typeshed project, which centrally maintains type stubs for the Python standard library and many third-party packages. These stubs are used by static type checkers like MyPy or Pyright to verify code correctness without running it, enhancing development and catching potential issues early. The package is regularly updated, often daily, to reflect changes and improvements in the corresponding runtime library, pyserial. This version aims to provide accurate annotations for pyserial==3.5.*.","status":"active","version":"3.5.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","pyserial","serial-communication","typeshed"],"install":[{"cmd":"pip install types-pyserial","lang":"bash","label":"Install types-pyserial"}],"dependencies":[{"reason":"These are typing stubs for the 'pyserial' runtime library. The 'pyserial' package must be installed separately for your application to function at runtime.","package":"pyserial","optional":false}],"imports":[{"note":"The runtime library is installed via `pip install pyserial` but imported as `serial`. The `types-pyserial` package provides stubs for this `serial` module.","wrong":"import pyserial","symbol":"Serial","correct":"from serial import Serial"}],"quickstart":{"code":"import os\nfrom serial import Serial\n\n# Replace with your actual serial port name (e.g., 'COM1' on Windows, '/dev/ttyUSB0' on Linux)\nSERIAL_PORT = os.environ.get('SERIAL_PORT', '/dev/ttyUSB0')\nBAUDRATE = 9600\n\ndef communicate_with_serial(port: str, baud: int) -> None:\n    ser: Serial | None = None\n    try:\n        # The `Serial` class is correctly typed by types-pyserial\n        ser = Serial(port, baud)\n        print(f\"Opened serial port {port} at {baud} baud.\")\n\n        # Example: Write data\n        message_to_send = b\"Hello, device!\\n\"\n        ser.write(message_to_send)\n        print(f\"Sent: {message_to_send.decode().strip()}\")\n\n        # Example: Read data (with a timeout)\n        ser.timeout = 1 # seconds\n        received_data = ser.readline()\n        if received_data:\n            print(f\"Received: {received_data.decode().strip()}\")\n        else:\n            print(\"No data received within timeout.\")\n\n    except Exception as e:\n        print(f\"Error during serial communication: {e}\")\n    finally:\n        if ser and ser.is_open:\n            ser.close()\n            print(f\"Closed serial port {port}.\")\n\nif __name__ == \"__main__\":\n    communicate_with_serial(SERIAL_PORT, BAUDRATE)","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Always install both the runtime library and its corresponding stubs: `pip install pyserial types-pyserial`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to a version supported by the latest typeshed stubs (currently Python 3.10+).","message":"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.","severity":"gotcha","affected_versions":"Python versions older than 3.10"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}