* [PATCH 00/13] Improve or add oe.* library docstrings
@ 2026-11-16 16:08 Antonin Godard
2026-11-16 16:08 ` [PATCH 01/13] lib/oe/path: rename "metadata" parameter to "d" Antonin Godard
` (12 more replies)
0 siblings, 13 replies; 16+ messages in thread
From: Antonin Godard @ 2026-11-16 16:08 UTC (permalink / raw)
To: openembedded-core; +Cc: Antonin Godard, Thomas Petazzoni
Improve the docstrings of useful oe library modules and format them for
inclusion with the sphinx.ext.autodoc extension. This allows presenting
the documentation like in [1].
The series is divided in two parts:
- Patch 01 to 05 are code fixups, they do not contains documentation
changes, but are relevant to provide a meaningful and consistent
documentation.
Some are breaking changes and scould be debated, but I believe for
most it does make sense to make the change, especially for
understanding how the function works in documentation.
- Patch 06 to the last patch are only docstrings changes, one patch per
oe module to make reviewing easier.
This work will be integrated to the yocto-docs documentation in separate
series, sent after this one.
Note: compared to [1], I deliberately stopped following the
"Parameters:" and "Returns ..." pattern as it sometimes proved to be
challenging to describe the function's behavior in a natural way.
Instead, I took inspiration from how the Python library documents its
own modules, using imperative tense and simple paragraphs (most of the
time).
Note 2: for now, only certain modules are covered, especially those that I
think are useful for end-users. Some functions in those modules are not
documented and were left as-is because I also felt it wasn't useful to
document them.
[1]: https://docs.yoctoproject.org/bitbake/bitbake-user-manual/bitbake-user-manual-library-functions.html
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Antonin Godard (13):
lib/oe/path: rename "metadata" parameter to "d"
oe/path: simplify replace_absolute_symlinks() signature
lib/oe/utils: simplify str_filter*() signatures
lib/oe/utils: drop all_multilib_tune_list
lib/oe: move oe.types.{is_x86,qemu_use_kvm} to oe.qemu
lib/oe/data: improve docstring for typed_value
lib/oe/go: detail map_arch() parameter
lib/oe/kernel: convert comments to docstrings and improve
lib/oe/lsb: improve docstrings
lib/oe/path: improve docstrings
lib/oe/purl: improve docstrings
lib/oe/utils: improve docstrings
lib/oe/types: improve docstrings
meta/classes-recipe/testimage.bbclass | 2 +-
meta/classes/relative_symlinks.bbclass | 2 +-
meta/lib/oe/data.py | 28 ++-
meta/lib/oe/go.py | 7 +-
meta/lib/oe/kernel.py | 22 +-
meta/lib/oe/lsb.py | 18 +-
meta/lib/oe/path.py | 154 ++++++++++----
meta/lib/oe/purl.py | 9 +-
meta/lib/oe/qemu.py | 24 +++
meta/lib/oe/types.py | 166 +++++++++++----
meta/lib/oe/utils.py | 254 +++++++++++++++++------
meta/lib/oeqa/selftest/cases/efibootpartition.py | 2 +-
meta/lib/oeqa/selftest/cases/runqemu.py | 2 +-
meta/lib/oeqa/selftest/cases/uki.py | 2 +-
meta/lib/oeqa/targetcontrol.py | 2 +-
15 files changed, 529 insertions(+), 165 deletions(-)
---
base-commit: f32bced7b431f39a956c3e0d42e3c756ab784c49
change-id: 20261103-oe-lib-docstrings-355ea9d439b5
^ permalink raw reply [flat|nested] 16+ messages in thread
* [PATCH 01/13] lib/oe/path: rename "metadata" parameter to "d"
2026-11-16 16:08 [PATCH 00/13] Improve or add oe.* library docstrings Antonin Godard
@ 2026-11-16 16:08 ` Antonin Godard
2026-11-16 16:09 ` [PATCH 02/13] oe/path: simplify replace_absolute_symlinks() signature Antonin Godard
` (11 subsequent siblings)
12 siblings, 0 replies; 16+ messages in thread
From: Antonin Godard @ 2026-11-16 16:08 UTC (permalink / raw)
To: openembedded-core; +Cc: Antonin Godard, Thomas Petazzoni
Using metadata for this argument is confusing, as almost any other
function in the oe library uses "d" to denote the datastore. Rename it
to "d".
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
meta/lib/oe/path.py | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/meta/lib/oe/path.py b/meta/lib/oe/path.py
index 88d256f00b..8fe5bbc7fb 100644
--- a/meta/lib/oe/path.py
+++ b/meta/lib/oe/path.py
@@ -81,9 +81,9 @@ def replace_absolute_symlinks(basedir, d):
os.symlink(base, path)
@bb.parse.vardepsexclude("TOPDIR")
-def format_display(path, metadata):
+def format_display(path, d):
""" Prepare a path for display to the user. """
- rel = relative(metadata.getVar("TOPDIR"), path)
+ rel = relative(d.getVar("TOPDIR"), path)
if len(rel) > len(path):
return path
else:
--
2.56.0
^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 02/13] oe/path: simplify replace_absolute_symlinks() signature
2026-11-16 16:08 [PATCH 00/13] Improve or add oe.* library docstrings Antonin Godard
2026-11-16 16:08 ` [PATCH 01/13] lib/oe/path: rename "metadata" parameter to "d" Antonin Godard
@ 2026-11-16 16:09 ` Antonin Godard
2026-11-16 16:09 ` [PATCH 03/13] lib/oe/utils: simplify str_filter*() signatures Antonin Godard
` (10 subsequent siblings)
12 siblings, 0 replies; 16+ messages in thread
From: Antonin Godard @ 2026-11-16 16:09 UTC (permalink / raw)
To: openembedded-core; +Cc: Antonin Godard, Thomas Petazzoni
In replace_absolute_symlinks(), the datastore (d) argument is never
used. Remove it.
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
meta/classes/relative_symlinks.bbclass | 2 +-
meta/lib/oe/path.py | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/meta/classes/relative_symlinks.bbclass b/meta/classes/relative_symlinks.bbclass
index 9ee20e0d09..d2279028f2 100644
--- a/meta/classes/relative_symlinks.bbclass
+++ b/meta/classes/relative_symlinks.bbclass
@@ -7,5 +7,5 @@
do_install[postfuncs] += "install_relative_symlinks"
python install_relative_symlinks () {
- oe.path.replace_absolute_symlinks(d.getVar('D'), d)
+ oe.path.replace_absolute_symlinks(d.getVar('D'))
}
diff --git a/meta/lib/oe/path.py b/meta/lib/oe/path.py
index 8fe5bbc7fb..366ab9720a 100644
--- a/meta/lib/oe/path.py
+++ b/meta/lib/oe/path.py
@@ -59,7 +59,7 @@ def make_relative_symlink(path):
os.remove(path)
os.symlink(base, path)
-def replace_absolute_symlinks(basedir, d):
+def replace_absolute_symlinks(basedir):
"""
Walk basedir looking for absolute symlinks and replacing them with relative ones.
The absolute links are assumed to be relative to basedir
--
2.56.0
^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 03/13] lib/oe/utils: simplify str_filter*() signatures
2026-11-16 16:08 [PATCH 00/13] Improve or add oe.* library docstrings Antonin Godard
2026-11-16 16:08 ` [PATCH 01/13] lib/oe/path: rename "metadata" parameter to "d" Antonin Godard
2026-11-16 16:09 ` [PATCH 02/13] oe/path: simplify replace_absolute_symlinks() signature Antonin Godard
@ 2026-11-16 16:09 ` Antonin Godard
2026-11-16 16:09 ` [PATCH 04/13] lib/oe/utils: drop all_multilib_tune_list Antonin Godard
` (9 subsequent siblings)
12 siblings, 0 replies; 16+ messages in thread
From: Antonin Godard @ 2026-11-16 16:09 UTC (permalink / raw)
To: openembedded-core; +Cc: Antonin Godard, Thomas Petazzoni
In the str_filter*() functions, the datastore (d) argument is never
used. Remove it.
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
meta/lib/oe/utils.py | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/meta/lib/oe/utils.py b/meta/lib/oe/utils.py
index 66f6323add..5d4f4056f7 100644
--- a/meta/lib/oe/utils.py
+++ b/meta/lib/oe/utils.py
@@ -132,11 +132,11 @@ def prune_suffix(var, suffixes, d):
return var
-def str_filter(f, str, d):
+def str_filter(f, str):
from re import match
return " ".join([x for x in str.split() if match(f, x, 0)])
-def str_filter_out(f, str, d):
+def str_filter_out(f, str):
from re import match
return " ".join([x for x in str.split() if not match(f, x, 0)])
--
2.56.0
^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 04/13] lib/oe/utils: drop all_multilib_tune_list
2026-11-16 16:08 [PATCH 00/13] Improve or add oe.* library docstrings Antonin Godard
` (2 preceding siblings ...)
2026-11-16 16:09 ` [PATCH 03/13] lib/oe/utils: simplify str_filter*() signatures Antonin Godard
@ 2026-11-16 16:09 ` Antonin Godard
2026-11-16 16:09 ` [PATCH 05/13] lib/oe: move oe.types.{is_x86,qemu_use_kvm} to oe.qemu Antonin Godard
` (8 subsequent siblings)
12 siblings, 0 replies; 16+ messages in thread
From: Antonin Godard @ 2026-11-16 16:09 UTC (permalink / raw)
To: openembedded-core; +Cc: Antonin Godard, Thomas Petazzoni
The last user of all_multilib_tune_list was prelink, which was dropped in
2022 with 23c0be78106f ("prelink: Drop support for it"). There are no
other users of this function, and the current function is broken due to
its usage of oe.utils.get_multilib_datastore(...) which should be
replaced by get_multilib_datastore(...) directly. Drop it.
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
meta/lib/oe/utils.py | 19 -------------------
1 file changed, 19 deletions(-)
diff --git a/meta/lib/oe/utils.py b/meta/lib/oe/utils.py
index 5d4f4056f7..a17938803e 100644
--- a/meta/lib/oe/utils.py
+++ b/meta/lib/oe/utils.py
@@ -601,25 +601,6 @@ def all_multilib_tune_values(d, var, unique = True, need_split = True, delim = '
ret = values
return " ".join(ret)
-def all_multilib_tune_list(vars, d):
- """
- Return a list of ${VAR} for each variable VAR in vars from each
- multilib tune configuration.
- Is safe to be called from a multilib recipe/context as it can
- figure out the original tune and remove the multilib overrides.
- """
- values = {}
- for v in vars:
- values[v] = []
- values['ml'] = ['']
-
- variants = (d.getVar("MULTILIB_VARIANTS") or "").split() + ['']
- for item in variants:
- localdata = oe.utils.get_multilib_datastore(item, d)
- values[v].append(localdata.getVar(v))
- values['ml'].append(item)
- return values
-
def extend_variants(d, var, extend, delim=':'):
"""Return a string of all bb class extend variants for the given extend"""
variants = []
--
2.56.0
^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 05/13] lib/oe: move oe.types.{is_x86,qemu_use_kvm} to oe.qemu
2026-11-16 16:08 [PATCH 00/13] Improve or add oe.* library docstrings Antonin Godard
` (3 preceding siblings ...)
2026-11-16 16:09 ` [PATCH 04/13] lib/oe/utils: drop all_multilib_tune_list Antonin Godard
@ 2026-11-16 16:09 ` Antonin Godard
2026-11-17 10:09 ` [OE-core] " Mathieu Dubois-Briand
2026-11-16 16:09 ` [PATCH 06/13] lib/oe/data: improve docstring for typed_value Antonin Godard
` (7 subsequent siblings)
12 siblings, 1 reply; 16+ messages in thread
From: Antonin Godard @ 2026-11-16 16:09 UTC (permalink / raw)
To: openembedded-core; +Cc: Antonin Godard, Thomas Petazzoni
The oe.types library represents OpenEmbedded types such as booleans,
integers, etc. which is unrelated to what these two functions do:
is_x86() checks if a given arch matches the x86 architecture, and
qemu_use_kvm() is used to return True to enable KVM based on the current
target architecture.
Move these two functions to oe.qemu which is more appropriate. Adapt
usage in OE-Core as a consequence.
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
meta/classes-recipe/testimage.bbclass | 2 +-
meta/lib/oe/qemu.py | 24 ++++++++++++++++++++++++
meta/lib/oe/types.py | 23 -----------------------
meta/lib/oeqa/selftest/cases/efibootpartition.py | 2 +-
meta/lib/oeqa/selftest/cases/runqemu.py | 2 +-
meta/lib/oeqa/selftest/cases/uki.py | 2 +-
meta/lib/oeqa/targetcontrol.py | 2 +-
7 files changed, 29 insertions(+), 28 deletions(-)
diff --git a/meta/classes-recipe/testimage.bbclass b/meta/classes-recipe/testimage.bbclass
index 9909c928cd..0c1a55a4c9 100644
--- a/meta/classes-recipe/testimage.bbclass
+++ b/meta/classes-recipe/testimage.bbclass
@@ -288,7 +288,7 @@ def testimage_main(d):
boottime = int(d.getVar("TEST_QEMUBOOT_TIMEOUT"))
# Get use_kvm
- kvm = oe.types.qemu_use_kvm(d.getVar('QEMU_USE_KVM'), d.getVar('TARGET_ARCH'))
+ kvm = oe.qemu.qemu_use_kvm(d.getVar('QEMU_USE_KVM'), d.getVar('TARGET_ARCH'))
# Get OVMF
ovmf = d.getVar("QEMU_USE_OVMF")
diff --git a/meta/lib/oe/qemu.py b/meta/lib/oe/qemu.py
index 769865036c..abe2745b10 100644
--- a/meta/lib/oe/qemu.py
+++ b/meta/lib/oe/qemu.py
@@ -52,3 +52,27 @@ def qemu_run_binary(d, rootfs_path, binary):
base_libdir = rootfs_path + d.getVar("base_libdir", False)
return qemu_wrapper_cmdline(d, rootfs_path, [libdir, base_libdir]) + rootfs_path + binary
+
+def is_x86(arch):
+ """
+ Check whether ``arch`` is ``x86`` or ``x86_64``, return ``True`` if it is,
+ ``False`` otherwise.
+ """
+ if arch.startswith('x86_') or re.match('i.*86', arch):
+ return True
+ else:
+ return False
+
+def qemu_use_kvm(kvm, target_arch):
+ """
+ Enable kvm if target_arch == build_arch or both of them are x86 archs.
+ """
+
+ use_kvm = False
+ if kvm and boolean(kvm):
+ build_arch = os.uname()[4]
+ if is_x86(build_arch) and is_x86(target_arch):
+ use_kvm = True
+ elif build_arch == target_arch:
+ use_kvm = True
+ return use_kvm
diff --git a/meta/lib/oe/types.py b/meta/lib/oe/types.py
index b929afb1f3..c4b338921b 100644
--- a/meta/lib/oe/types.py
+++ b/meta/lib/oe/types.py
@@ -163,26 +163,3 @@ def path(value, relativeto='', normalize='true', mustexist='false'):
raise ValueError("{0}: {1}".format(value, os.strerror(errno.ENOENT)))
return value
-
-def is_x86(arch):
- """
- Check whether arch is x86 or x86_64
- """
- if arch.startswith('x86_') or re.match('i.*86', arch):
- return True
- else:
- return False
-
-def qemu_use_kvm(kvm, target_arch):
- """
- Enable kvm if target_arch == build_arch or both of them are x86 archs.
- """
-
- use_kvm = False
- if kvm and boolean(kvm):
- build_arch = os.uname()[4]
- if is_x86(build_arch) and is_x86(target_arch):
- use_kvm = True
- elif build_arch == target_arch:
- use_kvm = True
- return use_kvm
diff --git a/meta/lib/oeqa/selftest/cases/efibootpartition.py b/meta/lib/oeqa/selftest/cases/efibootpartition.py
index fcfcdaf7e4..0899d57c0b 100644
--- a/meta/lib/oeqa/selftest/cases/efibootpartition.py
+++ b/meta/lib/oeqa/selftest/cases/efibootpartition.py
@@ -17,7 +17,7 @@ class GenericEFITest(OESelftestTestCase):
image = "core-image-minimal"
runqemu_params = get_bb_var('TEST_RUNQEMUPARAMS', image) or ""
cmd = "runqemu %s nographic serial wic ovmf" % (runqemu_params)
- if oe.types.qemu_use_kvm(self.td.get('QEMU_USE_KVM', 0), self.td["TARGET_ARCH"]):
+ if oe.qemu.qemu_use_kvm(self.td.get('QEMU_USE_KVM', 0), self.td["TARGET_ARCH"]):
cmd += " kvm"
self.write_config("""
diff --git a/meta/lib/oeqa/selftest/cases/runqemu.py b/meta/lib/oeqa/selftest/cases/runqemu.py
index bfa76812ae..bdd5ae1bc3 100644
--- a/meta/lib/oeqa/selftest/cases/runqemu.py
+++ b/meta/lib/oeqa/selftest/cases/runqemu.py
@@ -34,7 +34,7 @@ class RunqemuTests(OESelftestTestCase):
self.fstypes += " wic.vmdk wic.qcow2 wic.vdi wic.zst"
self.cmd_common = "runqemu nographic snapshot"
- kvm = oe.types.qemu_use_kvm(get_bb_var('QEMU_USE_KVM'), self.td["TARGET_ARCH"])
+ kvm = oe.qemu.qemu_use_kvm(get_bb_var('QEMU_USE_KVM'), self.td["TARGET_ARCH"])
if kvm:
self.cmd_common += " kvm"
diff --git a/meta/lib/oeqa/selftest/cases/uki.py b/meta/lib/oeqa/selftest/cases/uki.py
index fc31fb767a..6283df540a 100644
--- a/meta/lib/oeqa/selftest/cases/uki.py
+++ b/meta/lib/oeqa/selftest/cases/uki.py
@@ -21,7 +21,7 @@ class UkiTest(OESelftestTestCase):
image = "core-image-minimal"
runqemu_params = get_bb_var('TEST_RUNQEMUPARAMS', image) or ""
cmd = "runqemu %s nographic serial wic ovmf" % (runqemu_params)
- if oe.types.qemu_use_kvm(self.td.get('QEMU_USE_KVM', 0), self.td["TARGET_ARCH"]):
+ if oe.qemu.qemu_use_kvm(self.td.get('QEMU_USE_KVM', 0), self.td["TARGET_ARCH"]):
cmd += " kvm"
self.write_config("""
diff --git a/meta/lib/oeqa/targetcontrol.py b/meta/lib/oeqa/targetcontrol.py
index 1deea2e5ce..23b26bc2b5 100644
--- a/meta/lib/oeqa/targetcontrol.py
+++ b/meta/lib/oeqa/targetcontrol.py
@@ -108,7 +108,7 @@ class QemuTarget(BaseTarget):
dump_dir = d.getVar("TESTIMAGE_DUMP_DIR")
if not dump_dir:
dump_dir = os.path.join(d.getVar('LOG_DIR'), 'runtime-hostdump')
- use_kvm = oe.types.qemu_use_kvm(d.getVar('QEMU_USE_KVM'), d.getVar('TARGET_ARCH'))
+ use_kvm = oe.qemu.qemu_use_kvm(d.getVar('QEMU_USE_KVM'), d.getVar('TARGET_ARCH'))
# Log QemuRunner log output to a file
import oe.path
--
2.56.0
^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 06/13] lib/oe/data: improve docstring for typed_value
2026-11-16 16:08 [PATCH 00/13] Improve or add oe.* library docstrings Antonin Godard
` (4 preceding siblings ...)
2026-11-16 16:09 ` [PATCH 05/13] lib/oe: move oe.types.{is_x86,qemu_use_kvm} to oe.qemu Antonin Godard
@ 2026-11-16 16:09 ` Antonin Godard
2026-11-16 16:09 ` [PATCH 07/13] lib/oe/go: detail map_arch() parameter Antonin Godard
` (6 subsequent siblings)
12 siblings, 0 replies; 16+ messages in thread
From: Antonin Godard @ 2026-11-16 16:09 UTC (permalink / raw)
To: openembedded-core; +Cc: Antonin Godard, Thomas Petazzoni
Improve the docstring of oe.data.typed_value() with an example and
details about its parameters.
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
meta/lib/oe/data.py | 28 ++++++++++++++++++++++++++--
1 file changed, 26 insertions(+), 2 deletions(-)
diff --git a/meta/lib/oe/data.py b/meta/lib/oe/data.py
index 37121cfad2..e9ca87dc16 100644
--- a/meta/lib/oe/data.py
+++ b/meta/lib/oe/data.py
@@ -8,8 +8,32 @@ import json
import oe.maketype
def typed_value(key, d):
- """Construct a value for the specified metadata variable, using its flags
- to determine the type and parameters for construction."""
+ """
+ Construct a value for the specified metadata variable, using its flags
+ to determine the type and parameters for construction.
+
+ For example, consider the following definition for ``FOO``::
+
+ FOO = "\\
+ /path/to/one \\
+ /path/to/two \\
+ /path/to/three \\
+ "
+ FOO[type] = "list"
+
+ Then this value can be iterated as follows:
+
+ .. code-block:: python
+
+ for line in oe.data.typed_value("FOO", d):
+ # ...
+
+ Take ``key`` as the variable name and return the object, for which the
+ type depends on the ``type`` variable flag of the variable.
+
+ See :py:mod:`oe.types` for more information on OpenEmbedded types.
+ """
+
var_type = d.getVarFlag(key, 'type')
flags = d.getVarFlags(key)
if flags is not None:
--
2.56.0
^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 07/13] lib/oe/go: detail map_arch() parameter
2026-11-16 16:08 [PATCH 00/13] Improve or add oe.* library docstrings Antonin Godard
` (5 preceding siblings ...)
2026-11-16 16:09 ` [PATCH 06/13] lib/oe/data: improve docstring for typed_value Antonin Godard
@ 2026-11-16 16:09 ` Antonin Godard
2026-11-16 16:09 ` [PATCH 08/13] lib/oe/kernel: convert comments to docstrings and improve Antonin Godard
` (5 subsequent siblings)
12 siblings, 0 replies; 16+ messages in thread
From: Antonin Godard @ 2026-11-16 16:09 UTC (permalink / raw)
To: openembedded-core; +Cc: Antonin Godard, Thomas Petazzoni
Detail the architecture parameter for map_arch(), which should match
TUNE_ARCH.
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
meta/lib/oe/go.py | 7 +++++--
1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/meta/lib/oe/go.py b/meta/lib/oe/go.py
index cbcf80f0b1..2a2cb7e75a 100644
--- a/meta/lib/oe/go.py
+++ b/meta/lib/oe/go.py
@@ -8,8 +8,11 @@ import re
def map_arch(a):
"""
- Map our architecture names to Go's GOARCH names.
- See https://github.com/golang/go/blob/master/src/internal/syslist/syslist.go for the complete list.
+ Take ``a``, the architecture name used in OpenEmbedded (see the
+ :term:`TUNE_ARCH` variable), and return a string for the mapped architecture
+ name from Go's ``GOARCH`` names (see
+ https://github.com/golang/go/blob/master/src/internal/syslist/syslist.go
+ for the complete list).
"""
if re.match('i.86', a):
return '386'
--
2.56.0
^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 08/13] lib/oe/kernel: convert comments to docstrings and improve
2026-11-16 16:08 [PATCH 00/13] Improve or add oe.* library docstrings Antonin Godard
` (6 preceding siblings ...)
2026-11-16 16:09 ` [PATCH 07/13] lib/oe/go: detail map_arch() parameter Antonin Godard
@ 2026-11-16 16:09 ` Antonin Godard
2026-11-16 16:09 ` [PATCH 09/13] lib/oe/lsb: improve docstrings Antonin Godard
` (4 subsequent siblings)
12 siblings, 0 replies; 16+ messages in thread
From: Antonin Godard @ 2026-11-16 16:09 UTC (permalink / raw)
To: openembedded-core; +Cc: Antonin Godard, Thomas Petazzoni
Most functions in this module were comments. Move them to docstrings so
we can use this data in documentation modules such as Sphinx. Improve
the docstrings by detailing the parameters and return value.
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
meta/lib/oe/kernel.py | 22 ++++++++++++++++------
1 file changed, 16 insertions(+), 6 deletions(-)
diff --git a/meta/lib/oe/kernel.py b/meta/lib/oe/kernel.py
index 624eace10e..5c94a5df90 100644
--- a/meta/lib/oe/kernel.py
+++ b/meta/lib/oe/kernel.py
@@ -7,10 +7,13 @@
import os
import re
-# Return a value for the ARCH environment variable for kernel compilation (including
-# modules). return value must match one of the architecture directories
-# in the kernel source "arch" directory
def map_kernel_arch(d):
+ """
+ Take ``d`` (the :term:`datastore`) to get the value of :term:`TARGET_ARCH`
+ and return a value for the ``ARCH`` environment variable for kernel
+ compilation (including modules). Return value must match one of the architecture
+ directories in the kernel source "arch" directory.
+ """
a = d.getVar('TARGET_ARCH')
valid_archs = ["alpha", "cris", "ia64", "i386", "x86", "m68knommu", "m68k", "ppc", "powerpc",
@@ -39,13 +42,20 @@ def map_kernel_arch(d):
return a
bb.error("cannot map '%s' to a linux kernel architecture" % a)
-# Return a value for the -A parameter to u-boot's mkimage
-# This would be the value from the table in boot/image.c:uimage_arch
def map_uboot_arch(d):
+ """
+ Take ``d`` (the :term:`datastore`) to get the value of :term:`TARGET_ARCH`
+ and return a value for the ``-A`` parameter to U-Boot's ``mkimage``.
+ This would be the value from the table in ``boot/image.c:uimage_arch``.
+ """
return map_kernel_arch(d)
-# parse kernel ABI version out of <linux/version.h>
def get_version_headers(p):
+ """
+ Take ``p``, the root of the kernel build directory and parse the kernel
+ ABI version out of ``<linux/version.h>``, and return a string containing
+ the ABI version, if found. If not found, return ``None``.
+ """
fn = p + '/include/linux/utsrelease.h'
if not os.path.isfile(fn):
# after 2.6.33-rc1
--
2.56.0
^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 09/13] lib/oe/lsb: improve docstrings
2026-11-16 16:08 [PATCH 00/13] Improve or add oe.* library docstrings Antonin Godard
` (7 preceding siblings ...)
2026-11-16 16:09 ` [PATCH 08/13] lib/oe/kernel: convert comments to docstrings and improve Antonin Godard
@ 2026-11-16 16:09 ` Antonin Godard
2026-11-16 16:09 ` [PATCH 10/13] lib/oe/path: " Antonin Godard
` (3 subsequent siblings)
12 siblings, 0 replies; 16+ messages in thread
From: Antonin Godard @ 2026-11-16 16:09 UTC (permalink / raw)
To: openembedded-core; +Cc: Antonin Godard, Thomas Petazzoni
Improve docstrings by detailing the parameters and return values of
functions in this module.
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
meta/lib/oe/lsb.py | 18 +++++++++++++++---
1 file changed, 15 insertions(+), 3 deletions(-)
diff --git a/meta/lib/oe/lsb.py b/meta/lib/oe/lsb.py
index 1283cefaaf..8f43301484 100644
--- a/meta/lib/oe/lsb.py
+++ b/meta/lib/oe/lsb.py
@@ -7,7 +7,13 @@
import os
def get_os_release():
- """Get all key-value pairs from /etc/os-release as a dict"""
+ """
+ Get all key-value pairs from the :term:`Build Host`'s ``/etc/os-release``
+ as a dictionary.
+
+ Return a Python dictionary mapping keys from ``/etc/os-release`` to their
+ values.
+ """
data = {}
if os.path.exists('/etc/os-release'):
@@ -21,8 +27,14 @@ def get_os_release():
return data
def distro_identifier(d=None):
- """Return a distro identifier string based upon /etc/os-release
- with optional adjustment via a hook"""
+ """
+ Return a distro identifier string based upon the :term:`Build Host`'s /etc/os-release
+ with optional adjustment via a hook defined by ``LSB_DISTRO_ADJUST``.
+ See the value of :term:`SANITY_TESTED_DISTROS` for a list of valid distro identifiers.
+
+ Can optionally take ``d`` (the :term:`datastore`) to read the value of
+ ``LSB_DISTRO_ADJUST``.
+ """
import re
--
2.56.0
^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 10/13] lib/oe/path: improve docstrings
2026-11-16 16:08 [PATCH 00/13] Improve or add oe.* library docstrings Antonin Godard
` (8 preceding siblings ...)
2026-11-16 16:09 ` [PATCH 09/13] lib/oe/lsb: improve docstrings Antonin Godard
@ 2026-11-16 16:09 ` Antonin Godard
2026-11-16 16:09 ` [PATCH 11/13] lib/oe/purl: " Antonin Godard
` (2 subsequent siblings)
12 siblings, 0 replies; 16+ messages in thread
From: Antonin Godard @ 2026-11-16 16:09 UTC (permalink / raw)
To: openembedded-core; +Cc: Antonin Godard, Thomas Petazzoni
Improve docstrings by detailing the parameters and return values of
functions in this module. Give examples when possible to make the
understanding easier.
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
meta/lib/oe/path.py | 148 +++++++++++++++++++++++++++++++++++++++-------------
1 file changed, 112 insertions(+), 36 deletions(-)
diff --git a/meta/lib/oe/path.py b/meta/lib/oe/path.py
index 366ab9720a..5122fcb08e 100644
--- a/meta/lib/oe/path.py
+++ b/meta/lib/oe/path.py
@@ -14,26 +14,54 @@ import os.path
import bb.parse
def join(*paths):
- """Like os.path.join but doesn't treat absolute RHS specially"""
+ """
+ Like :py:func:`os.path.join` but do not treat absolute RHS specially.
+ Use :py:func:`os.path.normpath` after joining paths with slashes (``/``).
+
+ Take ``*paths`` which represent the paths to join and return the joined
+ paths as a string.
+ """
return os.path.normpath("/".join(paths))
def relative(src, dest):
- """ Return a relative path from src to dest.
+ """
+ Return a relative path from ``src`` to ``dest``.
+
+ Examples:
+
+ .. code-block:: python
- >>> relative("/usr/bin", "/tmp/foo/bar")
- ../../tmp/foo/bar
+ >>> oe.path.relative("/usr/bin", "/tmp/foo/bar")
+ ../../tmp/foo/bar
- >>> relative("/usr/bin", "/usr/lib")
- ../lib
+ .. code-block:: python
- >>> relative("/tmp", "/tmp/foo/bar")
- foo/bar
+ >>> oe.path.relative("/usr/bin", "/usr/lib")
+ ../lib
+
+ .. code-block:: python
+
+ >>> oe.path.relative("/tmp", "/tmp/foo/bar")
+ foo/bar
"""
return os.path.relpath(dest, src)
def make_relative_symlink(path):
- """ Convert an absolute symlink to a relative one """
+ """
+ Convert an absolute symbolic link ``path`` and convert it to a relative one.
+
+ No return value.
+
+ For example, if ``/path/to/dir/link`` points to ``/path/to/other/target``,
+ then:
+
+ .. code-block:: python
+
+ >>> oe.path.make_relative_symlink("/path/to/dir/link")
+
+ Converts the symlink to ``../other/file``.
+ """
if not os.path.islink(path):
return
link = os.readlink(path)
@@ -61,10 +89,12 @@ def make_relative_symlink(path):
def replace_absolute_symlinks(basedir):
"""
- Walk basedir looking for absolute symlinks and replacing them with relative ones.
- The absolute links are assumed to be relative to basedir
- (compared to make_relative_symlink above which tries to compute common ancestors
- using pattern matching instead)
+ Walk ``basedir`` looking for absolute symlinks and replacing them with relative ones.
+ The absolute links are assumed to be relative to ``basedir``.
+ (compared to :py:func:`oe.path.make_relative_symlink` which tries to compute
+ common ancestors using pattern matching instead).
+
+ No return value.
"""
for walkroot, dirs, files in os.walk(basedir):
for file in files + dirs:
@@ -82,7 +112,13 @@ def replace_absolute_symlinks(basedir):
@bb.parse.vardepsexclude("TOPDIR")
def format_display(path, d):
- """ Prepare a path for display to the user. """
+ """
+ Prepare ``path`` for display to the user: the path is converted to be
+ relative to :term:`TOPDIR`, which is obtained thanks to ``d`` (the
+ :term:`datastore`).
+
+ Return the formatted path as a string.
+ """
rel = relative(d.getVar("TOPDIR"), path)
if len(rel) > len(path):
return path
@@ -100,7 +136,13 @@ def copytree(src, dst):
subprocess.check_output(cmd, shell=True, stderr=subprocess.STDOUT)
def copyhardlinktree(src, dst):
- """Make a tree of hard links when possible, otherwise copy."""
+ """
+ Replicate the ``src`` directory into ``dst`` and replace files with
+ hardlinks when possible, otherwise copy them (some filesystems do not
+ support hardlinks).
+
+ No return value.
+ """
bb.utils.mkdirhier(dst)
if os.path.isdir(src) and not len(os.listdir(src)):
return
@@ -141,7 +183,12 @@ def copyhardlinktree(src, dst):
copytree(src, dst)
def copyhardlink(src, dst):
- """Make a hard link when possible, otherwise copy."""
+ """
+ Make a hard link of ``src`` into ``dst`` when possible, otherwise copy
+ (some filesystems do not support hardlinks).
+
+ No return value.
+ """
try:
os.link(src, dst)
@@ -150,12 +197,15 @@ def copyhardlink(src, dst):
def remove(path, recurse=True):
"""
- Equivalent to rm -f or rm -rf
+ Equivalent to ``rm -f`` or ``rm -rf`` (when ``recurse`` is ``True``).
+
NOTE: be careful about passing paths that may contain filenames with
wildcards in them (as opposed to passing an actual wildcarded path) -
- since we use glob.glob() to expand the path. Filenames containing
+ since we use :py:func:`glob.glob` to expand the path. Filenames containing
square brackets are particularly problematic since the they may not
actually expand to match the original filename.
+
+ No return value.
"""
for name in glob.glob(path):
try:
@@ -167,7 +217,12 @@ def remove(path, recurse=True):
raise
def symlink(source, destination, force=False):
- """Create a symbolic link"""
+ """
+ Create a symbolic link ``destination`` pointing to ``source``.
+ Optionally force it with ``force=True``.
+
+ No return value.
+ """
try:
if force:
# Remove the exact destination path. Do not route this through
@@ -191,8 +246,12 @@ def relsymlink(target, name, force=False):
symlink(os.path.relpath(target, os.path.dirname(name)), name, force=force)
def find(dir, **walkoptions):
- """ Given a directory, recurses into that directory,
- returning all files as absolute paths. """
+ """
+ Given a directory ``dir``, recurse into that directory,
+ ``yield``'ing all files as absolute paths.
+
+ No return value.
+ """
for root, dirs, files in os.walk(dir, **walkoptions):
for file in files:
@@ -251,12 +310,15 @@ def __realpath(file, root, loop_cnt, assume_dir):
return (file, is_dir)
def realpath(file, root, use_physdir = True, loop_cnt = 100, assume_dir = False):
- """ Returns the canonical path of 'file' with assuming a
- toplevel 'root' directory. When 'use_physdir' is set, all
- preceding path components of 'file' will be resolved first;
+ """
+ Return the canonical path of ``file`` with assuming a
+ toplevel ``root`` directory. When ``use_physdir`` is set, all
+ preceding path components of ``file`` will be resolved first;
this flag should be set unless it is guaranteed that there is
- no symlink in the path. When 'assume_dir' is not set, missing
- path components will raise an ENOENT error"""
+ no symlink in the path. When ``assume_dir`` is not set, missing
+ path components will raise an ``ENOENT`` error. Limit the recursion to
+ ``loop_cnt`` when recursively resolving paths.
+ """
root = os.path.normpath(root)
file = os.path.normpath(file)
@@ -288,10 +350,11 @@ def realpath(file, root, use_physdir = True, loop_cnt = 100, assume_dir = False)
def is_path_parent(possible_parent, *paths):
"""
- Return True if a path is the parent of another, False otherwise.
+ Return ``True`` if one or more paths (passed with ``*paths``) have
+ ``possible_parent`` as their parent, ``False`` otherwise.
Multiple paths to test can be specified in which case all
specified test paths must be under the parent in order to
- return True.
+ return ``True``.
"""
def abs_path_trailing(pth):
pth_abs = os.path.abspath(pth)
@@ -309,12 +372,23 @@ def is_path_parent(possible_parent, *paths):
return True
def which_wild(pathname, path=None, mode=os.F_OK, *, reverse=False, candidates=False):
- """Search a search path for pathname, supporting wildcards.
+ """
+ Search a search ``path`` for ``pathname``, supporting wildcards.
- Return all paths in the specific search path matching the wildcard pattern
- in pathname, returning only the first encountered for each file. If
- candidates is True, information on all potential candidate paths are
- included.
+ ``path`` should be a colon-separated list of paths. If not passed, the
+ ``PATH`` environment is used.
+
+ Return all paths as a list in the specific search path matching the wildcard pattern
+ in ``pathname``, returning only the first encountered for each file.
+
+ If ``candidates`` is True, information on all potential candidate paths are
+ included as two-element tuples: first element is the matched candidates,
+ second element is the list of other matches.
+
+ ``mode`` is passed to :py:func:`os.access` to control what the matched
+ files should have as attributes (executable, readable, etc.).
+
+ When ``reverse`` is ``True``, reverse the search path before iterating.
"""
paths = (path or os.environ.get('PATH', os.defpath)).split(':')
if reverse:
@@ -342,9 +416,11 @@ def which_wild(pathname, path=None, mode=os.F_OK, *, reverse=False, candidates=F
return files
def canonicalize(paths, sep=','):
- """Given a string with paths (separated by commas by default), expand
- each path using os.path.realpath() and return the resulting paths as a
- string (separated using the same separator a the original string).
+ """
+ Given a string with paths ``paths`` (separated by commas by default, but
+ controllable by ``sep``), expand each path using :py:func:`os.path.realpath`
+ and return the resulting paths as a string (separated using the same
+ separated as the original string).
"""
# Ignore paths containing "$" as they are assumed to be unexpanded bitbake
# variables. Normally they would be ignored, e.g., when passing the paths
--
2.56.0
^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 11/13] lib/oe/purl: improve docstrings
2026-11-16 16:08 [PATCH 00/13] Improve or add oe.* library docstrings Antonin Godard
` (9 preceding siblings ...)
2026-11-16 16:09 ` [PATCH 10/13] lib/oe/path: " Antonin Godard
@ 2026-11-16 16:09 ` Antonin Godard
2026-11-16 16:09 ` [PATCH 12/13] lib/oe/utils: " Antonin Godard
2026-11-16 16:09 ` [PATCH 13/13] lib/oe/types: " Antonin Godard
12 siblings, 0 replies; 16+ messages in thread
From: Antonin Godard @ 2026-11-16 16:09 UTC (permalink / raw)
To: openembedded-core; +Cc: Antonin Godard, Thomas Petazzoni
Improve docstrings by detailing the parameters and return values of
functions in this module.
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
meta/lib/oe/purl.py | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
diff --git a/meta/lib/oe/purl.py b/meta/lib/oe/purl.py
index 2f92a23596..ed158d7f81 100644
--- a/meta/lib/oe/purl.py
+++ b/meta/lib/oe/purl.py
@@ -11,16 +11,17 @@ PREFIX = "pkg:yocto"
def quote(s):
"""
- Returns the percent encoded version of the string, suitable for including
- in a PURL field
+ Return the percent encoded version of the string ``s``, suitable for inclusion
+ in a PURL field.
"""
return urllib.parse.quote(s, safe="")
def get_base_purl(d):
"""
- Returns the base PURL for the current recipe (that is, the PURL without any
- additional qualifiers)
+ Return the base PURL for the current recipe (that is, the PURL without any
+ additional qualifiers), using ``d`` (the :term:`datastore`) to access the recipe's
+ variables.
"""
layername = d.getVar("FILE_LAYERNAME")
bpn = d.getVar("BPN")
--
2.56.0
^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 12/13] lib/oe/utils: improve docstrings
2026-11-16 16:08 [PATCH 00/13] Improve or add oe.* library docstrings Antonin Godard
` (10 preceding siblings ...)
2026-11-16 16:09 ` [PATCH 11/13] lib/oe/purl: " Antonin Godard
@ 2026-11-16 16:09 ` Antonin Godard
2026-11-16 16:09 ` [PATCH 13/13] lib/oe/types: " Antonin Godard
12 siblings, 0 replies; 16+ messages in thread
From: Antonin Godard @ 2026-11-16 16:09 UTC (permalink / raw)
To: openembedded-core; +Cc: Antonin Godard, Thomas Petazzoni
Improve docstrings by detailing the parameters and return values of
functions in this module, or adding the docstring entirely when it
wasn't present and it made sense to document this function.
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
meta/lib/oe/utils.py | 235 +++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 190 insertions(+), 45 deletions(-)
diff --git a/meta/lib/oe/utils.py b/meta/lib/oe/utils.py
index a17938803e..caa4dd4301 100644
--- a/meta/lib/oe/utils.py
+++ b/meta/lib/oe/utils.py
@@ -13,6 +13,11 @@ import bb.parse
from bb import multiprocessing
def read_file(filename):
+ """
+ Read a file under the path ``filename`` and return the content of the
+ file. In case of :py:class:`IOError`, return an empty string. In case
+ of other exceptions, return ``None``.
+ """
try:
f = open( filename, "r" )
except IOError as reason:
@@ -24,18 +29,32 @@ def read_file(filename):
return None
def ifelse(condition, iftrue = True, iffalse = False):
+ """
+ If ``condition`` is ``True``, return the value of ``iftrue``, else
+ return the value of ``iffalse``.
+ """
if condition:
return iftrue
else:
return iffalse
def conditional(variable, checkvalue, truevalue, falsevalue, d):
+ """
+ If the value of ``variable`` (obtained using ``d``, the :term:`datastore`)
+ equals the value of ``checkvalue``, return the value of ``truevalue``, else
+ return the value of ``falsevalue``.
+ """
if d.getVar(variable) == checkvalue:
return truevalue
else:
return falsevalue
def vartrue(var, iftrue, iffalse, d):
+ """
+ Check if the value of ``var`` (obtained using ``d``, the :term:`datastore`)
+ passed to :py:func:`oe.types.boolean` returns ``True`` and return the value
+ of ``iftrue`` if it does, otherwise return the value of ``iffalse``.
+ """
import oe.types
if oe.types.boolean(d.getVar(var)):
return iftrue
@@ -43,12 +62,25 @@ def vartrue(var, iftrue, iffalse, d):
return iffalse
def less_or_equal(variable, checkvalue, truevalue, falsevalue, d):
+ """
+ Check if the value of ``variable`` (obtained using ``d``, the
+ :term:`datastore`) is inferior or equal to ``checkvalue``, and return the
+ value of ``truevalue`` if it is, otherwise return the value of
+ ``falsevalue``. Both ``checkvalue`` and the value of ``variable`` are
+ converted to :py:type:`float` numbers before comparison.
+ """
if float(d.getVar(variable)) <= float(checkvalue):
return truevalue
else:
return falsevalue
def version_less_or_equal(variable, checkvalue, truevalue, falsevalue, d):
+ """
+ Check if the value of ``variable`` (obtained using ``d``, the
+ :term:`datastore`) is inferior or equal to ``checkvalue`` using
+ :py:func:`oe.utils.vercmp_string`, and return the value of
+ ``truevalue`` if it is, otherwise return the value of ``falsevalue``.
+ """
result = bb.utils.vercmp_string(d.getVar(variable), checkvalue)
if result <= 0:
return truevalue
@@ -56,6 +88,13 @@ def version_less_or_equal(variable, checkvalue, truevalue, falsevalue, d):
return falsevalue
def both_contain(variable1, variable2, checkvalue, d):
+ """
+ Check whether the value of the variables ``variable1`` and ``variable2``
+ (obtained using ``d``, the :term:`datastore`) both contain all the values in
+ ``checkvalue``. ``variable1``, ``variable2`` and ``checkvalue`` are
+ treated as space-separated lists (``checkvalue`` can be a space-separated
+ string, or directly a Python list).
+ """
val1 = d.getVar(variable1)
val2 = d.getVar(variable2)
val1 = set(val1.split())
@@ -71,14 +110,21 @@ def both_contain(variable1, variable2, checkvalue, d):
def set_intersect(variable1, variable2, d):
"""
- Expand both variables, interpret them as lists of strings, and return the
- intersection as a flattened string.
+ Take the values of ``variable1`` and ``variable2`` (obtained using ``d``,
+ the :term:`datastore`), convert them from space-separated lists to Python
+ sets, and return the intersection as a space-separated list.
+
+ For example::
+
+ FOO = "a b c"
+ BAR = "b c d"
+
+ Then:
- For example:
- s1 = "a b c"
- s2 = "b c d"
- s3 = set_intersect(s1, s2)
- => s3 = "b c"
+ .. code-block:: python
+
+ >>> oe.utils.set_intersect("FOO", "BAR", d)
+ "b c"
"""
val1 = set(d.getVar(variable1).split())
val2 = set(d.getVar(variable2).split())
@@ -86,21 +132,37 @@ def set_intersect(variable1, variable2, d):
def set_difference(variable1, variable2, d):
"""
- Expand both variables, interpret them as lists of strings, and return the
- difference as a flattened string.
+ Take the values of ``variable1`` and ``variable2`` (obtained using ``d``,
+ the :term:`datastore`), convert them from space-separated lists to Python
+ sets, and return a space-separated list of the elements in ``variable1``
+ that are not in ``variable2``.
+
+ For example::
+
+ FOO = "a b c"
+ BAR = "b c d"
+
+ Then:
+
+ .. code-block:: python
+
+ >>> oe.utils.set_difference("FOO", "BAR", d)
+ "a"
+
+ If "*" is present in the value of ``variable2`` (not part of a larger
+ identifier), this is interpreted as "remove all entries":
+
+ For example::
+
+ FOO = "a b c"
+ BAR = "*"
- For example:
- s1 = "a b c"
- s2 = "b c d"
- s3 = set_difference(s1, s2)
- => s3 = "a"
+ Then:
- If '*' is present as a separate token (not part of a larger identifier) in
- the second operand, this is interpreted as "remove all entries":
- s1 = "a b c"
- s2 = "*"
- s3 = set_difference(s1, s2)
- => s3 = ""
+ .. code-block:: python
+
+ >>> oe.utils.set_difference("FOO", "BAR", d)
+ ""
"""
val1 = d.getVar(variable1)
if not val1:
@@ -120,8 +182,12 @@ def set_difference(variable1, variable2, d):
return " ".join(sorted(val1 - val2))
def prune_suffix(var, suffixes, d):
- # See if var ends with any of the suffixes listed and
- # remove it if found
+ """
+ See if the variable ``var`` ends with any of the suffixes listed and
+ remove it if found.
+
+ Also remove the :term:`MLPREFIX` prefix if present in ``var``.
+ """
for suffix in suffixes:
if suffix and var.endswith(suffix):
var = var[:-len(suffix)]
@@ -133,19 +199,41 @@ def prune_suffix(var, suffixes, d):
return var
def str_filter(f, str):
+ """
+ Take ``str``, as a space-separated list of values, and return a
+ space-separated list of all the values matching the regular expression ``f``
+ using :py:func:`re.match`.
+ """
from re import match
return " ".join([x for x in str.split() if match(f, x, 0)])
def str_filter_out(f, str):
+ """
+ Take ``str``, as a space-separated list of values, and return a
+ space-separated list of all the values *not* matching the regular expression ``f``
+ using :py:func:`re.match`.
+ """
from re import match
return " ".join([x for x in str.split() if not match(f, x, 0)])
def build_depends_string(depends, task):
- """Append a taskname to a string of dependencies as used by the [depends] flag"""
+ """
+ Append a taskname ``task`` to a space-separated list of dependencies stored in
+ ``depends`` as used by the ``[depends]`` variable flag:
+
+ .. code-block:: python
+
+ >>> oe.utils.build_depends_string("dep1 dep2 dep3", "task")
+ "dep1:task dep2:task dep3:task"
+ """
return " ".join(dep + ":" + task for dep in depends.split())
def inherits(d, *classes):
- """Return True if the metadata inherits any of the specified classes"""
+ """
+ Return ``True`` if the metadata (obtained from ``d``, the
+ :term:`datastore`) inherits *any* of the specified classes in
+ ``*classes`` (internally uses :py:func:`bb.data.inherits_class`).
+ """
return any(bb.data.inherits_class(cls, d) for cls in classes)
def filter_default_features(varname, d):
@@ -174,10 +262,12 @@ def set_class_filter(var, features_var, filter_var, d):
def parallel_make_value(pm):
"""
Return the integer value for the number of parallel threads to use when
- building, scraped out of given string. If no parallelization option is
- found, returns empty string
+ building, scraped out of given string ``pm``. If no parallelization option is
+ found, return an empty string.
+
+ For example if ``pm`` is "-j 10", this will return 10 as an integer.
- e.g. if string is "-j 10", this will return 10 as an integer.
+ This function is used by :py:func:`oe.utils.parallel_make`.
"""
# look for '-j' and throw other options (e.g. '-l') away
while pm:
@@ -196,10 +286,13 @@ def parallel_make_value(pm):
def parallel_make(d, makeinst=False):
"""
Return the integer value for the number of parallel threads to use when
- building, scraped out of PARALLEL_MAKE. If no parallelization option is
- found, returns empty string
+ building, scraped out of :term:`PARALLEL_MAKE`. If no parallelization option is
+ found, return an empty string.
- e.g. if PARALLEL_MAKE = "-j 10", this will return 10 as an integer.
+ For example if ``PARALLEL_MAKE = "-j 10"``, this will return 10 as an integer.
+
+ The ``makeinst`` boolean can be set to ``True`` if the value should be
+ obtained from :term:`PARALLEL_MAKEINST` instead.
"""
if makeinst:
pm = (d.getVar('PARALLEL_MAKEINST') or '').split()
@@ -210,15 +303,19 @@ def parallel_make(d, makeinst=False):
def parallel_make_argument(d, fmt, limit=None, makeinst=False):
"""
Helper utility to construct a parallel make argument from the number of
- parallel threads specified in PARALLEL_MAKE.
+ parallel threads specified in :term:`PARALLEL_MAKE`.
- Returns the input format string `fmt` where a single '%d' will be expanded
- with the number of parallel threads to use. If `limit` is specified, the
+ Return the input format string ``fmt`` where a single ``%d`` will be expanded
+ with the number of parallel threads to use. If ``limit`` is specified, the
number of parallel threads will be no larger than it. If no parallelization
- option is found in PARALLEL_MAKE, returns an empty string
+ option is found in :term:`PARALLEL_MAKE`, return an empty string.
+
+ For example if ``PARALLEL_MAKE = "-j 10"`` then:
- e.g. if PARALLEL_MAKE = "-j 10", parallel_make_argument(d, "-n %d") will return
- "-n 10"
+ .. code-block:: python
+
+ >>> parallel_make_argument(d, "-n %d")
+ "-n 10"
"""
v = parallel_make(d, makeinst)
if v:
@@ -229,8 +326,9 @@ def parallel_make_argument(d, fmt, limit=None, makeinst=False):
def packages_filter_out_system(d):
"""
- Return a list of packages from PACKAGES with the "system" packages such as
- PN-dbg PN-doc PN-locale-eb-gb removed.
+ Return a list of packages from :term:`PACKAGES` (obtained using ``d``, the
+ :term:`datastore`) with the "system" packages such as ``${PN}-dbg``, ``${PN}-doc``,
+ or ``${PN}-locale-en-gb`` removed.
"""
pn = d.getVar('PN')
pkgfilter = [pn + suffix for suffix in ('', '-dbg', '-dev', '-doc', '-locale', '-staticdev', '-src', '-lic')]
@@ -248,8 +346,13 @@ def getstatusoutput(cmd):
def trim_version(version, num_parts=2):
"""
- Return just the first <num_parts> of <version>, split by periods. For
- example, trim_version("1.2.3", 2) will return "1.2".
+ Return just the first ``num_parts`` parts of ``version``, split by periods
+ (``.``). For example:
+
+ .. code-block:: python
+
+ >>> oe.utils.trim_version("1.2.3", 2)
+ "1.2"
"""
if type(version) is not str:
raise TypeError("Version should be a string")
@@ -276,6 +379,11 @@ def execute_pre_post_process(d, cmds):
@bb.parse.vardepsexclude("BB_NUMBER_THREADS")
def get_bb_number_threads(d):
+ """
+ Return the value of :term:`BB_NUMBER_THREADS` (using ``d``, the
+ :term:`datastore`). If undefined, return the value of
+ :py:func:`os.cpu_count` or 1 if the former returns ``None``.
+ """
return int(d.getVar("BB_NUMBER_THREADS") or os.cpu_count() or 1)
def multiprocess_launch(target, items, d, extraargs=None):
@@ -362,6 +470,10 @@ def multiprocess_launch_mp(target, items, max_process, extraargs=None):
return results
def squashspaces(string):
+ """
+ Return the input ``string`` with every occurrence of two or more whitespace
+ replaced by only one whitespace.
+ """
import re
return re.sub(r"\s+", " ", string).strip()
@@ -466,13 +578,16 @@ def get_multilib_datastore(variant, d):
return localdata
def sh_quote(string):
+ """
+ Return a shell-escaped version of ``string`` using :py:func:`shlex.quote`.
+ """
import shlex
return shlex.quote(string)
def directory_size(root, blocksize=4096):
"""
- Calculate the size of the directory, taking into account hard links,
- rounding up every size to multiples of the blocksize.
+ Calculate and return the size of the directory ``root``, taking into account
+ hard links, rounding up every size to multiples of ``blocksize``.
"""
def roundup(size):
"""
@@ -500,8 +615,14 @@ def directory_size(root, blocksize=4096):
total += roundup(getsize(root))
return total
-# Update the mtime of a file, skip if permission/read-only issues
+
def touch(filename):
+ """
+ Update the ``mtime`` of a file under the path ``filename``,
+ skip if permission/read-only issues.
+
+ No return value.
+ """
try:
os.utime(filename, None)
except PermissionError:
@@ -572,12 +693,21 @@ def base_set_filespath(path, d):
return ":".join(filespath)
def check_app_exists(app, d):
+ """
+ Using :py:func:`bb.utils.which`, check if the program used by the command
+ stored in ``app`` exists.
+ """
app = d.expand(app).split()[0].strip()
path = d.getVar('PATH')
return bool(bb.utils.which(path, app))
def all_multilib_tune_values(d, var, unique = True, need_split = True, delim = ' '):
- """Return a string of all ${var} in all multilib tune configuration"""
+ """
+ Return a space-separated list of ``var`` in all multilib tune configurations.
+ ``unique`` removes repetitions in the string. ``need_split`` should be set
+ if the input ``var`` is a ``delim``-separated list that should be split
+ (otherwise an iterable object can be passed with ``need_split=False``).
+ """
values = []
variants = (d.getVar("MULTILIB_VARIANTS") or "").split() + ['']
for item in variants:
@@ -602,7 +732,22 @@ def all_multilib_tune_values(d, var, unique = True, need_split = True, delim = '
return " ".join(ret)
def extend_variants(d, var, extend, delim=':'):
- """Return a string of all bb class extend variants for the given extend"""
+ """
+ Return a space-separated string of all BitBake class extend variants
+ for the given ``extend``, extracted from the ``delim``-separated entries of
+ the value of ``var`` (obtained using ``d``, the :term:`datastore`).
+
+ For example, consider the following assignment::
+
+ MULTILIBS = "multilib:lib32 multilib:lib64"
+
+ Then:
+
+ .. code-block:: python
+
+ >>> oe.utils.extend_variants(d, "MULTILIBS", "multilib")
+ "lib32 lib64"
+ """
variants = []
whole = d.getVar(var) or ""
for ext in whole.split():
--
2.56.0
^ permalink raw reply related [flat|nested] 16+ messages in thread
* [PATCH 13/13] lib/oe/types: improve docstrings
2026-11-16 16:08 [PATCH 00/13] Improve or add oe.* library docstrings Antonin Godard
` (11 preceding siblings ...)
2026-11-16 16:09 ` [PATCH 12/13] lib/oe/utils: " Antonin Godard
@ 2026-11-16 16:09 ` Antonin Godard
12 siblings, 0 replies; 16+ messages in thread
From: Antonin Godard @ 2026-11-16 16:09 UTC (permalink / raw)
To: openembedded-core; +Cc: Antonin Godard, Thomas Petazzoni
Improve docstrings by detailing the parameters and return values of
OpenEmbedded types. Give usage examples for each of the type.
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
meta/lib/oe/types.py | 143 +++++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 127 insertions(+), 16 deletions(-)
diff --git a/meta/lib/oe/types.py b/meta/lib/oe/types.py
index c4b338921b..7fe9e9d8a4 100644
--- a/meta/lib/oe/types.py
+++ b/meta/lib/oe/types.py
@@ -75,14 +75,34 @@ class NoMatch(object):
NoMatch = NoMatch()
def regex(value, regexflags=None):
- """OpenEmbedded 'regex' type
+ """
+ OpenEmbedded 'regex' type.
Acts as a regular expression, returning the pre-compiled regular
- expression pattern object. To use this type, set the variable type flag
- to 'regex', and optionally, set the 'regexflags' type to a space separated
- list of the flags to control the regular expression matching (e.g.
- FOO[regexflags] += 'ignorecase'). See the python documentation on the
- 're' module for a list of valid flags."""
+ expression pattern object from the string ``value``.
+
+ To use this type, set a BitBake variable ``type`` flag
+ to ``regex``, and optionally, set the ``regexflags`` flag to a space-separated
+ list of the flags to control the regular expression matching.
+
+ The variable can then be used with :py:func:`oe.data.typed_value`.
+
+ For example::
+
+ FOO = "^foo[0-9]+$"
+ FOO[type] = "regex"
+ FOO[regexflags] += "ignorecase"
+
+ Then:
+
+ .. code-block:: python
+
+ if re.match(oe.data.typed_value("FOO", d), somevalue):
+ ...
+
+ See the Python documentation on the :py:mod:`re` module for a list of
+ valid flags.
+ """
flagval = 0
if regexflags:
@@ -106,10 +126,29 @@ def regex(value, regexflags=None):
(value, exc.args[0]))
def boolean(value):
- """OpenEmbedded 'boolean' type
+ """
+ OpenEmbedded 'boolean' type.
+
+ To use this type, set a BitBake variable ``type`` flag
+ to ``boolean``, and its value depending on the expected behavior:
- Valid values for true: 'yes', 'y', 'true', 't', '1'
- Valid values for false: 'no', 'n', 'false', 'f', '0', None
+ - To return ``True``: ``yes``, ``y``, ``true``, ``t`` or ``1``.
+ - To return ``False``: ``no``, ``n``, ``false``, ``f``, ``0`` or ``None``.
+
+ The variable can then be used with :py:func:`oe.data.typed_value`.
+
+ For example::
+
+ FOO = "yes"
+ FOO[type] = "boolean"
+
+ Then:
+
+ .. code-block:: python
+
+ if oe.data.typed_value("FOO", d):
+ # condition is met as FOO = "yes" so becomes "True"
+ ...
"""
if value is None:
return False
@@ -128,20 +167,56 @@ def boolean(value):
raise ValueError("Invalid boolean value '%s'" % value)
def integer(value, numberbase=10):
- """OpenEmbedded 'integer' type
+ """
+ OpenEmbedded 'integer' type.
+
+ To use this type, set a BitBake variable ``type`` flag
+ to ``integer``, and its value to an integer string. Optionally, the
+ ``numberbase`` flag can be set (defaults to base 10).
+
+ The variable can then be used with :py:func:`oe.data.typed_value`.
+
+ For example::
+
+ FOO = "13"
+ FOO[type] = "integer"
+
+ Then:
- Defaults to base 10, but this can be specified using the optional
- 'numberbase' flag."""
+ .. code-block:: python
+
+ if oe.data.typed_value("FOO", d) > 12:
+ # condition is met as FOO = "13" and 13 > 12
+ ...
+ """
return int(value, int(numberbase))
_float = float
def float(value, fromhex='false'):
- """OpenEmbedded floating point type
+ """
+ OpenEmbedded 'float' type.
+
+ To use this type, set a BitBake variable ``type`` flag
+ to ``float``, and its value to a floating number string. Optionally, the
+ ``fromhex`` flag can be set to "true" to use Python's built-in
+ :py:func:`float.fromhex` (defaults to "false").
+
+ The variable can then be used with :py:func:`oe.data.typed_value`.
+
+ For example::
- To use this type, set the type flag to 'float', and optionally set the
- 'fromhex' flag to a true value (obeying the same rules as for the
- 'boolean' type) if the value is in base 16 rather than base 10."""
+ FOO = "1.23"
+ FOO[type] = "float"
+
+ Then:
+
+ .. code-block:: python
+
+ if oe.data.typed_value("FOO", d) > 1:
+ # condition is met as FOO = "1.23" and 1.23 > 1
+ ...
+ """
if boolean(fromhex):
return _float.fromhex(value)
@@ -149,6 +224,42 @@ def float(value, fromhex='false'):
return _float(value)
def path(value, relativeto='', normalize='true', mustexist='false'):
+ """
+ OpenEmbedded 'path' type.
+
+ To use this type, set a BitBake variable ``type`` flag
+ to ``path``, and its value to a path. Optionally, the following variable
+ flags can be defined:
+
+ - ``relativeto``: another path string to join to the variable's value, with
+ :py:func:`os.path.join`:
+
+ .. code-block:: python
+
+ os.path.join(relativeto, value)
+
+ - ``normalize``: a boolean string ("true" by default) that normalizes the
+ path with :py:func:`os.path.normpath`.
+
+ - ``mustexist``: a boolean string ("false" by default) that ensures the
+ path to the file/directory exists, otherwise raises
+ :py:class:`ValueError`.
+
+ The variable can then be used with :py:func:`oe.data.typed_value`.
+
+ For example::
+
+ FOO = "src/pyproject.toml"
+ FOO[type] = "path"
+ FOO[relativeto] = "${S}"
+
+ Then:
+
+ .. code-block:: python
+
+ >>> print(oe.data.typed_value("FOO", d))
+ ".../path/to/source/src/pyproject.toml"
+ """
value = os.path.join(relativeto, value)
if boolean(normalize):
--
2.56.0
^ permalink raw reply related [flat|nested] 16+ messages in thread
* Re: [OE-core] [PATCH 05/13] lib/oe: move oe.types.{is_x86,qemu_use_kvm} to oe.qemu
2026-11-16 16:09 ` [PATCH 05/13] lib/oe: move oe.types.{is_x86,qemu_use_kvm} to oe.qemu Antonin Godard
@ 2026-11-17 10:09 ` Mathieu Dubois-Briand
2026-11-18 10:31 ` Antonin Godard
0 siblings, 1 reply; 16+ messages in thread
From: Mathieu Dubois-Briand @ 2026-11-17 10:09 UTC (permalink / raw)
To: antonin.godard, openembedded-core; +Cc: Thomas Petazzoni
On Mon Nov 16, 2026 at 5:09 PM CET, Antonin Godard via openembedded-core wrote:
> The oe.types library represents OpenEmbedded types such as booleans,
> integers, etc. which is unrelated to what these two functions do:
> is_x86() checks if a given arch matches the x86 architecture, and
> qemu_use_kvm() is used to return True to enable KVM based on the current
> target architecture.
>
> Move these two functions to oe.qemu which is more appropriate. Adapt
> usage in OE-Core as a consequence.
>
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
Hi Antonin,
Thanks for your patch.
> --- a/meta/lib/oe/qemu.py
> +++ b/meta/lib/oe/qemu.py
> @@ -52,3 +52,27 @@ def qemu_run_binary(d, rootfs_path, binary):
> base_libdir = rootfs_path + d.getVar("base_libdir", False)
>
> return qemu_wrapper_cmdline(d, rootfs_path, [libdir, base_libdir]) + rootfs_path + binary
> +
> +def is_x86(arch):
> + """
> + Check whether ``arch`` is ``x86`` or ``x86_64``, return ``True`` if it is,
> + ``False`` otherwise.
> + """
> + if arch.startswith('x86_') or re.match('i.*86', arch):
> + return True
> + else:
> + return False
> +
> +def qemu_use_kvm(kvm, target_arch):
> + """
> + Enable kvm if target_arch == build_arch or both of them are x86 archs.
> + """
> +
> + use_kvm = False
> + if kvm and boolean(kvm):
Missing import of oe.types here? We are probably also missing os and re.
https://autobuilder.yoctoproject.org/valkyrie/#/builders/50/builds/5078
https://autobuilder.yoctoproject.org/valkyrie/#/builders/95/builds/4956
Thanks,
Mathieu
--
Mathieu Dubois-Briand, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
^ permalink raw reply [flat|nested] 16+ messages in thread
* Re: [OE-core] [PATCH 05/13] lib/oe: move oe.types.{is_x86,qemu_use_kvm} to oe.qemu
2026-11-17 10:09 ` [OE-core] " Mathieu Dubois-Briand
@ 2026-11-18 10:31 ` Antonin Godard
0 siblings, 0 replies; 16+ messages in thread
From: Antonin Godard @ 2026-11-18 10:31 UTC (permalink / raw)
To: Mathieu Dubois-Briand, openembedded-core; +Cc: Thomas Petazzoni
On Tue Nov 17, 2026 at 11:09 AM CET, Mathieu Dubois-Briand wrote:
[...]
>> +
>> +def is_x86(arch):
>> + """
>> + Check whether ``arch`` is ``x86`` or ``x86_64``, return ``True`` if it is,
>> + ``False`` otherwise.
>> + """
>> + if arch.startswith('x86_') or re.match('i.*86', arch):
>> + return True
>> + else:
>> + return False
>> +
>> +def qemu_use_kvm(kvm, target_arch):
>> + """
>> + Enable kvm if target_arch == build_arch or both of them are x86 archs.
>> + """
>> +
>> + use_kvm = False
>> + if kvm and boolean(kvm):
>
> Missing import of oe.types here? We are probably also missing os and re.
>
> https://autobuilder.yoctoproject.org/valkyrie/#/builders/50/builds/5078
> https://autobuilder.yoctoproject.org/valkyrie/#/builders/95/builds/4956
Indeed, thanks Mathieu, those missing didn't prevent me from building the docs
so I did not spot that. Will be fixed in v2.
Antonin
^ permalink raw reply [flat|nested] 16+ messages in thread
end of thread, other threads:[~2026-11-18 10:31 UTC | newest]
Thread overview: 16+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-16 16:08 [PATCH 00/13] Improve or add oe.* library docstrings Antonin Godard
2026-11-16 16:08 ` [PATCH 01/13] lib/oe/path: rename "metadata" parameter to "d" Antonin Godard
2026-11-16 16:09 ` [PATCH 02/13] oe/path: simplify replace_absolute_symlinks() signature Antonin Godard
2026-11-16 16:09 ` [PATCH 03/13] lib/oe/utils: simplify str_filter*() signatures Antonin Godard
2026-11-16 16:09 ` [PATCH 04/13] lib/oe/utils: drop all_multilib_tune_list Antonin Godard
2026-11-16 16:09 ` [PATCH 05/13] lib/oe: move oe.types.{is_x86,qemu_use_kvm} to oe.qemu Antonin Godard
2026-11-17 10:09 ` [OE-core] " Mathieu Dubois-Briand
2026-11-18 10:31 ` Antonin Godard
2026-11-16 16:09 ` [PATCH 06/13] lib/oe/data: improve docstring for typed_value Antonin Godard
2026-11-16 16:09 ` [PATCH 07/13] lib/oe/go: detail map_arch() parameter Antonin Godard
2026-11-16 16:09 ` [PATCH 08/13] lib/oe/kernel: convert comments to docstrings and improve Antonin Godard
2026-11-16 16:09 ` [PATCH 09/13] lib/oe/lsb: improve docstrings Antonin Godard
2026-11-16 16:09 ` [PATCH 10/13] lib/oe/path: " Antonin Godard
2026-11-16 16:09 ` [PATCH 11/13] lib/oe/purl: " Antonin Godard
2026-11-16 16:09 ` [PATCH 12/13] lib/oe/utils: " Antonin Godard
2026-11-16 16:09 ` [PATCH 13/13] lib/oe/types: " Antonin Godard
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox