From 4faf1d8fd0adc1b3bc2bdf823fdd4d5a8d061391 Mon Sep 17 00:00:00 2001 From: Marian Buschsieweke Date: Tue, 28 Apr 2026 15:58:53 +0200 Subject: [PATCH 1/3] dist/tools/usb-serial: use `uv run` for as runner This allows users to not having to care about python dependencies. In addition SPDX annotations have been added. --- dist/tools/usb-serial/ttys.py | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/dist/tools/usb-serial/ttys.py b/dist/tools/usb-serial/ttys.py index 38b6ed3415ac..402337cd5715 100755 --- a/dist/tools/usb-serial/ttys.py +++ b/dist/tools/usb-serial/ttys.py @@ -1,4 +1,15 @@ -#!/usr/bin/env python3 +#!/usr/bin/env -S uv run + +# SPDX-FileCopyrightText: 2023 Otto-von-Guericke-Universität Magdeburg +# SPDX-FileCopyrightText: 2026 ML!PA Consulting GmbH +# SPDX-License-Identifier: LGPL-2.1-only + +# /// script +# requires-python = ">=3.10" +# dependencies = [ +# "pyudev" +# ] +# /// """ Command line utility to list and filter TTYs """ From e3604b8464818abe6be04eab0c76f41a9305614d Mon Sep 17 00:00:00 2001 From: Marian Buschsieweke Date: Thu, 4 Jun 2026 17:28:50 +0200 Subject: [PATCH 2/3] tools, build system: introduce PYTHON3_WITH_PEP723 - Document that Python scripts should use [PEP 723 Inline script metadata][pep723] - Add `PYTHON3_WITH_PEP723` as variable to allow uers to switch their running, such as `uv run` or `pipx run` or even just `python3` - Document that in the CI preparing a venv on demand is not acceptable, set `PYTHON3_WITH_PEP723` to `python3` in the CI [pep723]: https://peps.python.org/pep-0723/ --- .murdock | 1 + CODING_CONVENTIONS.md | 21 +++++++++++++++++++-- Makefile.include | 8 +++++++- 3 files changed, 27 insertions(+), 3 deletions(-) diff --git a/.murdock b/.murdock index 416a7cffbfbf..711dfd3e62fe 100755 --- a/.murdock +++ b/.murdock @@ -52,6 +52,7 @@ export CFLAGS_DBG="" export DLCACHE_DIR=${DLCACHE_DIR:-~/.dlcache} export ENABLE_TEST_CACHE=${ENABLE_TEST_CACHE:-1} export MURDOCK_REDIS_HOST=${MURDOCK_REDIS_HOST:-127.0.0.1} +export PYTHON3_WITH_PEP723=python3 NIGHTLY=${NIGHTLY:-0} diff --git a/CODING_CONVENTIONS.md b/CODING_CONVENTIONS.md index c3c414b77534..4509a07246a1 100644 --- a/CODING_CONVENTIONS.md +++ b/CODING_CONVENTIONS.md @@ -701,15 +701,32 @@ not a string literal`. [McCabe project](https://pypi.python.org/pypi/mccabe) * A line length of maximum of 120 is allowed instead of 79 as per PEP 8. This increases tests readability as they can expects long line of output. -* Only runnable scripts shall start with `#!/usr/bin/env python3` +* All runnable scripts and only runnable scripts **MUST** have a shebang +* Runnable scripts **SHOULD** use `#!/usr/bin/env -S uv run` as shebang +* [PEP 723 Inline script metadata](https://peps.python.org/pep-0723/) **SHOULD** + be used for runnable scripts to declare dependencies +* Calls to the python executables from the build system **MUST** be done with + the wrapper `PYTHON3_WITH_PEP723` if the have PEP 723 annotations. + * E.g. to run `dist/tools/fancy/fancy.py` use the following snippet: + `$(Q)$(PYTHON3_WITH_PEP723) $(RIOTTOOLS)/fancy/fancy.py` + * In the CI, `PYTHON3_WITH_PEP723` is overwritten as `python3` and the + CI container **MUST** ship all required python modules to avoid duplicate + downloads and slower CI time due to venv setup time * Runnable scripts shall use the following scheme: ```python -#!/usr/bin/env python3 +#!/usr/bin/env -S uv run # SPDX-FileCopyrightText: 2026 # SPDX-License-Identifier: LGPL-2.1-only +# /// script +# requires-python = ">=3.10" +# dependencies = [ +# "pyudev" +# ] +# /// + # put the module imports first # see https://www.python.org/dev/peps/pep-0008/#imports # for more details diff --git a/Makefile.include b/Makefile.include index 75f70b77a4c3..ad2c58fc9b57 100644 --- a/Makefile.include +++ b/Makefile.include @@ -186,6 +186,12 @@ OS_ARCH = $(word 2, $(UNAME)) # set python path, e.g. for tests PYTHONPATH := $(RIOTBASE)/dist/pythonlibs/:$(PYTHONPATH) +# Set python3 frontend capable of PEP 723 inline script metadata. Users may +# choose `pipx run` or just `python3` instead. In case of just `python3`, there +# will be no PEP 723 support and users will just have to install the right +# python modules beforehand. +PYTHON3_WITH_PEP723 ?= uv run + # Basic utilities included before anything else include $(RIOTMAKE)/utils/checks.mk @@ -877,7 +883,7 @@ cleanterm: $(TERMDEPS) $(TERMPROG) $(TERMFLAGS) $(TERMTEE) list-ttys: - $(Q)$(RIOTTOOLS)/usb-serial/ttys.py + $(Q)$(PYTHON3_WITH_PEP723) $(RIOTTOOLS)/usb-serial/ttys.py doc doc-man doc-latex: $(MAKE) -C $(RIOTBASE) $@ From 184586aac7e3ace516f523876e5cb750bc111c36 Mon Sep 17 00:00:00 2001 From: Marian Buschsieweke Date: Fri, 5 Jun 2026 15:28:04 +0200 Subject: [PATCH 3/3] Update CODING_CONVENTIONS.md Co-authored-by: crasbe --- CODING_CONVENTIONS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CODING_CONVENTIONS.md b/CODING_CONVENTIONS.md index 4509a07246a1..76e5d37e36b3 100644 --- a/CODING_CONVENTIONS.md +++ b/CODING_CONVENTIONS.md @@ -706,7 +706,7 @@ not a string literal`. * [PEP 723 Inline script metadata](https://peps.python.org/pep-0723/) **SHOULD** be used for runnable scripts to declare dependencies * Calls to the python executables from the build system **MUST** be done with - the wrapper `PYTHON3_WITH_PEP723` if the have PEP 723 annotations. + the wrapper `PYTHON3_WITH_PEP723` if they have PEP 723 annotations. * E.g. to run `dist/tools/fancy/fancy.py` use the following snippet: `$(Q)$(PYTHON3_WITH_PEP723) $(RIOTTOOLS)/fancy/fancy.py` * In the CI, `PYTHON3_WITH_PEP723` is overwritten as `python3` and the