gpiod 2.2.4__tar.gz → 2.3.0__tar.gz

{gpiod-2.2.4 → gpiod-2.3.0}/MANIFEST.in

@@ -13,7 +13,7 @@ recursive-include gpiod/ext *.c
 recursive-include gpiod/ext *.h
 
 recursive-include tests/gpiosim *.c
-recursive-include tests/procname *.c
+recursive-include tests/system *.c
 
 recursive-include lib *.c
 recursive-include lib *.h

{gpiod-2.2.4/gpiod.egg-info → gpiod-2.3.0}/PKG-INFO

@@ -1,23 +1,26 @@
 Metadata-Version: 2.2
 Name: gpiod
-Version: 2.2.4
+Version: 2.3.0
 Summary: Python bindings for libgpiod
-Home-page: https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git
-Author: Bartosz Golaszewski
-Author-email: brgl@bgdev.pl
-License: LGPLv2.1
+Author-email: Bartosz Golaszewski <brgl@bgdev.pl>
+License: LGPL-2.1-or-later
+Project-URL: Homepage, https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git
+Project-URL: Issues, https://github.com/brgl/libgpiod/issues/
 Platform: linux
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v2 or later (LGPLv2+)
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.9.0
 Description-Content-Type: text/markdown
-Dynamic: author
-Dynamic: author-email
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license
-Dynamic: platform
-Dynamic: requires-python
-Dynamic: summary
 
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
 <!-- SPDX-FileCopyrightText: 2023 Phil Howard <phil@gadgetoid.com> -->
@@ -133,3 +136,20 @@ make python-tests-run
 
 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 mypy ruff
+mypy; ruff format; ruff check
+```
+
+Ideally the gpiod library will continue to pass strict checks:
+
+```
+mypy --strict
+```

{gpiod-2.2.4 → gpiod-2.3.0}/README.md

@@ -112,3 +112,20 @@ make python-tests-run
 
 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 mypy ruff
+mypy; ruff format; ruff check
+```
+
+Ideally the gpiod library will continue to pass strict checks:
+
+```
+mypy --strict
+```

{gpiod-2.2.4 → gpiod-2.3.0}/build_tests.py

@@ -11,7 +11,7 @@ polluted with artefacts in build/
 Builds:
 
     tests/gpiosim/_ext.<target>.so
