pythonnative 0.19.0__py3-none-any.whl → 0.21.0__py3-none-any.whl

pythonnative/hooks.py

@@ -76,6 +76,8 @@ class HookState:
         "_trigger_render",
         "_pending_effects",
         "_dirty",
+        "_vnode",
+        "_reconciler",
     )
 
     def __init__(self) -> None:
@@ -95,6 +97,13 @@ class HookState:
         # knows that a memoized component still needs to re-render even
         # when its props didn't change.
         self._dirty: bool = False
+        # Back-references wired by the reconciler so a state setter can
+        # mark *its own* component subtree dirty for a local re-render
+        # (instead of forcing a whole-app re-render from the root). Both
+        # stay ``None`` until the component is mounted, and are cleared
+        # again when it unmounts.
+        self._vnode: Any = None
+        self._reconciler: Any = None
 
     def reset_index(self) -> None:
         """Reset every per-hook cursor to ``0``.
@@ -182,6 +191,25 @@ def _schedule_trigger(trigger: Callable[[], None]) -> None:
         trigger()
 
 
+def _notify_state_changed(ctx: "HookState") -> None:
+    """Mark ``ctx``'s component dirty and schedule a render after a state change.
+
+    Enqueuing the owning ``VNode`` in the reconciler's dirty set is what
+    makes the subsequent render *local*: the screen host's trigger calls
+    ``flush_dirty``, which re-renders only the components marked here
+    rather than the whole app. The dirty mark is eager (so several
+    setters coalesce), while the render trigger respects
+    [`batch_updates`][pythonnative.batch_updates].
+    """
+    ctx._dirty = True
+    reconciler = ctx._reconciler
+    vnode = ctx._vnode
+    if reconciler is not None and vnode is not None:
+        reconciler.mark_dirty(vnode)
+    if ctx._trigger_render:
+        _schedule_trigger(ctx._trigger_render)
+
+
 @contextmanager
 def batch_updates() -> Generator[None, None, None]:
     """Coalesce multiple state updates into a single re-render.
@@ -272,9 +300,7 @@ def use_state(initial: Any = None) -> Tuple[Any, Callable]:
             new_value = new_value(ctx.states[idx])
         if ctx.states[idx] is not new_value and ctx.states[idx] != new_value:
             ctx.states[idx] = new_value
-            ctx._dirty = True
-            if ctx._trigger_render:
-                _schedule_trigger(ctx._trigger_render)
+            _notify_state_changed(ctx)
 
     return current, setter
 
@@ -339,9 +365,7 @@ def use_reducer(reducer: Callable[[Any, Any], Any], initial_state: Any) -> Tuple
         new_state = reducer(ctx.states[idx], action)
         if ctx.states[idx] is not new_state and ctx.states[idx] != new_state:
             ctx.states[idx] = new_state
-            ctx._dirty = True
-            if ctx._trigger_render:
-                _schedule_trigger(ctx._trigger_render)
+            _notify_state_changed(ctx)
 
     return current, dispatch
 

pythonnative/native_views/android.py

@@ -48,6 +48,26 @@ def _ctx() -> Any:
     return get_android_context()
 
 
+def _pn_runtime_class(class_name: str) -> Any:
+    """Resolve a PythonNative Android helper class for the running app.
+
+    The Android template's helper classes (e.g. ``PNVirtualListView``)
+    live in the app's own package, which the ``pn`` CLI relocates to the
+    configured ``application_id`` at build time. Deriving the package from
+    the runtime ``Context`` (rather than hardcoding the template package)
+    keeps these lookups correct for any app id.
+
+    Args:
+        class_name: The class name within the app package, e.g.
+            ``"PNVirtualListView"`` or ``"PNVirtualListView$Delegate"``.
+
+    Returns:
+        The resolved Java class.
+    """
+    package = _ctx().getPackageName()
+    return jclass(f"{package}.{class_name}")
+
+
 def _density() -> float:
     return float(_ctx().getResources().getDisplayMetrics().density)
 
@@ -1942,7 +1962,7 @@ def _java_id(jobj: Any) -> int:
 
 
 def _make_recyclerview_delegate(props: Dict[str, Any]) -> Any:
-    Delegate = jclass("com.pythonnative.android_template.PNVirtualListView$Delegate")
+    Delegate = _pn_runtime_class("PNVirtualListView$Delegate")
 
     class _Delegate(dynamic_proxy(Delegate)):
         def __init__(self, initial: Dict[str, Any]) -> None:
