bindings: python: move long_description into README.md

Move the long_description into README.md and include some basic
information about libgpiod, and some simple Python example code.

Signed-off-by: Phil Howard <phil@gadgetoid.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

diff --git a/bindings/python/MANIFEST.in b/bindings/python/MANIFEST.in
index c7124d42788308da5de94f3cff9c923fc606aebb..459b317024864b010a66a3be64a2a0526d513590 100644 (file)
--- a/bindings/python/MANIFEST.in
+++ b/bindings/python/MANIFEST.in
@@ -2,6 +2,7 @@
 # SPDX-FileCopyrightText: 2023 Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
 
 include setup.py
+include README.md
 
 recursive-include gpiod *.py
 recursive-include tests *.py

diff --git a/bindings/python/README.md b/bindings/python/README.md
new file mode 100644 (file)
index 0000000..abb69da
--- /dev/null
+++ b/bindings/python/README.md
@@ -0,0 +1,104 @@
+# 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/).
+
+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 not provided. 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)
+```
+

diff --git a/bindings/python/setup.py b/bindings/python/setup.py
index 0fb9581f9cc0a1b155e7e717ff51b812b864daf2..c8db0a0e2699ec61a4b6d5a3c5efe2e8cf9767c1 100644 (file)
--- a/bindings/python/setup.py
+++ b/bindings/python/setup.py
@@ -67,8 +67,8 @@ setup(
     author="Bartosz Golaszewski",
     author_email="brgl@bgdev.pl",
     description="Python bindings for libgpiod",
-    long_description="This is a package spun out of the main libgpiod repository containing " \
-                     "python bindings to the underlying C library.",
+    long_description=open("README.md", "r").read(),
+    long_description_content_type="text/markdown",
     platforms=["linux"],
     license="LGPLv2.1",
 )