-    tests/procname/_ext.<target>.so
+    tests/system/_ext.<target>.so
 
 """
 
@@ -61,9 +61,9 @@ gpiosim_ext = Extension(
     ],
 )
 
-procname_ext = Extension(
-    "tests.procname._ext",
-    sources=["tests/procname/ext.c"],
+system_ext = Extension(
+    "tests.system._ext",
+    sources=["tests/system/ext.c"],
     define_macros=[("_GNU_SOURCE", "1")],
     extra_compile_args=["-Wall", "-Wextra"],
 )
@@ -71,7 +71,7 @@ procname_ext = Extension(
 dist = Distribution(
     {
         "name": "gpiod",
-        "ext_modules": [gpiosim_ext, procname_ext, gpiod_ext],
+        "ext_modules": [gpiosim_ext, system_ext, gpiod_ext],
         "version": __version__,
         "platforms": ["linux"],
     }
@@ -82,9 +82,13 @@ try:
 
     configure()
 except ImportError:
-    from distutils.log import DEBUG, set_verbosity
+    try:
+        from distutils.log import DEBUG, set_verbosity
 
-    set_verbosity(DEBUG)
+        set_verbosity(DEBUG)
+    except ImportError:
+        # We can still build the tests, it will just be very quiet.
+        pass
 
 with tempfile.TemporaryDirectory(prefix="libgpiod-") as temp_dir:
     command = build_ext(dist)

gpiod-2.3.0/gpiod/__init__.py

@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# SPDX-FileCopyrightText: 2022 Bartosz Golaszewski <brgl@bgdev.pl>
+
+"""
+Python bindings for libgpiod.
+
+This module wraps the native C API of libgpiod in a set of python classes.
+"""
+
+from collections.abc import Iterable
+from typing import Optional, Union
+
+from . import (
+    _ext,
+    chip,
+    chip_info,
+    edge_event,
+    exception,
+    info_event,
+    line,
+    line_info,
+    line_request,
+    line_settings,
+    version,
+)
+from .chip import *
+from .chip_info import *
+from .edge_event import *
+from .exception import *
+from .info_event import *
+from .line_info import *
+from .line_request import *
+from .line_settings import *
+from .version import __version__
+
+api_version = _ext.api_version
+
+# public submodules
+__all__ = [
+    "chip",
+    "chip_info",
+    "edge_event",
+    "exception",
+    "info_event",
+    "line",
+    "line_info",
+    "line_request",
+    "line_settings",
+    "version",
+]
+
+# re-export public submodule exports
+# do not re-export line objects, this is not an oversight
+__all__ += (
+    chip.__all__
+    + chip_info.__all__
+    + edge_event.__all__
+    + exception.__all__
+    + info_event.__all__
+    + line_info.__all__
+    + line_request.__all__
+    + line_settings.__all__
+)
+
+# module methods/attributes
+__all__ += [
+    "__version__",
+    "api_version",
+    "is_gpiochip_device",
+    "request_lines",
+]
+
+
+def is_gpiochip_device(path: str) -> bool:
+    """
+    Check if the file pointed to by path is a GPIO chip character device.
+
+    Args:
+      path
+        Path to the file that should be checked.
+
+    Returns:
+      Returns true if so, False otherwise.
+    """
+    return _ext.is_gpiochip_device(path)
+
+
+def request_lines(
+    path: str,
+    config: dict[Union[Iterable[Union[int, str]], int, str], Optional[LineSettings]],
+    consumer: Optional[str] = None,
+    event_buffer_size: Optional[int] = None,
+    output_values: Optional[dict[Union[int, str], line.Value]] = None,
+) -> LineRequest:
+    """
+    Open a GPIO chip pointed to by 'path', request lines according to the
+    configuration arguments, close the chip and return the request object.
+
+    Args:
+      path
+        Path to the GPIO character device file.
+      config:
+        Dictionary mapping offsets or names (or tuples thereof) to
+        LineSettings. If None is passed as the value of the mapping,
+        default settings are used.
+      consumer:
+        Consumer string to use for this request.
+      event_buffer_size:
+        Size of the kernel edge event buffer to configure for this request.
+      output_values:
+        Dictionary mapping offsets or names to line.Value. This can be used
+        to set the desired output values globally while reusing LineSettings
+        for more lines.
+
+    Returns:
+      Returns a new LineRequest object.
+    """
+    with Chip(path) as chip:
+        return chip.request_lines(
+            config=config,
+            consumer=consumer,
+            event_buffer_size=event_buffer_size,
+            output_values=output_values,
+        )

gpiod-2.3.0/gpiod/_ext.pyi

@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# SPDX-FileCopyrightText: 2024 Vincent Fazio <vfazio@gmail.com>
+
+from typing import Optional
+
+from .chip_info import ChipInfo
+from .edge_event import EdgeEvent
+from .info_event import InfoEvent
+from .line import Value
+from .line_info import LineInfo
+
+class LineSettings:
+    def __init__(
+        self,
+        direction: int,
+        edge_detection: int,
+        bias: int,
+        drive: int,
+        active_low: bool,
+        debounce_period: int,
+        event_clock: int,
+        output_value: int,
+    ) -> None: ...
+
+class LineConfig:
+    def __init__(self) -> None: ...
+    def add_line_settings(self, offsets: list[int], settings: LineSettings) -> None: ...
+    def set_output_values(self, global_output_values: list[Value]) -> None: ...
+
+class Request:
+    def release(self) -> None: ...
+    def get_values(self, offsets: list[int], values: list[Value]) -> None: ...
+    def set_values(self, values: dict[int, Value]) -> None: ...
+    def reconfigure_lines(self, line_cfg: LineConfig) -> None: ...
+    def read_edge_events(self, max_events: Optional[int]) -> list[EdgeEvent]: ...
+    @property
+    def chip_name(self) -> str: ...
+    @property
+    def num_lines(self) -> int: ...
+    @property
+    def offsets(self) -> list[int]: ...
+    @property
+    def fd(self) -> int: ...
+
+class Chip:
+    def __init__(self, path: str) -> None: ...
+    def get_info(self) -> ChipInfo: ...
+    def line_offset_from_id(self, id: str) -> int: ...
+    def get_line_info(self, offset: int, watch: bool) -> LineInfo: ...
+    def request_lines(
+        self,
+        line_cfg: LineConfig,
+        consumer: Optional[str],
+        event_buffer_size: Optional[int],
+    ) -> Request: ...
+    def read_info_event(self) -> InfoEvent: ...
+    def close(self) -> None: ...
+    def unwatch_line_info(self, line: int) -> None: ...
+    @property
+    def path(self) -> str: ...
+    @property
+    def fd(self) -> int: ...
+
+def is_gpiochip_device(path: str) -> bool: ...
+
+api_version: str
+
+# enum constants
+BIAS_AS_IS: int
+BIAS_DISABLED: int
+BIAS_PULL_DOWN: int
+BIAS_PULL_UP: int
+BIAS_UNKNOWN: int
+CLOCK_HTE: int
+CLOCK_MONOTONIC: int
+CLOCK_REALTIME: int
+DIRECTION_AS_IS: int
+DIRECTION_INPUT: int
+DIRECTION_OUTPUT: int
+DRIVE_OPEN_DRAIN: int
+DRIVE_OPEN_SOURCE: int
+DRIVE_PUSH_PULL: int
+EDGE_BOTH: int
+EDGE_EVENT_TYPE_FALLING: int
+EDGE_EVENT_TYPE_RISING: int
+EDGE_FALLING: int
+EDGE_NONE: int
+EDGE_RISING: int
+INFO_EVENT_TYPE_LINE_CONFIG_CHANGED: int
+INFO_EVENT_TYPE_LINE_RELEASED: int
+INFO_EVENT_TYPE_LINE_REQUESTED: int
+VALUE_ACTIVE: int
+VALUE_INACTIVE: int

gpiod-2.2.4/gpiod/internal.py → gpiod-2.3.0/gpiod/_internal.py

@@ -1,14 +1,15 @@
-# SPDX-License-Identifier: GPL-2.0-or-later
+# SPDX-License-Identifier: LGPL-2.1-or-later
 # SPDX-FileCopyrightText: 2022 Bartosz Golaszewski <brgl@bgdev.pl>
 
 from datetime import timedelta
 from select import select
 from typing import Optional, Union
 
-__all__ = []
+__all__ = ["poll_fd"]
 
 
 def poll_fd(fd: int, timeout: Optional[Union[timedelta, float]] = None) -> bool:
+    sec: Union[float, None]
     if isinstance(timeout, timedelta):
         sec = timeout.total_seconds()
     else:

{gpiod-2.2.4 → gpiod-2.3.0}/gpiod/chip.py

@@ -1,22 +1,29 @@
 # SPDX-License-Identifier: LGPL-2.1-or-later
 # SPDX-FileCopyrightText: 2022 Bartosz Golaszewski <brgl@bgdev.pl>
 
+from __future__ import annotations
+
+from collections import Counter
+from errno import ENOENT
+from typing import TYPE_CHECKING, Optional, Union, cast
+
 from . import _ext
-from .chip_info import ChipInfo
+from ._internal import poll_fd
 from .exception import ChipClosedError
-from .info_event import InfoEvent
-from .internal import poll_fd
 from .line import Value
-from .line_info import LineInfo
-from .line_settings import LineSettings, _line_settings_to_ext
 from .line_request import LineRequest
-from collections import Counter
-from collections.abc import Iterable
-from datetime import timedelta
-from errno import ENOENT
-from typing import Union, Optional
+from .line_settings import LineSettings, _line_settings_to_ext
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+    from datetime import timedelta
+    from types import TracebackType
+
+    from .chip_info import ChipInfo
+    from .info_event import InfoEvent
+    from .line_info import LineInfo
 
-__all__ = "Chip"
+__all__ = ["Chip"]
 
 
 class Chip:
@@ -32,7 +39,7 @@ class Chip:
     Callers must close the chip by calling the close() method when it's no longer
     used.
 
-    Example:
+    Example::
 
         chip = gpiod.Chip(\"/dev/gpiochip0\")
         do_something(chip)
@@ -40,7 +47,7 @@ class Chip:
 
     The gpiod.Chip class also supports controlled execution ('with' statement).
 
-    Example:
+    Example::
 
         with gpiod.Chip(path="/dev/gpiochip0") as chip:
             do_something(chip)
@@ -54,8 +61,8 @@ class Chip:
           path:
             Path to the GPIO character device file.
         """