@@ -2003,7 +2023,7 @@ class VirtualListHandler(AndroidViewHandler):
 
     def create(self, props: Dict[str, Any]) -> Any:
         try:
-            PNVirtualListView = jclass("com.pythonnative.android_template.PNVirtualListView")
+            PNVirtualListView = _pn_runtime_class("PNVirtualListView")
             delegate = _make_recyclerview_delegate(props)
             rv = PNVirtualListView(_ctx(), delegate)
             if "background_color" in props and props["background_color"] is not None:

pythonnative/project/__init__.py

@@ -0,0 +1,68 @@
+"""App project model and build system for PythonNative.
+
+This package turns a declarative ``pythonnative.toml`` into real,
+branded, installable native apps. It is the engine behind the ``pn``
+CLI's ``run``, ``build``, and ``doctor`` commands, split into focused,
+independently-testable modules:
+
+- [`config`][pythonnative.project.config]: parse/validate the TOML into a
+  typed [`AppConfig`][pythonnative.project.config.AppConfig].
+- [`permissions`][pythonnative.project.permissions]: map declarative
+  capabilities to native permission artifacts.
+- [`android`][pythonnative.project.android] /
+  [`ios`][pythonnative.project.ios]: configure the staged native
+  templates for a specific app (identity, permissions, branding).
+- [`icons`][pythonnative.project.icons]: generate icons and splash
+  assets.
+- [`runtime_assets`][pythonnative.project.runtime_assets]: acquire the
+  embedded iOS CPython runtime.
+- [`builder`][pythonnative.project.builder]: orchestrate staging,
+  configuration, and the native toolchains.
+- [`doctor`][pythonnative.project.doctor]: diagnose the local toolchain.
+
+Most users interact with this package only through the ``pn`` CLI, but
+the API is public and stable enough to script against.
+"""
+
+from .builder import (
+    BuildArtifacts,
+    Builder,
+    BuildError,
+    CommandResult,
+    CommandRunner,
+    PreparedProject,
+    SubprocessRunner,
+)
+from .config import (
+    AndroidConfig,
+    AndroidSigning,
+    AppConfig,
+    ConfigError,
+    IOSConfig,
+    IOSSigning,
+    entrypoint_to_module,
+    render_default_toml,
+)
+from .permissions import CAPABILITIES, Capability, ResolvedPermissions, resolve_permissions
+
+__all__ = [
+    "AppConfig",
+    "ConfigError",
+    "IOSConfig",
+    "IOSSigning",
+    "AndroidConfig",
+    "AndroidSigning",
+    "entrypoint_to_module",
+    "render_default_toml",
+    "Capability",
+    "CAPABILITIES",
+    "ResolvedPermissions",
+    "resolve_permissions",
+    "Builder",
+    "BuildError",
+    "BuildArtifacts",
+    "PreparedProject",
+    "CommandRunner",
+    "SubprocessRunner",
+    "CommandResult",
+]

pythonnative/project/android.py

