{"id":9437,"library":"adafruit-circuitpython-typing","title":"Adafruit CircuitPython Typing","description":"adafruit-circuitpython-typing provides Python type hints, specifically Protocol definitions and TypeAliases, for common hardware interface types found in CircuitPython, such as BlockDevice, SPIDevice, and AnyDisplay. It facilitates static type checking for CircuitPython applications developed in CPython environments. The library is currently at version 1.12.3 and is actively maintained with frequent minor releases.","status":"active","version":"1.12.3","language":"en","source_language":"en","source_url":"https://github.com/adafruit/Adafruit_CircuitPython_Typing","tags":["typing","adafruit","circuitpython","type-hints","protocol","development"],"install":[{"cmd":"pip install adafruit-circuitpython-typing","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Commonly used for block storage devices like SD cards.","symbol":"BlockDevice","correct":"from adafruit_circuitpython_typing import BlockDevice"},{"note":"A type alias representing any display device, useful for abstracting display drivers.","symbol":"AnyDisplay","correct":"from adafruit_circuitpython_typing import AnyDisplay"},{"note":"Protocol for SPI bus devices.","symbol":"SPIDevice","correct":"from adafruit_circuitpython_typing import SPIDevice"}],"quickstart":{"code":"from adafruit_circuitpython_typing import BlockDevice, AnyDisplay\nfrom typing import Protocol\n\n# Define a mock BlockDevice for demonstration purposes\nclass MockBlockDevice(Protocol):\n    def readblocks(self, start_block: int, buf: bytearray) -> None:\n        print(f\"Reading block {start_block}\")\n\n    def writeblocks(self, start_block: int, buf: bytearray) -> None:\n        print(f\"Writing block {start_block}\")\n\n    def ioctl(self, operation: int, arg: int) -> int:\n        print(f\"IOCTL operation {operation} with arg {arg}\")\n        return 0\n\n# A function that expects any BlockDevice\ndef format_device(device: BlockDevice) -> None:\n    print(f\"Formatting a device of type: {type(device).__name__}\")\n    device.writeblocks(0, bytearray(512))\n\n# A function that expects any display type\ndef initialize_display(display: AnyDisplay) -> None:\n    print(f\"Initializing display of type: {type(display).__name__}\")\n    # In a real scenario, this would call display methods like show(), fill(), etc.\n\n\n# Example usage:\nmy_sd_card = MockBlockDevice()\nformat_device(my_sd_card)\n\n# A mock display object (in reality, it would be from a CircuitPython display driver)\nclass MockDisplay:\n    def show(self) -> None: pass\n    def fill(self, color: int) -> None: pass\n\nmy_oled_display = MockDisplay()\ninitialize_display(my_oled_display)\n\nprint(\"Type hints used successfully for static analysis.\")","lang":"python","description":"This quickstart demonstrates how to import and use the `BlockDevice` and `AnyDisplay` types in function signatures. These types are primarily used for static type checking to ensure compatibility with various hardware interfaces, not for runtime instantiation. The example includes mock implementations to illustrate how objects conforming to the protocols would be used."},"warnings":[{"fix":"Use the types only in type annotations (e.g., `device: BlockDevice`). Instances are provided by actual hardware drivers, not by this library directly.","message":"This library primarily provides `Protocol` definitions and `TypeAlias` types for static analysis. You should not attempt to instantiate `BlockDevice()`, `SPIDevice()`, or similar types at runtime, as they are not designed for that and will raise a `TypeError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your CPython development environment uses Python 3.8 or a later version. Upgrade your Python installation if necessary.","message":"As of version 1.10.3, `adafruit-circuitpython-typing` requires Python 3.8 or newer. Using it with older Python versions will result in installation failures or `SyntaxError` due to features like position-only arguments used internally.","severity":"breaking","affected_versions":">=1.10.3"},{"fix":"Use this library only in your CPython development environment (e.g., on your desktop computer) for linting and static analysis. For microcontrollers, simply use the actual CircuitPython libraries without explicit type hinting dependencies from this package.","message":"This library is designed for CPython development environments to provide type hints for CircuitPython code. It is NOT intended to be installed or run directly on microcontrollers or used to build .mpy bundles, as it contains syntax incompatible with `mpy-cross` and microcontroller targets.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install adafruit-circuitpython-typing` to install the package.","cause":"The `adafruit-circuitpython-typing` library has not been installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'adafruit_circuitpython_typing'"},{"fix":"Protocols and TypeAliases are for type checking, not for creating objects. Use them in type annotations like `my_function(device: BlockDevice)`.","cause":"You are attempting to instantiate a Protocol or TypeAlias (e.g., `my_device = BlockDevice()`) instead of using it as a type hint.","error":"TypeError: 'BlockDevice' is not a type object"},{"fix":"Upgrade your Python environment to Python 3.8 or newer. The library explicitly requires `python_requires='>=3.8'`.","cause":"This error can occur if you are running `adafruit-circuitpython-typing` (version 1.10.3 or higher) on a Python version older than 3.8, which does not support position-only arguments used within the library's internal type definitions.","error":"SyntaxError: '/' is an invalid character in identifier"}]}