Registry / type-stubs / adafruit-circuitpython-typing

adafruit-circuitpython-typing

JSON →
library1.12.3pypypi✓ verified 82d ago

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.

pip install adafruit-circuitpython-typing
INSTALL
IMPORT
SIG · ADAFRUIT-CIRCUITPY
A
adafruit-circuitpython-typing
type-stubspythonv1.12.3
Install
2.6s avg
Import
Disk
26MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.12.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 27.4MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 2.6s · import 0.000s · 28MB
26MB installed
● package 26MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

BlockDevice
from circuitpython_typing import BlockDevice
from adafruit_circuitpython_typing import BlockDevice

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.

from adafruit_circuitpython_typing import BlockDevice, AnyDisplay from typing import Protocol # Define a mock BlockDevice for demonstration purposes class MockBlockDevice(Protocol): def readblocks(self, start_block: int, buf: bytearray) -> None: print(f"Reading block {start_block}") def writeblocks(self, start_block: int, buf: bytearray) -> None: print(f"Writing block {start_block}") def ioctl(self, operation: int, arg: int) -> int: print(f"IOCTL operation {operation} with arg {arg}") return 0 # A function that expects any BlockDevice def format_device(device: BlockDevice) -> None: print(f"Formatting a device of type: {type(device).__name__}") device.writeblocks(0, bytearray(512)) # A function that expects any display type def initialize_display(display: AnyDisplay) -> None: print(f"Initializing display of type: {type(display).__name__}") # In a real scenario, this would call display methods like show(), fill(), etc. # Example usage: my_sd_card = MockBlockDevice() format_device(my_sd_card) # A mock display object (in reality, it would be from a CircuitPython display driver) class MockDisplay: def show(self) -> None: pass def fill(self, color: int) -> None: pass my_oled_display = MockDisplay() initialize_display(my_oled_display) print("Type hints used successfully for static analysis.")
Debug
Known issues
gotchaThis 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`.
fix
Use the types only in type annotations (e.g., `device: BlockDevice`). Instances are provided by actual hardware drivers, not by this library directly.
affects: All versions
breakingAs 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.
fix
Ensure your CPython development environment uses Python 3.8 or a later version. Upgrade your Python installation if necessary.
affects: >=1.10.3
gotchaThis 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.
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.
affects: All versions
Upgrade
Version history
1.12.3latest on PyPI · released Oct 27, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
71 hits · last 30 days
node
60
Perplexity
1
OpenAI (training)
1
Resources
adafruit-circuitpython-typing — pip install adafruit-circuitpython-typing · libregistry