@@ -0,0 +1,504 @@
+"""Config-driven Android project configurator.
+
+Turns the bundled ``android_template`` into a concrete, buildable Gradle
+project for a specific [`AppConfig`][pythonnative.project.config.AppConfig]:
+
+- **Package relocation.** The template lives under
+  ``com.pythonnative.android_template``; this module rewrites and moves
+  it to the app's own ``application_id`` so each app ships a distinct
+  package. The PythonNative Android runtime resolves its helper classes
+  (``Navigator``, ``PNVirtualListView``) via ``getPackageName()``, so the
+  relocation needs no runtime configuration.
+- **Identity & SDKs.** ``applicationId``, ``versionCode``/``versionName``,
+  ``minSdk``/``targetSdk``/``compileSdk``, ABI filters, and the embedded
+  CPython version are written into ``app/build.gradle``.
+- **Permissions.** ``<uses-permission>`` entries (derived from
+  ``[permissions]``) and the launch orientation are written into
+  ``AndroidManifest.xml``.
+- **Signing.** A release ``signingConfig`` is injected when a keystore is
+  configured (passwords are read from the environment at build time).
+- **Branding.** Launcher icons and an Android 12+ splash screen are
+  generated from the configured assets.
+- **Python sources.** The user's ``app/`` and (in a dev checkout) the
+  in-repo ``pythonnative`` package are staged into Chaquopy's source set,
+  and ``requirements.txt`` is generated from ``[requirements].packages``.
+
+Everything here is plain file manipulation, which keeps it fully unit
+testable without an Android toolchain.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, List, Optional
+
+from . import icons
+from .config import AppConfig
+
+TEMPLATE_PACKAGE = "com.pythonnative.android_template"
+"""The fixed package the bundled Android template ships under."""
+
+TEXT_SUFFIXES = {".kt", ".java", ".gradle", ".xml", ".pro", ".properties", ".cfg"}
+
+_SOURCE_ROOTS = (
+    ("app", "src", "main", "java"),
+    ("app", "src", "test", "java"),
+    ("app", "src", "androidTest", "java"),
+)
+
+Logger = Callable[[str], None]
+
+
+@dataclass
+class AndroidLayout:
+    """Resolved paths within a configured Android project.
+
+    Attributes:
+        project_dir: The Gradle project root (``.../android_template``).
+        application_id: The final Android application id.
+        python_root: Chaquopy Python source root
+            (``app/src/main/python``).
+    """
+
+    project_dir: Path
+    application_id: str
+    python_root: Path
+
+
+def configure(
+    project_dir: Path,
+    config: AppConfig,
+    *,
+    dev_lib_root: Optional[Path] = None,
+    log: Optional[Logger] = None,
+) -> AndroidLayout:
+    """Fully configure a staged Android template for ``config``.
+
+    Args:
+        project_dir: The staged ``android_template`` directory.
+        config: The validated app configuration.
+        dev_lib_root: Path to an in-repo ``pythonnative`` package to
+            bundle (dev checkout); ``None`` to rely on the PyPI install.
+        log: Optional progress logger.
+
+    Returns:
+        An [`AndroidLayout`][pythonnative.project.android.AndroidLayout]
+        describing the configured project.
+    """
+    emit: Logger = log or (lambda _message: None)
+    project_dir = Path(project_dir)
+
+    relocate_package(project_dir, TEMPLATE_PACKAGE, config.application_id)
+    configure_gradle(project_dir, config)
+    configure_settings_gradle(project_dir, config)
+    configure_strings(project_dir, config)
+    configure_manifest(project_dir, config)
+    write_requirements(project_dir, config)
+
+    _apply_branding(project_dir, config, emit)
+
+    python_root = stage_python_sources(project_dir, config, dev_lib_root=dev_lib_root)
+    emit(f"Configured Android project ({config.application_id}).")
+    return AndroidLayout(project_dir=project_dir, application_id=config.application_id, python_root=python_root)
+
+
+# ======================================================================
+# Package relocation
+# ======================================================================
+
+
+def relocate_package(project_dir: Path, old_package: str, new_package: str) -> None:
+    """Rewrite and move the template's Java/Kotlin package.
+
+    Replaces every occurrence of ``old_package`` with ``new_package`` in
+    all text sources, then moves the source directories from the old
+    package path to the new one. A no-op when the packages are equal.
+
+    Args:
+        project_dir: The staged Android project root.
+        old_package: The dotted package currently in the template.
+        new_package: The desired dotted package (the app's id).
+    """
+    if old_package == new_package:
+        return
+
+    _replace_in_tree(project_dir, old_package, new_package)
+
+    old_rel = old_package.replace(".", os.sep)
+    new_rel = new_package.replace(".", os.sep)
+    for parts in _SOURCE_ROOTS:
+        source_root = project_dir.joinpath(*parts)
+        old_dir = source_root / old_rel
+        if not old_dir.is_dir():
+            continue
+        new_dir = source_root / new_rel
+        new_dir.mkdir(parents=True, exist_ok=True)
+        for entry in old_dir.iterdir():
+            shutil.move(str(entry), str(new_dir / entry.name))
+        _prune_empty_dirs(source_root, old_rel)
+
+
+def _replace_in_tree(root: Path, needle: str, replacement: str) -> None:
+    for path in root.rglob("*"):
+        if not path.is_file() or path.suffix not in TEXT_SUFFIXES:
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            continue
+        if needle in text:
+            path.write_text(text.replace(needle, replacement), encoding="utf-8")
+
+
+def _prune_empty_dirs(source_root: Path, relative: str) -> None:
+    current = source_root / relative
+    while current != source_root and current.is_dir() and not any(current.iterdir()):
+        current.rmdir()
+        current = current.parent
+
+
+# ======================================================================
+# Gradle / manifest / resources
+# ======================================================================
+
+
+def configure_gradle(project_dir: Path, config: AppConfig) -> None:
+    """Write identity, SDK levels, ABIs, Python version, and signing.
+
+    Args:
+        project_dir: The staged Android project root.
+        config: The validated app configuration.
+    """
+    gradle_path = project_dir / "app" / "build.gradle"
+    content = gradle_path.read_text(encoding="utf-8")
+
+    content = re.sub(r"versionCode\s+\d+", f"versionCode {config.build}", content)
+    content = re.sub(r'versionName\s+"[^"]*"', f'versionName "{config.version}"', content)
+    content = re.sub(r"minSdk\s+\d+", f"minSdk {config.android.min_sdk}", content)
+    content = re.sub(r"targetSdk\s+\d+", f"targetSdk {config.android.target_sdk}", content)
+    content = re.sub(r"compileSdk\s+\d+", f"compileSdk {config.android.compile_sdk}", content)
+    content = re.sub(r'version\s+"3\.\d+"', f'version "{config.python_version}"', content)
+
+    abi_csv = ", ".join(f'"{abi}"' for abi in config.android.abi_filters)
+    content = re.sub(r"abiFilters[^\n]*", f"abiFilters {abi_csv}", content)
+
+    if config.android.signing.is_configured:
+        content = _inject_signing(content, config)
+
+    gradle_path.write_text(content, encoding="utf-8")
+
+
+def _inject_signing(content: str, config: AppConfig) -> str:
+    signing = config.android.signing
+    assert signing.keystore is not None and signing.key_alias is not None
+    keystore_path = config.resolve_path(signing.keystore).as_posix()
+    block = (
+        "    signingConfigs {\n"
+        "        release {\n"
+        f"            storeFile file('{keystore_path}')\n"
+        f'            storePassword System.getenv("{signing.store_password_env}")\n'
+        f"            keyAlias '{signing.key_alias}'\n"
+        f'            keyPassword System.getenv("{signing.key_password_env}")\n'
+        "        }\n"
+        "    }\n"
+    )
+    if "signingConfigs {" not in content:
+        content = content.replace("    buildTypes {", block + "    buildTypes {", 1)
+    if "signingConfig signingConfigs.release" not in content:
+        content = content.replace(
+            "        release {\n            minifyEnabled false",
+            "        release {\n            signingConfig signingConfigs.release\n            minifyEnabled false",
+            1,
+        )
+    return content
+
+
+def configure_settings_gradle(project_dir: Path, config: AppConfig) -> None:
+    """Update ``rootProject.name`` to the configured project name.
+
+    Args:
+        project_dir: The staged Android project root.
+        config: The validated app configuration.
+    """
+    settings_path = project_dir / "settings.gradle"
+    if not settings_path.is_file():
+        return
+    content = settings_path.read_text(encoding="utf-8")
+    safe_name = re.sub(r"[^A-Za-z0-9_]", "_", config.name) or "app"
+    content = re.sub(r'rootProject\.name\s*=\s*"[^"]*"', f'rootProject.name = "{safe_name}"', content)
+    settings_path.write_text(content, encoding="utf-8")
+
+
+def configure_strings(project_dir: Path, config: AppConfig) -> None:
+    """Set the ``app_name`` string resource to the display name.
+
+    Args:
+        project_dir: The staged Android project root.
+        config: The validated app configuration.
+    """
+    strings_path = project_dir / "app" / "src" / "main" / "res" / "values" / "strings.xml"
+    if not strings_path.is_file():
+        return
+    content = strings_path.read_text(encoding="utf-8")
+    escaped = _xml_escape(config.display_name)
+    content = re.sub(
+        r'(<string name="app_name">)(.*?)(</string>)',
+        rf"\g<1>{escaped}\g<3>",
+        content,
+        flags=re.DOTALL,
+    )
+    strings_path.write_text(content, encoding="utf-8")
+
+
+def configure_manifest(project_dir: Path, config: AppConfig) -> None:
+    """Inject ``<uses-permission>`` entries and the launch orientation.
+
+    Args:
+        project_dir: The staged Android project root.
+        config: The validated app configuration.
+    """
+    manifest_path = project_dir / "app" / "src" / "main" / "AndroidManifest.xml"
+    content = manifest_path.read_text(encoding="utf-8")
+
+    permissions = config.resolved_permissions().android_permissions
+    if permissions:
+        lines = "".join(f'    <uses-permission android:name="{name}" />\n' for name in permissions)
+        content = content.replace("    <application", f"{lines}\n    <application", 1)
+
+    orientation_attr = _ANDROID_ORIENTATION.get(config.orientation)
+    if orientation_attr:
+        content = content.replace(
+            '            android:exported="true">',
+            f'            android:exported="true"\n            android:screenOrientation="{orientation_attr}">',
+            1,
+        )
+
+    manifest_path.write_text(content, encoding="utf-8")
+
+
+_ANDROID_ORIENTATION = {
+    "portrait": "portrait",
+    "landscape": "sensorLandscape",
+}
+
+
+def write_requirements(project_dir: Path, config: AppConfig) -> None:
+    """Generate ``app/requirements.txt`` from ``[requirements].packages``.
+
+    Chaquopy installs from this file (referenced by ``build.gradle``).
+
+    Args:
+        project_dir: The staged Android project root.
+        config: The validated app configuration.
+    """
+    requirements_path = project_dir / "app" / "requirements.txt"
+    body = "\n".join(config.requirements)
+    requirements_path.write_text(body + ("\n" if body else ""), encoding="utf-8")
+
+
+# ======================================================================
+# Branding (icons + splash)
+# ======================================================================
+
+
+def _apply_branding(project_dir: Path, config: AppConfig, emit: Logger) -> None:
+    res_dir = project_dir / "app" / "src" / "main" / "res"
+    icon_path = config.resolve_path(config.icon) if config.icon else None
+    splash_path = config.resolve_path(config.splash) if config.splash else None
+
+    if icon_path and icons.has_source(icon_path):
+        if icons.generate_android_icons(icon_path, res_dir):
+            emit("Generated Android launcher icons.")
+        else:
+            emit("Skipping Android icons: Pillow not installed (pip install 'pythonnative[build]').")
+
+    if splash_path and icons.has_source(splash_path):
+        if icons.pillow_available():
+            configure_splash(project_dir, config, splash_path)
+            emit("Configured Android splash screen.")
+        else:
+            emit("Skipping Android splash: Pillow not installed (pip install 'pythonnative[build]').")
+
+
+def configure_splash(project_dir: Path, config: AppConfig, splash_path: Path) -> None:
+    """Wire up an Android 12+ splash screen from the splash asset.
+
+    Adds the ``androidx.core:core-splashscreen`` dependency, a
+    ``Theme.App.Starting`` splash theme (with the splash background color
+    and centered icon), installs the splash in ``MainActivity``, and
+    points the launcher activity at the splash theme.
+
+    Args:
+        project_dir: The staged Android project root.
+        config: The validated app configuration.
+        splash_path: Path to the source splash image.
+    """
+    res_dir = project_dir / "app" / "src" / "main" / "res"
+    background = icons.dominant_background_color(splash_path) or "#FFFFFF"
+
+    icons.generate_android_splash_icon(splash_path, res_dir / "drawable-xxxhdpi" / "pn_splash_icon.png")
+
+    _upsert_color(res_dir / "values" / "colors.xml", "pn_splash_background", background)
+
+    splash_style = (
+        '    <style name="Theme.App.Starting" parent="Theme.SplashScreen">\n'
+        '        <item name="windowSplashScreenBackground">@color/pn_splash_background</item>\n'
+        '        <item name="windowSplashScreenAnimatedIcon">@drawable/pn_splash_icon</item>\n'
+        '        <item name="postSplashScreenTheme">@style/Theme.Android_template</item>\n'
+        "    </style>\n"
+    )
+    for themes in (res_dir / "values" / "themes.xml", res_dir / "values-night" / "themes.xml"):
+        _insert_style(themes, splash_style)
+
+    _add_gradle_dependency(
+        project_dir / "app" / "build.gradle",
+        "implementation 'androidx.core:core-splashscreen:1.0.1'",
+    )
+    _install_splash_in_activity(project_dir, config)
+
+    # Point the app theme at the splash theme; ``installSplashScreen()`` swaps
+    # to ``postSplashScreenTheme`` (the original theme) right after launch.
+    manifest_path = project_dir / "app" / "src" / "main" / "AndroidManifest.xml"
+    manifest = manifest_path.read_text(encoding="utf-8")
+    manifest = manifest.replace(
+        'android:theme="@style/Theme.Android_template"',
+        'android:theme="@style/Theme.App.Starting"',
+        1,
+    )
+    manifest_path.write_text(manifest, encoding="utf-8")
+
+
+def _install_splash_in_activity(project_dir: Path, config: AppConfig) -> None:
+    activity = project_dir / "app" / "src" / "main" / "java" / config.android_package_path / "MainActivity.kt"
+    if not activity.is_file():
+        return
+    content = activity.read_text(encoding="utf-8")
+    if "installSplashScreen" in content:
+        return
+    content = content.replace(
+        "import androidx.appcompat.app.AppCompatActivity",
+        "import androidx.appcompat.app.AppCompatActivity\n"
+        "import androidx.core.splashscreen.SplashScreen.Companion.installSplashScreen",
+        1,
+    )
+    content = content.replace(
+        "        super.onCreate(savedInstanceState)",
+        "        installSplashScreen()\n        super.onCreate(savedInstanceState)",
+        1,
+    )
+    activity.write_text(content, encoding="utf-8")
+
+
+# ======================================================================
+# Python source staging
+# ======================================================================
+
+
+def stage_python_sources(
+    project_dir: Path,
+    config: AppConfig,
+    *,
+    dev_lib_root: Optional[Path] = None,
+) -> Path:
+    """Copy the user's ``app/`` and (optionally) the in-repo library.
+
+    Args:
+        project_dir: The staged Android project root.
+        config: The validated app configuration.
+        dev_lib_root: Path to an in-repo ``pythonnative`` package to
+            bundle, or ``None``.
+
+    Returns:
+        The Chaquopy Python source root (``app/src/main/python``).
+    """
+    python_root = project_dir / "app" / "src" / "main" / "python"
+    python_root.mkdir(parents=True, exist_ok=True)
+
+    app_src = config.project_root / "app"
+    if app_src.is_dir():
+        shutil.copytree(app_src, python_root / "app", dirs_exist_ok=True)
+
+    if dev_lib_root and dev_lib_root.is_dir():
+        shutil.copytree(
+            dev_lib_root,
+            python_root / "pythonnative",
+            dirs_exist_ok=True,
+            ignore=LIB_IGNORE,
+        )
+
+    return python_root
+
+
+LIB_IGNORE = shutil.ignore_patterns("templates", "__pycache__", "*.pyc", "*.pyo")
+"""Ignore rules for bundling the ``pythonnative`` package (skips templates)."""
+
+
+# ======================================================================
+# Small XML/text helpers
+# ======================================================================
+
+
+def _xml_escape(value: str) -> str:
+    return value.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def _upsert_color(colors_path: Path, name: str, value: str) -> None:
+    if not colors_path.is_file():
+        colors_path.parent.mkdir(parents=True, exist_ok=True)
+        colors_path.write_text(
+            '<?xml version="1.0" encoding="utf-8"?>\n<resources>\n</resources>\n',
+            encoding="utf-8",
+        )
+    content = colors_path.read_text(encoding="utf-8")
+    entry = f'    <color name="{name}">{value}</color>\n'
+    if f'name="{name}"' in content:
+        content = re.sub(
+            rf'(<color name="{re.escape(name)}">)(.*?)(</color>)',
+            rf"\g<1>{value}\g<3>",
+            content,
+        )
+    else:
+        content = content.replace("</resources>", f"{entry}</resources>", 1)
+    colors_path.write_text(content, encoding="utf-8")
+
+
+def _insert_style(themes_path: Path, style_block: str) -> None:
+    if not themes_path.is_file():
+        return
+    content = themes_path.read_text(encoding="utf-8")
+    if "Theme.App.Starting" in content:
+        return
+    content = content.replace("</resources>", f"{style_block}</resources>", 1)
+    themes_path.write_text(content, encoding="utf-8")
+
+
+def _add_gradle_dependency(gradle_path: Path, dependency: str) -> None:
+    content = gradle_path.read_text(encoding="utf-8")
+    if dependency in content:
+        return
+    content = content.replace("dependencies {\n", f"dependencies {{\n    {dependency}\n", 1)
+    gradle_path.write_text(content, encoding="utf-8")
+
+
+def collect_logcat_filters() -> List[str]:
+    """Return the logcat tag filters used when streaming device logs.
+
+    Returns:
+        A list of ``tag:level`` filter specs ending with ``*:S`` to
+        silence everything else.
+    """
+    return [
+        "python.stdout:V",
+        "python.stderr:V",
+        "MainActivity:V",
+        "ScreenFragment:V",
+        "Navigator:V",
+        "PythonNative:V",
+        "AndroidRuntime:E",
+        "System.err:W",
+        "*:S",
+    ]