diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 86b1a34f98..2f0d3f995d 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -43,3 +43,4 @@ jobs: uses: pypa/gh-action-pypi-publish@release/v1 with: password: ${{ secrets.PYPI_API_TOKEN }} + packages-dir: src/bindings/python/dist/ diff --git a/build-scripts/build-bindings.sh b/build-scripts/build-bindings.sh index 840caeaba3..395bc7de79 100644 --- a/build-scripts/build-bindings.sh +++ b/build-scripts/build-bindings.sh @@ -11,13 +11,15 @@ VERSION="$(meson introspect --projectinfo builddir | jq -r '.version')" function python() { # Package python bindings PYTHON_BINDINGS_DIR="src/bindings/python/" + cd $PYTHON_BINDINGS_DIR + ## Set version and release sed \ -e "s|@VERSION@|${VERSION}|g" \ - < $PYTHON_BINDINGS_DIR"setup.py.in" \ - > $PYTHON_BINDINGS_DIR"setup.py" - - python3 $PYTHON_BINDINGS_DIR"setup.py" bdist_wheel --dist-dir=dist/ + < "setup.py.in" \ + > "setup.py" + + python3 "setup.py" bdist_wheel --dist-dir=dist/ } echo "Building bindings $1" diff --git a/doc/docs/api/bindings.md b/doc/docs/api/bindings.md new file mode 100644 index 0000000000..8255ccd6ed --- /dev/null +++ b/doc/docs/api/bindings.md @@ -0,0 +1,74 @@ + +# D-Bus API bindings + +Hirte provides for its public API +[introspection data](https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format) in the +[data directory](https://github.com/containers/hirte/tree/main/data). These XML files can be used as input to code +generation tools to create clients for using the described D-Bus API in various programming languages. +For example: + +- `C`: [gdbus-codegen](https://developer-old.gnome.org/gio/stable/gdbus-codegen.html) +- `Go`: [dbus-codegen-go](https://github.com/amenzhinsky/dbus-codegen-go) +- `Rust`: [dbus-codegen-rust](https://crates.io/crates/dbus-codegen) +- and many more + +## pyhirte + +For `python`, the dynamically generated proxies (e.g. from [dasbus](https://github.com/rhinstaller/dasbus)) don't +require such a generation and work well on their own. These proxies, however, don't provide type hints. Because of that +the hirte project provides `pyhirte` - auto-generated, typed python bindings. + +### Installation + +Install `pyhirte` via: + +```bash +# from rpm package +dnf install python3-pyhirte + +# or from PyPI +pip install pyhirte +``` + +### Usage + +The following code snippets showcase how `pyhirte` can be used: + +```python +# starting a systemd unit +--8<-- "pyhirte-examples/StartUnit:5" + +# and stopping it again +--8<-- "pyhirte-examples/StopUnit:7" +``` + +```python +# enabling a systemd unit to be executed on startup +--8<-- "pyhirte-examples/EnableUnit:5" + +# and disabling it again +--8<-- "pyhirte-examples/DisableUnit:7" +``` + +```python +# listing all nodes +--8<-- "pyhirte-examples/ListAllNodes:5" +``` + +```python +# listing all units on all nodes +--8<-- "pyhirte-examples/ListNodeUnits:5" + + +# or easily filter them and only display active services +--8<-- "pyhirte-examples/ListActiveServices:5" +``` + +```python +# getting properties from systemd units +# e.g. the CPUWeight +--8<-- "pyhirte-examples/CPUWeight:5" + +# and setting values for them +--8<-- "pyhirte-examples/SetCPUWeight:5" +``` diff --git a/doc/docs/getting_started.md b/doc/docs/getting_started.md index 9492ab34bc..99ca24593a 100644 --- a/doc/docs/getting_started.md +++ b/doc/docs/getting_started.md @@ -5,9 +5,13 @@ On Fedora systems, hirte can be directly installed from the Fedora repository. On CentOS-Stream systems, it can be installed using the COPR repository shipping -the latest hirte code. That repository can be enabled using: dnf copr enable -mperina/hirte-snapshot centos-stream-9. This should no longer be necessary once -hirte is made available in EPEL. +the latest hirte code. That repository can be enabled using: + +```bash +dnf copr enable mperina/hirte-snapshot centos-stream-9 +``` + +This should no longer be necessary once hirte is made available in EPEL. On the laptop install both hirte and the hirte-agent via this command: diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml index 4743287b8f..5a2d9a75d2 100644 --- a/doc/mkdocs.yml +++ b/doc/mkdocs.yml @@ -12,6 +12,7 @@ nav: - DBus API: - Description: api/description.md - Examples: api/examples.md + - Bindings: api/bindings.md - Proxy Services: proxy_services.md - MAN Pages: - Binaries: diff --git a/src/bindings/examples/python/CPUWeight b/doc/pyhirte-examples/CPUWeight similarity index 100% rename from src/bindings/examples/python/CPUWeight rename to doc/pyhirte-examples/CPUWeight diff --git a/src/bindings/examples/python/DisableUnit b/doc/pyhirte-examples/DisableUnit similarity index 100% rename from src/bindings/examples/python/DisableUnit rename to doc/pyhirte-examples/DisableUnit diff --git a/src/bindings/examples/python/EnableUnit b/doc/pyhirte-examples/EnableUnit similarity index 100% rename from src/bindings/examples/python/EnableUnit rename to doc/pyhirte-examples/EnableUnit diff --git a/src/bindings/examples/python/ListActiveServices b/doc/pyhirte-examples/ListActiveServices similarity index 100% rename from src/bindings/examples/python/ListActiveServices rename to doc/pyhirte-examples/ListActiveServices diff --git a/src/bindings/examples/python/ListAllNodes b/doc/pyhirte-examples/ListAllNodes similarity index 100% rename from src/bindings/examples/python/ListAllNodes rename to doc/pyhirte-examples/ListAllNodes diff --git a/src/bindings/examples/python/ListNodeUnits b/doc/pyhirte-examples/ListNodeUnits similarity index 100% rename from src/bindings/examples/python/ListNodeUnits rename to doc/pyhirte-examples/ListNodeUnits diff --git a/src/bindings/examples/python/SetCPUWeight b/doc/pyhirte-examples/SetCPUWeight similarity index 100% rename from src/bindings/examples/python/SetCPUWeight rename to doc/pyhirte-examples/SetCPUWeight diff --git a/src/bindings/examples/python/StartUnit b/doc/pyhirte-examples/StartUnit similarity index 100% rename from src/bindings/examples/python/StartUnit rename to doc/pyhirte-examples/StartUnit diff --git a/src/bindings/examples/python/StopUnit b/doc/pyhirte-examples/StopUnit similarity index 100% rename from src/bindings/examples/python/StopUnit rename to doc/pyhirte-examples/StopUnit diff --git a/src/bindings/README.md b/src/bindings/README.md index f2a6831f4f..dee61f2aea 100644 --- a/src/bindings/README.md +++ b/src/bindings/README.md @@ -8,4 +8,3 @@ functions are written to simplify recurring tasks. - [bindings/generator](./generator/): small python project used to generate client code for the D-Bus API - [bindinds/python](./python/): python client for hirte -- [bindings/examples](./examples/): contains example code for using the bindings diff --git a/src/bindings/python/setup.py b/src/bindings/python/setup.py index 0ab5e10634..116e2ce803 100644 --- a/src/bindings/python/setup.py +++ b/src/bindings/python/setup.py @@ -12,6 +12,7 @@ def readme(): version="0.4.0", description="Python bindings for hirte's D-Bus API", long_description=readme(), + long_description_content_type="text/markdown", author="Hirte developers", url="https://github.com/containers/hirte/", license="LGPL-2.0-or-later", diff --git a/src/bindings/python/setup.py.in b/src/bindings/python/setup.py.in index 4afc59cd4e..747fda7ca9 100644 --- a/src/bindings/python/setup.py.in +++ b/src/bindings/python/setup.py.in @@ -12,6 +12,7 @@ setup( version="@VERSION@", description="Python bindings for hirte's D-Bus API", long_description=readme(), + long_description_content_type="text/markdown", author="Hirte developers", url="https://github.com/containers/hirte/", license="LGPL-2.0-or-later",