-        self._chip = _ext.Chip(path)
-        self._info = None
+        self._chip: Union[_ext.Chip, None] = _ext.Chip(path)
+        self._info: Union[ChipInfo, None] = None
 
     def __bool__(self) -> bool:
         """
@@ -66,14 +73,19 @@ class Chip:
         """
         return True if self._chip else False
 
-    def __enter__(self):
+    def __enter__(self) -> Chip:
         """
         Controlled execution enter callback.
         """
         self._check_closed()
         return self
 
-    def __exit__(self, exc_type, exc_value, traceback) -> None:
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc_value: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
         """
         Controlled execution exit callback.
         """
@@ -89,7 +101,7 @@ class Chip:
         longer be used after this method is called.
         """
         self._check_closed()
-        self._chip.close()
+        cast(_ext.Chip, self._chip).close()
         self._chip = None
 
     def get_info(self) -> ChipInfo:
@@ -102,7 +114,7 @@ class Chip:
         self._check_closed()
 
         if not self._info:
-            self._info = self._chip.get_info()
+            self._info = cast(_ext.Chip, self._chip).get_info()
 
         return self._info
 
@@ -127,7 +139,7 @@ class Chip:
 
         if not isinstance(id, int):
             try:
-                return self._chip.line_offset_from_id(id)
+                return cast(_ext.Chip, self._chip).line_offset_from_id(id)
             except OSError as ex:
                 if ex.errno == ENOENT:
                     try:
@@ -146,7 +158,9 @@ class Chip:
 
     def _get_line_info(self, line: Union[int, str], watch: bool) -> LineInfo:
         self._check_closed()
-        return self._chip.get_line_info(self.line_offset_from_id(line), watch)
+        return cast(_ext.Chip, self._chip).get_line_info(
+            self.line_offset_from_id(line), watch
+        )
 
     def get_line_info(self, line: Union[int, str]) -> LineInfo:
         """
