Code generation workflow for the Slint Python bindings

.github/workflows/ci.yaml

@@ -213,10 +213,11 @@ jobs:
                   python-version: "3.12"
             - name: Install uv
               uses: astral-sh/setup-uv@v7
-            - uses: fjwillemsen/[email protected]
             - name: Run python tests
               working-directory: api/python/slint
-              run: nox --default-venv-backend uv
+              run: uv run pytest tests
+              env:
+                  MATURIN_PEP517_ARGS: --profile=dev
             - name: Run mypy
               working-directory: api/python/slint
               run: uv run mypy -p tests -p slint

api/python/briefcase/src/briefcasex_slint/__init__.py

@@ -2,6 +2,7 @@
 # SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-Slint-Royalty-free-2.0 OR LicenseRef-Slint-Software-3.0
 
 from pathlib import Path
+import inspect
 
 from briefcase.bootstraps.base import BaseGuiBootstrap
 
@@ -10,91 +11,92 @@ class SlintGuiBootstrap(BaseGuiBootstrap):
     display_name_annotation = "does not support Android/Web deployment"
 
     def app_source(self):
-        return """\
-import slint
+        return inspect.cleandoc("""
+            import slint
 
-class {{ cookiecutter.class_name }}(slint.loader.{{ cookiecutter.module_name }}.resources.app_window.AppWindow):
-    @slint.callback
-    def request_increase_value(self):
-        self.counter = self.counter + 1
+            class {{ cookiecutter.class_name }}(slint.loader.{{ cookiecutter.module_name }}.resources.app_window.AppWindow):
+                @slint.callback
+                def request_increase_value(self):
+                    self.counter = self.counter + 1
 
 
-def main():
-    main_window = {{ cookiecutter.class_name }}()
-    main_window.show()
-    main_window.run()
-"""
+            def main():
+                main_window = {{ cookiecutter.class_name }}()
+                main_window.show()
+                main_window.run()
+        """)
 
     def app_start_source(self):
-        return """\
-from {{ cookiecutter.module_name }}.app import main
+        return inspect.cleandoc("""
+            from {{ cookiecutter.module_name }}.app import main
 
-if __name__ == "__main__":
-    main()
-"""
+            if __name__ == "__main__":
+                main()
+        """)
 
     def pyproject_table_briefcase_app_extra_content(self):
-        return """
-requires = [
-]
-test_requires = [
-{% if cookiecutter.test_framework == "pytest" %}
-    "pytest",
-{% endif %}
-]
-"""
+        return inspect.cleandoc("""
+            requires = [
+            ]
+            test_requires = [
+            {% if cookiecutter.test_framework == "pytest" %}
+                "pytest",
+            {% endif %}
+            ]
+        """)
 
     def pyproject_table_macOS(self):
-        return """\
-universal_build = false
-requires = [
-    "slint",
-]
-"""
+        return inspect.cleandoc("""
+            universal_build = false
+            requires = [
+                "slint",
+            ]
+        """)
 
     def pyproject_table_linux(self):
-        return """\
-requires = [
-    "slint",
-]
-"""
+        return inspect.cleandoc("""
+            requires = [
+                "slint",
+            ]
+        """)
 
     def pyproject_table_windows(self):
-        return """\
-requires = [
-    "slint",
-]
-"""
+        return inspect.cleandoc("""
+            requires = [
+                "slint",
+            ]
+        """)
 
     def pyproject_table_iOS(self):
-        return """\
-requires = [
-    "slint",
-]
-"""
+        return inspect.cleandoc("""
+            requires = [
+                "slint",
+            ]
+        """)
 
     def post_generate(self, base_path: Path) -> None:
         target_dir = base_path / self.context["source_dir"] / "resources"
         target_dir.mkdir(parents=True, exist_ok=True)
         with open(target_dir / "app-window.slint", "w") as slint_file:
-            slint_file.write(r"""
-import { Button, VerticalBox, AboutSlint } from "std-widgets.slint";
-
-export component AppWindow inherits Window {
-    in-out property<int> counter: 42;
-    callback request-increase-value();
-    VerticalBox {
-        alignment: center;
-        AboutSlint {}
-        Text {
-            text: "Counter: \{root.counter}";
-        }
-        Button {
-            text: "Increase value";
-            clicked => {
-                root.request-increase-value();
-            }
-        }
-     }
-}
-""")
+            content = inspect.cleandoc("""
+                import { Button, VerticalBox, AboutSlint } from "std-widgets.slint";
+
+                export component AppWindow inherits Window {
+                    in-out property<int> counter: 42;
+                    callback request-increase-value();
+                    VerticalBox {
+                        alignment: center;
+                        AboutSlint {}
+                        Text {
+                            text: "Counter: {root.counter}";
+                        }
+                        Button {
+                            text: "Increase value";
+                            clicked => {
+                                root.request-increase-value();
+                            }
+                        }
+                    }
+                }
+            """)
+            slint_file.write(content)

api/python/slint/Cargo.toml

@@ -14,6 +14,7 @@ publish = false
 rust-version.workspace = true
 
 [lib]
+name = "core"
 path = "lib.rs"
 crate-type = ["cdylib", "rlib"]
 
