mirror of
https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git
synced 2026-10-25 12:39:18 +03:00
c9378d6c63
PEP 703 [0] discusses making the GIL optional in certain builds of the CPython interpreter. This build option was available experiementally in Python 3.13 but has since been stabilized in Python 3.14 per PEP 779 [1]. According to the porting guide [2], there is no strict requirement that C extensions must be thread-safe. Experiments have shown that no logic changes are required if callers use sychronization mechanisms provided by the Python standard library. The documentation has been updated to call this out specifically using terminology from the porting guide [3]. [0]: https://peps.python.org/pep-0703/ [1]: https://peps.python.org/pep-0779/ [2]: https://py-free-threading.github.io/porting/#define-and-document-thread-safety-guarantees [3]: https://py-free-threading.github.io/documentation-principles/#free-threading-terminology Signed-off-by: Vincent Fazio <vfazio@gmail.com> Link: https://patch.msgid.link/20260527215922.18678-3-vfazio@gmail.com Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@oss.qualcomm.com>
140 lines
3.3 KiB
Markdown
140 lines
3.3 KiB
Markdown
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
|
|
<!-- SPDX-FileCopyrightText: 2023 Phil Howard <phil@gadgetoid.com> -->
|
|
|
|
# gpiod
|
|
|
|
These are the official Python bindings for [libgpiod](https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/about/).
|
|
|
|
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:
|
|
|
|
```python
|
|
import gpiod
|
|
|
|
gpiod.is_gpiochip_device("/dev/gpiochip0")
|
|
|
|
```
|
|
|
|
Get information about a GPIO chip character device:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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
|
|
```
|