test: Check the examples in README.md

This extracts the examples into temporary files and runs them through
pytest. Let's make sure that these don't break again in the future!

Author: martinpitt

tests/test_readme_examples.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+"""Test that code examples in README.md actually work"""
+
+# pylint does not understand pytest fixtures..
+# pylint: disable=redefined-outer-name
+
+__author__ = "Martin Pitt"
+__copyright__ = """
+(c) 2026 Martin Pitt <martin@piware.de>
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture(scope="module")
+def readme_blocks():
+    """Extract Python code blocks from README.md"""
+    readme_path = Path(__file__).parent.parent / "README.md"
+    content = readme_path.read_text()
+    blocks = []
+    in_python_block = False
+    current_block = []
+
+    for line in content.splitlines():
+        if line.strip() == "```python":
+            in_python_block = True
+            current_block = []
+        elif line.strip() == "```" and in_python_block:
+            in_python_block = False
+            if current_block:
+                blocks.append("\n".join(current_block))
+            current_block = []
+        elif in_python_block:
+            current_block.append(line)
+
+    return blocks
+
+
+def test_examples_exist(readme_blocks):
+    """Verify that we found some Python code blocks"""
+    assert len(readme_blocks) > 0
+
+
+def test_readme_examples(readme_blocks, tmp_path):
+    """Test all README examples by running them through pytest"""
+    for i, code_block in enumerate(readme_blocks):
+        # Write the code to a temporary file (works in read-only source directories)
+        test_file = tmp_path / f"test_readme_example_{i}.py"
+        test_file.write_text(code_block)
+
+        # Run pytest on the temporary file - will raise CalledProcessError if it fails
+        subprocess.run(
+            [sys.executable, "-m", "pytest", str(test_file), "-v"],
+            check=True,
+        )