@@ -39,20 +40,20 @@ renderer-skia-opengl = ["slint-interpreter/renderer-skia-opengl"]
 renderer-skia-vulkan = ["slint-interpreter/renderer-skia-vulkan"]
 renderer-software = ["slint-interpreter/renderer-software"]
 accessibility = ["slint-interpreter/accessibility"]
+stubgen = []
 
 
 [dependencies]
 i-slint-backend-selector = { workspace = true }
 i-slint-core = { workspace = true, features = ["tr"] }
+i-slint-common = { workspace = true }
 slint-interpreter = { workspace = true, features = ["default", "display-diagnostics", "internal"] }
 i-slint-compiler = { workspace = true }
 pyo3 = { version = "0.26", features = ["extension-module", "indexmap", "chrono", "abi3-py311"] }
 indexmap = { version = "2.1.0" }
 chrono = "0.4"
 spin_on = { workspace = true }
 css-color-parser2 = { workspace = true }
-pyo3-stub-gen = { version = "0.9.0", default-features = false }
+pyo3-stub-gen = { git = "https://github.com/GreyElaina/pyo3-stub-gen", branch = "main", default-features = false, features = ["infer_signature"] }
 smol = { version = "2.0.0" }
-
-[package.metadata.maturin]
-python-source = "slint"
+smol_str = { workspace = true }

api/python/slint/README.md

@@ -75,6 +75,84 @@ app.run()
 
 5. Run it with `uv run main.py`
 
+## Code Generation CLI
+
+Use the bundled code generator to derive Python bindings and type stubs from your `.slint` files. The generator lives in the `slint.codegen` module and exposes a CLI entry point.
+
+Run it with `uv`:
+
+```bash
+uv run -m slint.codegen generate --input path/to/app.slint --output generated
+```
+
+When `--output` is omitted the generated files are written next to each input source.
+
+You can also call the generator from Python:
+
+```python
+from pathlib import Path
+from slint.codegen.generator import generate_project
+from slint.codegen.models import GenerationConfig
+
+slint_file = Path("ui/app.slint")
+generate_project(
+    inputs=[slint_file],
+    output_dir=Path("generated"),
+    config=GenerationConfig(
+        include_paths=[slint_file.parent],
+        library_paths={},
+        style=None,
+        translation_domain=None,
+        quiet=True,
+    ),
+)
+```
+
+It's strongly recommended to run the code generator as part of your build process (e.g., `hatch` build hooks), so that the generated bindings are always in sync with your `.slint` files.
+
+## Component Libraries and `library_paths`
+
+Slint supports importing third-party component libraries such as the Material 3 component set under the `@material` namespace. Follow the instructions on [material.slint.dev/getting-started](https://material.slint.dev/getting-started/) to download the library bundle into your project (for example into `material-1.0/`).
+
+When you load a `.slint` file from Python, pass a `library_paths` dictionary that maps the library name to the `.slint` entry file in that bundle:
+
+```python
+from pathlib import Path
+import slint
+
+root = Path(__file__).parent
+ui = slint.load_file(
+    root / "ui" / "main.slint",
+    library_paths={
+        "material": root / "material-1.0" / "material.slint",
+    },
+)
+```
+
+The same mapping can be supplied to the code generator via `GenerationConfig` so the generated bindings reference the library correctly:
+
+```python
+from pathlib import Path
+from slint.codegen.generator import generate_project
+from slint.codegen.models import GenerationConfig
+
+slint_file = Path("ui/app.slint")
+
+generate_project(
+    inputs=[slint_file],
+    output_dir=Path("generated"),
+    config=GenerationConfig(
+        include_paths=[slint_file.parent],
+        library_paths={"material": Path("material-1.0/material.slint")},
+        style=None,
+        translation_domain=None,
+        quiet=True,
+    ),
+)
+```
+
+Any library referenced with `import { ... } from "@library-name"` must appear in `library_paths`, and the value should point to the `.slint` file that serves as the library's root entry point.
+
 ## API Overview
 
 ### Instantiating a Component

api/python/slint/brush.rs

@@ -2,7 +2,10 @@
 // SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-Slint-Royalty-free-2.0 OR LicenseRef-Slint-Software-3.0
 
 use pyo3::prelude::*;
-use pyo3_stub_gen::{derive::gen_stub_pyclass, derive::gen_stub_pymethods, impl_stub_type};
+use pyo3_stub_gen::{
+    derive::gen_stub_pyclass, derive::gen_stub_pyclass_complex_enum, derive::gen_stub_pymethods,
+    impl_stub_type,
+};
 
 use crate::errors::PyColorParseError;
 
@@ -33,6 +36,7 @@ struct RgbColor {
 }
 
 #[derive(FromPyObject)]
+#[gen_stub_pyclass_complex_enum]
 #[pyclass]
 enum PyColorInput {
     ColorStr(String),
@@ -57,8 +61,6 @@ enum PyColorInput {
     },
 }
 
-impl_stub_type!(PyColorInput = String | RgbaColor | RgbColor);
-
 /// A Color object represents a color in the RGB color space with an alpha. Each color channel and the alpha is represented
 /// as an 8-bit integer. The alpha channel is 0 for fully transparent and 255 for fully opaque.
 ///