ksp-builder 0.0.0__py3-none-any.whl

ksp_builder/__init__.py

@@ -0,0 +1,222 @@
+"""ksp_builder — PEP 517 build backend for KSProject-based packages.
+
+Wraps setuptools and combines functionality from pyjnius-builder and
+pyswiftkit-builder into a single backend.  User-supplied ``before_build`` /
+``after_build`` scripts configured under ``[tool.ksp-builder]`` bracket every
+build, package sources can be compiled with Cython (``cythonize`` /
+``py_to_pyx``, replacing the old cythonized-app setup.py), Kivy ``.kv`` files
+can be compiled into the modules beside them (``compile_kv``), and three
+optional injection steps run after the base setuptools wheel/sdist is
+produced:
+
+1. **Java sources** — if ``[tool.pyjnius]`` is present, Java files from the
+   configured ``java-paths`` are injected under ``.java/`` (same convention
+   as pyjnius-builder).
+
+2. **Swift artifacts** — if ``[tool.pyswiftkit]`` is present *and*
+   ``pyswiftkit_builder`` is installed, ``swift build`` is executed and the
+   compiled ``.so`` / ``.dylib`` files are injected into the wheel.
+
+3. **Android gradle config** — if ``[tool.kivy-school.android]`` is present,
+   a ``.gradle/<package_name>.json`` file containing ``gradle_dependencies``,
+   ``permissions``, and ``meta_data`` is injected into the wheel/sdist.
+   ``ksproject`` can then discover and merge these JSON files from all
+   installed packages to assemble the final Gradle build configuration.
+
+The backend's own section::
+
+    [tool.ksp-builder]
+    before_build = "path/to/before_build_script.py"
+    after_build = "path/to/after_build_script.py"
+    cythonize = true
+    py_to_pyx = true
+    compile_kv = true
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from setuptools import build_meta as _setuptools_backend
+
+__all__ = [
+    "build_wheel",
+    "build_sdist",
+    "get_requires_for_build_wheel",
+    "get_requires_for_build_sdist",
+    "prepare_metadata_for_build_wheel",
+]
+
+# Pass-through hooks that need no extra logic.
+get_requires_for_build_wheel = _setuptools_backend.get_requires_for_build_wheel
+get_requires_for_build_sdist = _setuptools_backend.get_requires_for_build_sdist
+prepare_metadata_for_build_wheel = _setuptools_backend.prepare_metadata_for_build_wheel
+
+_st_build_editable = getattr(_setuptools_backend, "build_editable", None)
+_st_get_requires_for_build_editable = getattr(
+    _setuptools_backend, "get_requires_for_build_editable", None
+)
+_st_prepare_metadata_for_build_editable = getattr(
+    _setuptools_backend, "prepare_metadata_for_build_editable", None
+)
+
+if _st_get_requires_for_build_editable is not None:
+    get_requires_for_build_editable = _st_get_requires_for_build_editable
+    __all__.append("get_requires_for_build_editable")
+
+if _st_prepare_metadata_for_build_editable is not None:
+    prepare_metadata_for_build_editable = _st_prepare_metadata_for_build_editable
+    __all__.append("prepare_metadata_for_build_editable")
+
+
+# ---------------------------------------------------------------------------
+# Build hooks
+# ---------------------------------------------------------------------------
+
+def build_wheel(
+    wheel_directory: str,
+    config_settings: dict | None = None,
+    metadata_directory: str | None = None,
+) -> str:
+    project_dir = Path.cwd()
+
+    from ._pre_post_build import run_before_build, run_after_build
+    run_before_build(project_dir, "wheel")
+
+    # Swift build must happen before setuptools assembles the wheel so that
+    # the compiled .so/.dylib files can be picked up as package data.
+    swift_config = _load_swift_config(project_dir)
+    if swift_config is not None:
+        _run_swift_build(project_dir, swift_config)
+        _force_platform_wheel()
+
+    from ._build import ksp_build
+    with ksp_build(project_dir):
+        wheel_name = _setuptools_backend.build_wheel(
+            wheel_directory, config_settings, metadata_directory
+        )
+    wheel_path = Path(wheel_directory) / wheel_name
+
+    if swift_config is not None:
+        _inject_swift_artifacts(wheel_path, swift_config, project_dir)
+
+    from ._java import get_java_source_dirs, add_java_sources_to_wheel
+    java_dirs = get_java_source_dirs(
+        config_settings=config_settings, project_root=project_dir
+    )
+    add_java_sources_to_wheel(wheel_path, java_dirs)
+
+    from ._kivy_school import read_android_config
+    from ._gradle import inject_gradle_config_to_wheel
+    android_config = read_android_config(project_dir)
+    if android_config is not None:
+        inject_gradle_config_to_wheel(wheel_path, android_config)
+
+    run_after_build(project_dir, "wheel", wheel_path)
+
+    return wheel_name
+
+
+def build_sdist(sdist_directory: str, config_settings: dict | None = None) -> str:
+    project_dir = Path.cwd()
+
+    from ._pre_post_build import run_before_build, run_after_build
+    run_before_build(project_dir, "sdist")
+
+    sdist_name = _setuptools_backend.build_sdist(sdist_directory, config_settings)
+    sdist_path = Path(sdist_directory) / sdist_name
+
+    from ._java import get_java_source_dirs, add_java_sources_to_sdist
+    java_dirs = get_java_source_dirs(
+        config_settings=config_settings, project_root=project_dir
+    )
+    add_java_sources_to_sdist(sdist_path, java_dirs)
+
+    from ._kivy_school import read_android_config
+    from ._gradle import inject_gradle_config_to_sdist
+    android_config = read_android_config(project_dir)
+    if android_config is not None:
+        inject_gradle_config_to_sdist(sdist_path, android_config)
+
+    run_after_build(project_dir, "sdist", sdist_path)
+
+    return sdist_name
+
+
+if _st_build_editable is not None:
+    def build_editable(
+        wheel_directory: str,
+        config_settings: dict | None = None,
+        metadata_directory: str | None = None,
+    ) -> str:
+        project_dir = Path.cwd()
+
+        from ._pre_post_build import run_before_build, run_after_build
+        run_before_build(project_dir, "editable")
+
+        swift_config = _load_swift_config(project_dir)
+        if swift_config is not None:
+            _run_swift_build(project_dir, swift_config)
+            _force_platform_wheel()
+        if _st_build_editable is None:
+            raise RuntimeError("Editable builds are not supported by this setuptools version.")
+        
+        # Editable installs expose the source tree, so .py modules and .kv
+        # files are left alone; only real .pyx sources are compiled.
+        from ._build import ksp_build
+        with ksp_build(project_dir, editable=True):
+            wheel_name = _st_build_editable(
+                wheel_directory, config_settings, metadata_directory
+            )
+        wheel_path = Path(wheel_directory) / wheel_name
+
+        if swift_config is not None:
+            _inject_swift_artifacts(wheel_path, swift_config, project_dir)
+
+        from ._java import get_java_source_dirs, add_java_sources_to_wheel
+        java_dirs = get_java_source_dirs(
+            config_settings=config_settings, project_root=project_dir
+        )
+        add_java_sources_to_wheel(wheel_path, java_dirs)
+
+        from ._kivy_school import read_android_config
+        from ._gradle import inject_gradle_config_to_wheel
+        android_config = read_android_config(project_dir)
+        if android_config is not None:
+            inject_gradle_config_to_wheel(wheel_path, android_config)
+
+        run_after_build(project_dir, "editable", wheel_path)
+
+        return wheel_name
+
+    __all__.append("build_editable")
+
+
+# ---------------------------------------------------------------------------
+# Swift helpers (pyswiftkit_builder is an optional runtime dependency)
+# ---------------------------------------------------------------------------
+
+def _load_swift_config(project_dir: Path):
+    """Return a PSKConfig if [tool.pyswiftkit] is configured, else None."""
+    try:
+        from pyswiftkit_builder._config import read_config  # type: ignore[import-untyped]
+        return read_config(project_dir)
+    except ImportError:
+        return None
+    except (FileNotFoundError, KeyError, ValueError):
+        return None
+
+
+def _run_swift_build(project_dir: Path, config) -> None:
+    from pyswiftkit_builder._swift_build import build_swift  # type: ignore[import-untyped]
+    build_swift(project_dir, config)
+
+
+def _inject_swift_artifacts(wheel_path: Path, config, project_dir: Path) -> None:
+    from pyswiftkit_builder._swift_build import inject_artifacts  # type: ignore[import-untyped]
+    inject_artifacts(wheel_path, config, project_dir)
+
+
+def _force_platform_wheel() -> None:
+    """Tell setuptools this is a binary wheel (has native extensions)."""
+    import setuptools
+    setuptools.Distribution.has_ext_modules = lambda self: True  # type: ignore[method-assign]

ksp_builder/_build.py

@@ -0,0 +1,250 @@
+"""ksp_builder._build — hooks the generated sources into the setuptools build.
+
+``setuptools.build_meta`` runs ``from setuptools import setup; setup()`` when a
+project has no setup.py, so there is no place to declare ``ext_modules`` or a
+``cmdclass``.  :func:`ksp_build` wraps ``setuptools.setup`` for the duration of
+the build and passes them in there.
+
+It is also the one place that sees both compilation steps at once, which is
+what the three-switch combination needs::
+
+    [tool.ksp-builder]
+    cythonize = true
+    py_to_pyx = true
+    compile_kv = true
+
+With all three on, a ``.kv`` is compiled into a module, staged as a ``.pyx``
+and compiled to an extension; the ``.py`` that fed it is not shipped, and
+neither is the ``.kv``.
+"""
+from __future__ import annotations
+
+import contextlib
+import os
+import warnings
+from pathlib import Path
+from typing import Iterator
+
+from ._compile_kv import KvModule, compile_kv_modules, read_compile_kv
+from ._cythonize import CyModule, build_extensions, collect_modules, read_cythonize_config
+from ._packages import find_package_assets, prune_staging, read_section
+
+__all__ = ["ksp_build"]
+
+
+@contextlib.contextmanager
+def ksp_build(project_root: Path, *, editable: bool = False) -> Iterator[None]:
+    """Compile what ``[tool.ksp-builder]`` asks for, for this block's build.
+
+    A no-op when neither Cython nor KV compilation is configured.  An editable
+    install exposes the source tree itself, so nothing generated would ever be
+    imported: ``.py`` modules are left alone there and ``.kv`` files stay as
+    they are, and only hand-written ``.pyx`` sources are still compiled.
+    """
+    section = read_section(project_root)
+    config = read_cythonize_config(project_root)
+    compile_kv = read_compile_kv(project_root) and not editable
+
+    if config is None and not compile_kv:
+        yield
+        return
+
+    if config is not None and config.py_to_pyx and not config.cythonize:
+        print(
+            "ksp-builder: py_to_pyx is set but cythonize is not — "
+            "nothing will be compiled.",
+            flush=True,
+        )
+
+    convert_py = (
+        config is not None and config.cythonize and config.py_to_pyx and not editable
+    )
+
+    kv_modules: list[KvModule] = []
+    if compile_kv:
+        kv_modules = compile_kv_modules(
+            project_root,
+            as_pyx=convert_py,
+            exclude=config.exclude if config is not None else (),
+        )
+        for module in kv_modules:
+            print(f"ksp-builder: compile_kv {module.kv} -> {module.dotted}", flush=True)
+
+    cy_modules: list[CyModule] = []
+    if config is not None:
+        cy_modules = collect_modules(
+            project_root,
+            config,
+            allow_py_to_pyx=not editable,
+            skip={(m.package, m.name) for m in kv_modules},
+        )
+    cy_modules += [
+        CyModule(
+            package=module.package,
+            name=module.name,
+            source=module.source,
+            origin=module.kv,
+            converted=True,
+        )
+        for module in kv_modules
+        if module.as_pyx
+    ]
+
+    prune_staging(
+        project_root,
+        {project_root / m.source for m in cy_modules if m.converted}
+        | {project_root / m.source for m in kv_modules},
+    )
+
+    if not cy_modules and not kv_modules:
+        yield
+        return
+
+    for module in cy_modules:
+        print(f"ksp-builder: cythonize {module.origin} -> {module.dotted}", flush=True)
+
+    ext_modules = build_extensions(cy_modules, config) if cy_modules else []
+
+    keep_py = config is not None and config.keep_py
+    excluded: set[tuple[str, str]] = set()
+    if not keep_py:
+        excluded = {(m.package, m.name) for m in cy_modules if m.converted}
+
+    # A KV module that was not staged for Cython ships as source, generated
+    # from the .kv plus the .py beside it — so it replaces that .py, and adds a
+    # module of its own when there was no .py to begin with.
+    replacements = {
+        (m.package, m.name): str(project_root / m.source)
+        for m in kv_modules
+        if not m.as_pyx
+    }
+    # The .kv has been compiled into the module; shipping it too would only
+    # invite a second, conflicting set of rules at runtime.
+    compiled_kv = {os.path.abspath(project_root / m.kv) for m in kv_modules}
+
+    with _patched_setup(
+        ext_modules,
+        excluded=excluded,
+        replacements=replacements,
+        dropped_data=compiled_kv,
+        include_assets=bool(section.get("include_assets", True)),
+    ):
+        yield
+
+
+@contextlib.contextmanager
+def _patched_setup(
+    ext_modules: list,
+    *,
+    excluded: set[tuple[str, str]],
+    replacements: dict[tuple[str, str], str],
+    dropped_data: set[str],
+    include_assets: bool,
+) -> Iterator[None]:
+    import setuptools
+
+    original = setuptools.setup
+
+    def setup(**attrs):
+        attrs["ext_modules"] = list(attrs.get("ext_modules") or []) + list(ext_modules)
+        cmdclass = dict(attrs.get("cmdclass") or {})
+        cmdclass.setdefault(
+            "build_py",
+            _make_build_py(excluded, replacements, dropped_data, include_assets),
+        )
+        attrs["cmdclass"] = cmdclass
+        return original(**attrs)
+
+    setuptools.setup = setup
+    try:
+        with _quiet_data_directory_warning(include_assets):
+            yield
+    finally:
+        setuptools.setup = original
+
+
+@contextlib.contextmanager
+def _quiet_data_directory_warning(active: bool) -> Iterator[None]:
+    """Silence setuptools' "Package would be ignored" notice for asset dirs.
+
+    Shipping ``images/`` or ``fonts/`` as package data is the whole point here,
+    but the files reach egg-info's manifest, where setuptools sees importable
+    directories missing from ``packages`` and emits ~30 lines of advice for
+    each one.  Only that one warning is filtered, and only during our build.
+    """
+    category = None
+    if active:
+        from setuptools.command import build_py as _build_py_module
+
+        abuse = getattr(_build_py_module, "_IncludePackageDataAbuse", None)
+        category = getattr(abuse, "_Warning", None)
+
+    if category is None:
+        yield
+        return
+
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", category=category)
+        yield
+
+
+def _make_build_py(
+    excluded: set[tuple[str, str]],
+    replacements: dict[tuple[str, str], str],
+    dropped_data: set[str],
+    include_assets: bool,
+):
+    """A ``build_py`` that ships what this build generated, not what it read."""
+    from setuptools.command.build_py import build_py as _build_py
+
+    class build_py(_build_py):
+        ksp_excluded = excluded
+        ksp_replacements = replacements
+        ksp_dropped_data = dropped_data
+        ksp_include_assets = include_assets
+
+        def find_package_modules(self, package, package_dir):
+            found = [
+                entry
+                for entry in super().find_package_modules(package, package_dir)
+                if (entry[0], entry[1]) not in excluded
+            ]
+            generated = {
+                name: path
+                for (owner, name), path in replacements.items()
+                if owner == package
+            }
+            if not generated:
+                return found
+
+            modules = [
+                (pkg, name, generated.get(name, source)) for pkg, name, source in found
+            ]
+            present = {name for _, name, _ in found}
+            modules += [
+                (package, name, path)
+                for name, path in sorted(generated.items())
+                if name not in present
+            ]
+            return modules
+
+        def find_data_files(self, package, src_dir):
+            files = list(super().find_data_files(package, src_dir))
+            if include_assets and src_dir:
+                # exclude_data_files applies the project's exclude-package-data,
+                # which super() has already applied to its own half of the list.
+                found = self.exclude_data_files(
+                    package, src_dir, find_package_assets(Path(src_dir))
+                )
+                seen = set(files)
+                for path in found:
+                    if path not in seen:
+                        seen.add(path)
+                        files.append(path)
+            if dropped_data:
+                files = [
+                    path for path in files if os.path.abspath(path) not in dropped_data
+                ]
+            return files
+
+    return build_py

ksp_builder/_compile_kv.py

@@ -0,0 +1,158 @@
+"""ksp_builder._compile_kv — compiles Kivy ``.kv`` files into Python modules.
+
+Configured under ``[tool.ksp-builder]``::
+
+    [tool.ksp-builder]
+    compile_kv = true
+
+Every ``.kv`` sitting in a package directory is handed to the ``compilekv``
+library together with the ``.py`` of the same name beside it, and the module
+the two produce is written to the staging directory.  That generated module is
+what ships: it carries the hand-written code *and* the widget classes the KV
+rules describe, so the ``.kv`` itself is no longer needed at runtime and is
+left out of the wheel.
+
+With ``cythonize`` and ``py_to_pyx`` also on, the generated module is staged as
+a ``.pyx`` and compiled to an extension instead of shipping as source.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+
+from ._packages import (
+    NEVER_CONVERTED,
+    STAGING_DIR,
+    find_packages,
+    is_excluded,
+    stage_file,
+)
+
+__all__ = [
+    "KvModule",
+    "read_compile_kv",
+    "find_kv_sources",
+    "compile_kv_modules",
+]
+
+
+@dataclass
+class KvModule:
+    """One module compiled out of a ``.kv`` file."""
+
+    package: str  # dotted package name, e.g. "myapp.screens"
+    name: str  # module name without extension, e.g. "home"
+    source: Path  # the generated module, relative to the project root
+    kv: Path  # the .kv it was compiled from, relative to the project root
+    py: Path | None  # the hand-written .py merged into it, if there was one
+    as_pyx: bool  # True when the module was staged for Cython
+
+    @property
+    def dotted(self) -> str:
+        return f"{self.package}.{self.name}" if self.package else self.name
+
+
+def read_compile_kv(project_root: Path) -> bool:
+    """Whether ``[tool.ksp-builder] compile_kv`` is on."""
+    from ._packages import read_section
+
+    return bool(read_section(project_root).get("compile_kv", False))
+
+
+def _compilekv():
+    """The ``compilekv`` library, with a build-time error if it is missing."""
+    try:
+        import compilekv
+    except ImportError as exc:  # pragma: no cover - compilekv is a dependency
+        raise RuntimeError(
+            "ksp-builder: compile_kv is enabled but compilekv is not installed."
+        ) from exc
+    return compilekv
+
+
+def find_kv_sources(project_root: Path) -> list[tuple[str, Path]]:
+    """The ``(package, kv path)`` pairs this project can compile.
+
+    Only ``.kv`` files directly inside a package are collected — a compiled KV
+    file becomes an importable module, and there is no module name for one
+    sitting in a plain data directory.  Those stay ordinary package data.
+    """
+    find_kv_files = _compilekv().find_kv_files
+
+    sources: list[tuple[str, Path]] = []
+    for package, directory in sorted(find_packages(project_root).items()):
+        for kv_path in find_kv_files(directory, recursive=False):
+            sources.append((package, kv_path))
+    return sources
+
+
+def compile_kv_modules(
+    project_root: Path,
+    *,
+    as_pyx: bool = False,
+    exclude: Sequence[str] = (),
+) -> list[KvModule]:
+    """Compile every package ``.kv`` into the staging directory.
+
+    ``as_pyx`` stages the result for Cython instead of shipping it as source.
+    ``exclude`` is ``cythonize_exclude``: a module it names is still compiled
+    out of its KV file, it just stays a plain ``.py``.
+    """
+    sources = find_kv_sources(project_root)
+    if not sources:
+        return []
+
+    compilekv = _compilekv()
+    KvCompileError = compilekv.KvCompileError
+    source_path_for = compilekv.source_path_for
+
+    compiler = compilekv.default_compiler()
+    patterns = list(exclude)
+    modules: list[KvModule] = []
+
+    for package, kv_path in sources:
+        relative_kv = kv_path.relative_to(project_root)
+        py_path = source_path_for(kv_path)
+        has_py = py_path.is_file()
+        py_source = py_path.read_text(encoding="utf-8") if has_py else ""
+
+        try:
+            generated = compiler.compile_source(
+                kv_path.read_text(encoding="utf-8"), py_source
+            )
+        except KvCompileError as exc:
+            raise RuntimeError(f"ksp-builder: cannot compile {relative_kv}: {exc}") from exc
+
+        relative_py = py_path.relative_to(project_root) if has_py else None
+        staged_as_pyx = as_pyx and _compilable(kv_path.stem, relative_kv, relative_py, patterns)
+        suffix = ".pyx" if staged_as_pyx else ".py"
+        staged = Path(STAGING_DIR, *package.split("."), f"{kv_path.stem}{suffix}")
+        stage_file(project_root / staged, generated.encode("utf-8"))
+
+        modules.append(
+            KvModule(
+                package=package,
+                name=kv_path.stem,
+                source=staged,
+                kv=relative_kv,
+                py=relative_py,
+                as_pyx=staged_as_pyx,
+            )
+        )
+
+    return modules
+
+
+def _compilable(
+    stem: str,
+    relative_kv: Path,
+    relative_py: Path | None,
+    patterns: list[str],
+) -> bool:
+    """Whether the module built from this KV file may become an extension."""
+    if stem in NEVER_CONVERTED:
+        return False
+    if is_excluded(relative_kv, patterns):
+        return False
+    return relative_py is None or not is_excluded(relative_py, patterns)