3076847a6c
Changelog: - add support for free-threaded (no-GIL) CPython - generate wheels for CPython 3.14t (free-threaded) - drop support for Python 3.9 - migrate the C extension and test modules to multi-phase module initialization - release the GIL in chip_get_info() - fix heap-buffer overflow bugs when setting/getting line values - check for errors after PyIter_Next() when setting output values - check for errors after PyIter_Next() when reading request values - fix reference count imbalances (missing Py_None and line-name increments, erroneous decref on PyList_SetItem() failure) - allow closing a Chip multiple times without raising an error - allow releasing a LineRequest multiple times without raising an error - remove a duplicated edge-detection setting - add a CHANGELOG.md to track changes between releases - copy the license file into source and binary distributions - require setuptools v77 or newer - remove wheel from the build dependencies - add multi-threaded tests - add a dedicated lint dependency group and update linter configuration - apply linter recommendations and add type annotations across examples, setup and helper scripts - modernize the C extension using upgrade_pythoncapi.py suggestions - minor internal cleanups and performance improvements Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@oss.qualcomm.com>
gpiod
These are the official Python bindings for libgpiod.
Both GIL-enabled and free-threaded CPython are supported.
The Python bindings, much like the C API they wrap, are not thread-safe and do require external synchronization by the caller to serialize access to objects shared across threads.
The gpiod library has been vendored into this package for your convenience and this version of gpiod is independent from your system package.
Binary wheels are provided for some platforms. The source package requires python3-dev.
Rationale
The new character device interface guarantees all allocated resources are freed after closing the device file descriptor and adds several new features that are not present in the obsolete sysfs interface (like event polling, setting/reading multiple values at once or open-source and open-drain GPIOs).
Unfortunately interacting with the linux device file can no longer be done using only standard command-line tools. This is the reason for creating a library encapsulating the cumbersome, ioctl-based kernel-userspace interaction in a set of convenient functions and opaque data structures.
Breaking Changes
As of v2.0.2 we have replaced the unofficial, pure-Python "gpiod". The official gpiod is not backwards compatible.
You should ensure you specify at least v2.0.2 for the official API. Versions 1.5.4 and prior are the deprecated, unofficial, pure-Python bindings.
Installing
You will need python3-dev, on Debian/Ubuntu you can install this with:
sudo apt install python3-dev
And then install gpiod with:
pip install gpiod
You can optionally depend upon your system gpiod by installing with:
LINK_SYSTEM_LIBGPIOD=1 pip install gpiod
If you still need the deprecated pure-Python bindings, install with:
pip install gpiod==1.5.4
Examples
Check a GPIO chip character device exists:
import gpiod
gpiod.is_gpiochip_device("/dev/gpiochip0")
Get information about a GPIO chip character device:
import gpiod
with gpiod.Chip("/dev/gpiochip0") as chip:
info = chip.get_info()
print(f"{info.name} [{info.label}] ({info.num_lines} lines)")
Blink an LED, or toggling a GPIO line:
import time
from gpiod.line import Direction, Value
LINE = 5
with gpiod.request_lines(
"/dev/gpiochip0",
consumer="blink-example",
config={
LINE: gpiod.LineSettings(
direction=Direction.OUTPUT, output_value=Value.ACTIVE
)
},
) as request:
while True:
request.set_value(LINE, Value.ACTIVE)
time.sleep(1)
request.set_value(LINE, Value.INACTIVE)
time.sleep(1)
Testing
The test suite for the python bindings can be run by calling:
python -B -m tests
from the libgpiod/bindings/python directory as root (necessary to be able
to create the gpio-sims used for testing).
Linting/Formatting
When making changes, ensure type checks and linting still pass:
python3 -m venv venv
. venv/bin/activate
pip install --group lint
mypy; ruff format; ruff check
Note that pip >=25.1 is necessary for --group support.
Ideally the gpiod library will continue to pass strict checks:
mypy --strict