@@ -184,7 +198,9 @@ class Chip:
             Offset or name of the line to stop watching.
         """
         self._check_closed()
-        return self._chip.unwatch_line_info(self.line_offset_from_id(line))
+        return cast(_ext.Chip, self._chip).unwatch_line_info(
+            self.line_offset_from_id(line)
+        )
 
     def wait_info_event(
         self, timeout: Optional[Union[timedelta, float]] = None
@@ -218,11 +234,13 @@ class Chip:
           This function may block if there are no available events in the queue.
         """
         self._check_closed()
-        return self._chip.read_info_event()
+        return cast(_ext.Chip, self._chip).read_info_event()
 
     def request_lines(
         self,
-        config: dict[tuple[Union[int, str]], Optional[LineSettings]],
+        config: dict[
+            Union[Iterable[Union[int, str]], int, str], Optional[LineSettings]
+        ],
         consumer: Optional[str] = None,
         event_buffer_size: Optional[int] = None,
         output_values: Optional[dict[Union[int, str], Value]] = None,
@@ -251,7 +269,7 @@ class Chip:
 
         line_cfg = _ext.LineConfig()
 
-        # Sanitize lines - don't allow offset repeatitions or offset-name conflicts.
+        # Sanitize lines - don't allow offset repetitions or offset-name conflicts.
         for offset, count in Counter(
             [
                 self.line_offset_from_id(line)
@@ -264,9 +282,7 @@ class Chip:
         ).items():
             if count != 1:
                 raise ValueError(
-                    "line must be configured exactly once - offset {} repeats".format(
-                        offset
-                    )
+                    f"line must be configured exactly once - offset {offset} repeats"
                 )
 
         # If we have global output values - map line names to offsets
@@ -312,7 +328,9 @@ class Chip:
         if len(global_output_values):
             line_cfg.set_output_values(global_output_values)
 
-        req_internal = self._chip.request_lines(line_cfg, consumer, event_buffer_size)
+        req_internal = cast(_ext.Chip, self._chip).request_lines(
+            line_cfg, consumer, event_buffer_size
+        )
         request = LineRequest(req_internal)
 
         request._chip_name = req_internal.chip_name
@@ -326,6 +344,12 @@ class Chip:
 
         return request
 
+    def fileno(self) -> int:
+        """
+        Return the underlying file descriptor.
+        """
+        return self.fd
+
     def __repr__(self) -> str:
         """
         Return a string that can be used to re-create this chip object.
@@ -333,7 +357,7 @@ class Chip:
         if not self._chip:
             return "<Chip CLOSED>"
 
-        return 'gpiod.Chip("{}")'.format(self.path)
+        return f'gpiod.Chip("{self.path}")'
 
     def __str__(self) -> str:
         """
@@ -342,9 +366,7 @@ class Chip:
         if not self._chip:
             return "<Chip CLOSED>"
 
-        return '<Chip path="{}" fd={} info={}>'.format(
-            self.path, self.fd, self.get_info()
-        )
+        return f'<Chip path="{self.path}" fd={self.fd} info={self.get_info()}>'
 
     @property
     def path(self) -> str:
@@ -352,7 +374,7 @@ class Chip:
         Filesystem path used to open this chip.
         """
         self._check_closed()
-        return self._chip.path
+        return cast(_ext.Chip, self._chip).path
 
     @property
     def fd(self) -> int:
@@ -360,4 +382,4 @@ class Chip:
         File descriptor associated with this chip.
         """
         self._check_closed()
-        return self._chip.fd
+        return cast(_ext.Chip, self._chip).fd

{gpiod-2.2.4 → gpiod-2.3.0}/gpiod/chip_info.py

@@ -4,7 +4,7 @@
 
 from dataclasses import dataclass
 
-__all__ = "ChipInfo"
+__all__ = ["ChipInfo"]
 
 
 @dataclass(frozen=True, repr=False)
@@ -14,10 +14,13 @@ class ChipInfo:
     """
 
     name: str
+    """Name of the chip."""
+
     label: str
+    """Label of the chip."""
+
     num_lines: int
+    """Number of lines exposed by the chip."""
 
-    def __str__(self):
-        return '<ChipInfo name="{}" label="{}" num_lines={}>'.format(
-            self.name, self.label, self.num_lines
-        )
+    def __str__(self) -> str:
+        return f'<ChipInfo name="{self.name}" label="{self.label}" num_lines={self.num_lines}>'

{gpiod-2.2.4 → gpiod-2.3.0}/gpiod/edge_event.py

@@ -1,11 +1,12 @@
 # SPDX-License-Identifier: LGPL-2.1-or-later
 # SPDX-FileCopyrightText: 2022 Bartosz Golaszewski <brgl@bgdev.pl>
 
-from . import _ext
 from dataclasses import dataclass
 from enum import Enum
 
-__all__ = "EdgeEvent"
+from . import _ext
+
+__all__ = ["EdgeEvent"]
 
 
 @dataclass(frozen=True, init=False, repr=False)
@@ -15,14 +16,23 @@ class EdgeEvent:
     """
 
     class Type(Enum):
+        """Possible edge event types."""
+
         RISING_EDGE = _ext.EDGE_EVENT_TYPE_RISING
+        """Rising edge event."""
         FALLING_EDGE = _ext.EDGE_EVENT_TYPE_FALLING
+        """Falling edge event."""
 
     event_type: Type
+    """Edge event type."""
     timestamp_ns: int
+    """Timestamp of the event in nanoseconds."""
     line_offset: int
+    """Offset of the line on which this event was registered."""
     global_seqno: int
+    """Global sequence number of this event."""
     line_seqno: int
+    """Event sequence number specific to the concerned line."""
 
     def __init__(
         self,
@@ -38,8 +48,8 @@ class EdgeEvent:
         object.__setattr__(self, "global_seqno", global_seqno)
         object.__setattr__(self, "line_seqno", line_seqno)
 
-    def __str__(self):
-        return "<EdgeEvent type={} timestamp_ns={} line_offset={} global_seqno={} line_seqno={}>".format(
+    def __str__(self) -> str:
+        return "<EdgeEvent type={} timestamp_ns={} line_offset={} global_seqno={} line_seqno={}>".format(  # noqa: UP032
             self.event_type,
             self.timestamp_ns,
             self.line_offset,