pythonnative 0.9.0__tar.gz → 0.10.0__tar.gz

{pythonnative-0.9.0/src/pythonnative.egg-info → pythonnative-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonnative
-Version: 0.9.0
+Version: 0.10.0
 Summary: Cross-platform native UI toolkit for Android and iOS
 Author: Owen Carey
 License: MIT License
@@ -48,6 +48,8 @@ Provides-Extra: docs
 Requires-Dist: mkdocs>=1.5; extra == "docs"
 Requires-Dist: mkdocs-material[imaging]>=9.5; extra == "docs"
 Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Requires-Dist: mkdocs-autorefs>=1.0; extra == "docs"
+Requires-Dist: pymdown-extensions>=10.7; extra == "docs"
 Provides-Extra: dev
 Requires-Dist: black>=24.0; extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"

{pythonnative-0.9.0 → pythonnative-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythonnative"
-version = "0.9.0"
+version = "0.10.0"
 description = "Cross-platform native UI toolkit for Android and iOS"
 authors = [
   { name = "Owen Carey" }
@@ -35,6 +35,8 @@ docs = [
   "mkdocs>=1.5",
   "mkdocs-material[imaging]>=9.5",
   "mkdocstrings[python]>=0.24",
+  "mkdocs-autorefs>=1.0",
+  "pymdown-extensions>=10.7",
 ]
 dev = [
   "black>=24.0",
@@ -81,8 +83,32 @@ extend-exclude = [
 ]
 
 [tool.ruff.lint]
-select = ["E", "F", "I"]
-ignore = []
+# Docstring (D) rules use the Google convention; see [tool.ruff.lint.pydocstyle].
+# Selectively enabled so tests/examples/templates aren't penalized.
+select = ["E", "F", "I", "D"]
+# D107 (missing __init__ docstring): mkdocstrings is configured to merge
+#   __init__ into the class docstring, so the class docstring is the source of truth.
+# D105 (magic method docstring): most are self-explanatory (__repr__, __eq__, etc.).
+# D203/D213: conflict with Google convention defaults; ruff auto-suppresses
+#   these via `convention = "google"`, but we list them defensively.
+ignore = ["D107", "D105", "D203", "D213"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["D"]
+"examples/**/*.py" = ["D"]
+"src/pythonnative/templates/**/*.py" = ["D"]
+"setup.py" = ["D"]
+"conftest.py" = ["D"]
+# Platform handler subclasses implement the ViewHandler ABC defined in
+# native_views/base.py, which carries the canonical docstrings for the
+# protocol. The concrete classes are internal (registered by name in
+# NativeViewRegistry, never imported by users), so requiring per-method
+# docstrings would only add boilerplate that repeats the ABC.
+"src/pythonnative/native_views/android.py" = ["D101", "D102"]
+"src/pythonnative/native_views/ios.py" = ["D101", "D102"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
 
 [tool.black]
 line-length = 120

{pythonnative-0.9.0 → pythonnative-0.10.0}/src/pythonnative/__init__.py

@@ -1,7 +1,31 @@
-"""PythonNative — declarative native UI for Android and iOS.
+"""PythonNative: declarative native UI for Android and iOS.
 
-Public API::
+PythonNative is a cross-platform toolkit that turns Python ``@component``
+functions into real, native Android and iOS views. The component model
+is React-like (function components plus hooks), but rendering happens
+through direct platform bindings: Chaquopy on Android (Java) and
+rubicon-objc on iOS (Objective-C). There is no JavaScript bridge.
 
+Key building blocks:
+
+- **Element factories** ([`Text`][pythonnative.Text],
+  [`Button`][pythonnative.Button], [`Column`][pythonnative.Column], etc.)
+  return immutable [`Element`][pythonnative.Element] descriptors.
+- **Hooks** ([`use_state`][pythonnative.use_state],
+  [`use_effect`][pythonnative.use_effect],
+  [`use_reducer`][pythonnative.use_reducer], etc.) manage state, side
+  effects, and context inside `@component` functions.
+- **Navigation** is built from
+  [`NavigationContainer`][pythonnative.NavigationContainer] plus one of
+  the [`create_stack_navigator`][pythonnative.create_stack_navigator],
+  [`create_tab_navigator`][pythonnative.create_tab_navigator], or
+  [`create_drawer_navigator`][pythonnative.create_drawer_navigator]
+  factories.
+- **Styling** uses a single ``style`` dict per element (or a list of
+  dicts), composable via [`StyleSheet`][pythonnative.StyleSheet].
+
+Example:
+    ```python
     import pythonnative as pn
 
     @pn.component
@@ -12,9 +36,10 @@ Public API::
             pn.Button("+", on_click=lambda: set_count(count + 1)),
             style={"spacing": 12},
         )
+    ```
 """
 
-__version__ = "0.9.0"
+__version__ = "0.10.0"
 
 from .components import (
     ActivityIndicator,

{pythonnative-0.9.0 → pythonnative-0.10.0}/src/pythonnative/_ios_log.py

@@ -1,24 +1,22 @@
-"""Route Python ``sys.stdout``/``sys.stderr`` through fd 2 on iOS.
-
-Why
----
-When an app is launched via ``xcrun simctl launch --console-pty`` (what
-``pn run ios`` does), the simulator attaches the caller's terminal to
-the app's stderr, which is the same channel ``NSLog`` / ``os_log``
-writes to. Python ``print()`` calls, however, go to ``sys.stdout``
-(fd 1), and for reasons specific to how CPython's embedded framework
-is started on the iOS Simulator that descriptor does not reach the
-attached console. As a result users see Swift-side ``NSLog`` output
-but never their own ``print()`` output.
-
-Redirecting ``sys.stdout`` / ``sys.stderr`` at a Python level to write
+"""Route Python `sys.stdout`/`sys.stderr` through fd 2 on iOS.
+
+When an app is launched via `xcrun simctl launch --console-pty`
+(what `pn run ios` does), the simulator attaches the caller's
+terminal to the app's stderr, which is the same channel `NSLog` and
+`os_log` write to. Python `print()` calls, however, go to
+`sys.stdout` (fd 1), and for reasons specific to how CPython's
+embedded framework is started on the iOS Simulator that descriptor
+does not reach the attached console. As a result, users see
+Swift-side `NSLog` output but never their own `print()` output.
+
+Redirecting `sys.stdout` and `sys.stderr` at a Python level to write
 straight to fd 2 is a small, reliable fix: fd 2 *is* visible to
-``simctl`` (that's exactly how ``NSLog`` reaches the terminal), so
+`simctl` (that is exactly how `NSLog` reaches the terminal), so
 Python output lands next to the Swift logs with correct ordering.
 
-This module is intentionally self-contained: no rubicon-objc or
-platform-specific C bindings required, so it's safe to import early
-during ``pythonnative`` package initialization.
+This module is intentionally self-contained (no rubicon-objc or
+platform-specific C bindings required), so it is safe to import
+early during `pythonnative` package initialization.
 """
 
 from __future__ import annotations
@@ -33,8 +31,8 @@ _STDERR_FD = 2
 class _StderrStream:
     """Minimal text-mode file-like that writes UTF-8 bytes to fd 2.
 
-    It's write-through (no buffering) so a ``print()`` call appears in
-    the terminal immediately, which matches user expectations for an
+    Write-through (no buffering), so a `print()` call appears in the
+    terminal immediately. That matches user expectations for an
     interactive "run on simulator" log stream.
     """
 
@@ -82,9 +80,9 @@ _installed = False
 
 
 def install() -> None:
-    """Swap ``sys.stdout`` / ``sys.stderr`` for fd-2 writers.
+    """Swap `sys.stdout` and `sys.stderr` for fd-2 writers.
 
-    Safe to call multiple times; only the first call has effect.
+    Idempotent: only the first call has effect.
     """
     global _installed
     if _installed:

pythonnative-0.10.0/src/pythonnative/cli/__init__.py

@@ -0,0 +1,7 @@
+"""Command-line interface package for the `pn` script.
+
+The CLI entry point lives in
+[`pythonnative.cli.pn`][pythonnative.cli.pn] and is exposed as the
+`pn` console script (configured in `pyproject.toml`'s
+`[project.scripts]`).
+"""

{pythonnative-0.9.0 → pythonnative-0.10.0}/src/pythonnative/cli/pn.py

@@ -1,3 +1,19 @@
+"""`pn` CLI: scaffold, run, and clean PythonNative projects.
+
+The console script `pn` (declared in `pyproject.toml` under
+`[project.scripts]`) dispatches to one of three subcommands:
+
+- `pn init [name]`: scaffold a new project in the current directory.
+- `pn run android|ios`: stage code into a native template, build it,
+  install it, and stream logs back to the terminal.
+- `pn clean`: remove the local `build/` directory.
+
+The implementation here is intentionally side-effect heavy: it shells
+out to `gradle`, `xcodebuild`, `adb`, and `xcrun simctl`. Errors from
+those tools are usually surfaced inline so the developer sees the
+underlying message.
+"""
+
 import argparse
 import hashlib
 import json
@@ -7,15 +23,25 @@ import shutil
 import subprocess
 import sys
 import sysconfig
+import time
 import urllib.request
 from importlib import resources
 from typing import Any, Dict, List, Optional
 
 
 def init_project(args: argparse.Namespace) -> None:
-    """
-    Initialize a new PythonNative project.
-    Creates `app/`, `pythonnative.json`, `requirements.txt`, `.gitignore`.
+    """Scaffold a new PythonNative project in the current directory.
+
+    Creates `app/main_page.py`, `pythonnative.json`,
+    `requirements.txt`, and `.gitignore`. Refuses to overwrite
+    existing files unless `--force` is passed.
+
+    Args:
+        args: The parsed argparse namespace. Recognized attributes:
+
+            - `name` (`str`, optional): Project name (defaults to the
+              current directory name).
+            - `force` (`bool`): Overwrite existing files.
     """
     project_name: str = getattr(args, "name", None) or os.path.basename(os.getcwd())
     cwd: str = os.getcwd()
@@ -88,16 +114,29 @@ def MainPage():
 
 
 def _copy_dir(src: str, dst: str) -> None:
+    """Recursively copy `src` into `dst`, creating parents as needed."""
     os.makedirs(os.path.dirname(dst), exist_ok=True)
     shutil.copytree(src, dst, dirs_exist_ok=True)
 
 
 def _copy_bundled_template_dir(template_dir: str, destination: str) -> None:
-    """
-    Copy a bundled template directory into the destination directory.
-    Tries the repository `templates/` first during development, then
-    package resources when installed from a wheel.
-    The result should be `${destination}/{template_dir}`.
+    """Copy a bundled template directory into `destination`.
+
+    Search order:
+
+    1. Local source checkout (`src/pythonnative/templates/<name>`).
+    2. Repository `templates/<name>` (used when running from a clone).
+    3. Installed package data via `importlib.resources`.
+    4. `sysconfig` data/site directories (last resort).
+
+    Args:
+        template_dir: The bundled template subdirectory to copy
+            (e.g., `"android_template"`).
+        destination: Parent directory; the template lands at
+            `<destination>/<template_dir>`.
+
+    Raises:
+        FileNotFoundError: If no bundled copy can be located.
     """
     dest_path = os.path.join(destination, template_dir)
 
@@ -150,6 +189,11 @@ def _copy_bundled_template_dir(template_dir: str, destination: str) -> None:
 
 
 def _github_json(url: str) -> Any:
+    """Fetch a GitHub JSON endpoint, optionally authenticated.
+
+    Reads `GITHUB_TOKEN` or `GH_TOKEN` from the environment to raise
+    the unauthenticated rate limit.
+    """
     headers: dict[str, str] = {"User-Agent": "pythonnative-cli"}
     token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
     if token:
@@ -162,10 +206,21 @@ def _github_json(url: str) -> Any:
 def _resolve_python_apple_support_asset(
     py_major_minor: str = "3.11", preferred_name: str = "Python-3.11-iOS-support.b7.tar.gz"
 ) -> Optional[str]:
-    """
-    Find a browser_download_url for a Python-Apple-support asset on GitHub Releases.
-    Prefers an exact name match (preferred_name). Falls back to the newest
-    asset whose name contains "Python-{py_major_minor}-iOS-support" and endswith .tar.gz.
+    """Resolve a download URL for a `Python-Apple-support` release asset.
+
+    Prefers an exact name match for `preferred_name`; otherwise falls
+    back to the newest asset whose name contains
+    `Python-{py_major_minor}-iOS-support` and ends with `.tar.gz`.
+
+    Args:
+        py_major_minor: Python version string used in the asset name
+            (e.g., `"3.11"`).
+        preferred_name: Exact filename to prefer when multiple matching
+            assets exist.
+
+    Returns:
+        A `browser_download_url` string, or `None` if the GitHub API
+        call fails or no matching asset is found.
     """
     try:
         releases = _github_json("https://api.github.com/repos/beeware/Python-Apple-support/releases?per_page=100")
@@ -188,29 +243,33 @@ def _resolve_python_apple_support_asset(
 
 
 def create_android_project(project_name: str, destination: str) -> None:
-    """
-    Create a new Android project using a template.
+    """Stage the bundled Android template into `destination`.
 
-    :param project_name: The name of the project.
-    :param destination: The directory where the project will be created.
+    Args:
+        project_name: Project name (currently informational; the
+            template uses fixed package IDs).
+        destination: Directory to receive the staged project.
     """
-    # Copy the Android template project directory
     _copy_bundled_template_dir("android_template", destination)
 
 
 def create_ios_project(project_name: str, destination: str) -> None:
-    """
-    Create a new iOS project using a template.
+    """Stage the bundled iOS template into `destination`.
 
-    :param project_name: The name of the project.
-    :param destination: The directory where the project will be created.
+    Args:
+        project_name: Project name (currently informational; the
+            template uses fixed bundle IDs).
+        destination: Directory to receive the staged project.
     """
-    # Copy the iOS template project directory
     _copy_bundled_template_dir("ios_template", destination)
 
 
 def _read_project_config() -> dict:
-    """Read pythonnative.json from the current working directory."""
+    """Read `pythonnative.json` from the current working directory.
+
+    Returns:
+        The parsed config dict, or `{}` if the file is missing.
+    """
     config_path = os.path.join(os.getcwd(), "pythonnative.json")
     if os.path.exists(config_path):
         with open(config_path, encoding="utf-8") as f:
@@ -221,8 +280,15 @@ def _read_project_config() -> dict:
 def _read_requirements(requirements_path: str) -> list[str]:
     """Read a requirements file and return non-empty, non-comment lines.
 
-    Exits with an error if pythonnative is listed — the CLI bundles it
-    directly, so it must not be installed separately via pip/Chaquopy.
+    Exits with an error if `pythonnative` is listed: the CLI bundles
+    it directly, so it must not be installed separately via pip or
+    Chaquopy.
+
+    Args:
+        requirements_path: Path to a `requirements.txt` file.
+
+    Returns:
+        A list of requirement specifier strings, in file order.
     """
     if not os.path.exists(requirements_path):
         return []
@@ -246,6 +312,9 @@ def _read_requirements(requirements_path: str) -> list[str]:
     return result
 
 
+ANDROID_PACKAGE_ID: str = "com.pythonnative.android_template"
+HOT_RELOAD_DEV_ROOT: str = "pythonnative_dev"
+
 ANDROID_LOGCAT_FILTERS: list[str] = [
     "python.stdout:V",
     "python.stderr:V",
@@ -264,10 +333,13 @@ IOS_BUNDLE_ID: str = "com.pythonnative.ios-template"
 def _start_android_log_stream() -> Optional[subprocess.Popen]:
     """Clear logcat and stream Python-relevant log tags to the terminal.
 
-    Returns the ``adb logcat`` subprocess, or ``None`` when ``adb`` is
-    unavailable. Python's ``print()`` output reaches logcat via Chaquopy,
-    which redirects ``sys.stdout``/``sys.stderr`` to the ``python.stdout``
-    and ``python.stderr`` tags.
+    Python's `print()` output reaches logcat via Chaquopy, which
+    redirects `sys.stdout`/`sys.stderr` to the `python.stdout` and
+    `python.stderr` tags.
+
+    Returns:
+        The `adb logcat` subprocess, or `None` when `adb` is
+        unavailable on `PATH`.
     """
     try:
         subprocess.run(["adb", "logcat", "-c"], check=False, capture_output=True)
@@ -283,7 +355,10 @@ def _start_android_log_stream() -> Optional[subprocess.Popen]:
 
 
 def _terminate_subprocess(proc: Optional[subprocess.Popen]) -> None:
-    """Politely stop a subprocess, escalating to SIGKILL if needed."""
+    """Politely stop a subprocess, escalating to `SIGKILL` if needed.
+
+    A no-op when `proc` is `None` or has already exited.
+    """
     if proc is None:
         return
     if proc.poll() is not None:
@@ -295,9 +370,141 @@ def _terminate_subprocess(proc: Optional[subprocess.Popen]) -> None:
         proc.kill()
 
 
+def _hot_reload_manifest_payload(
+    changed_files: List[str],
+    project_dir: str,
+    *,
+    version: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Build the reload manifest consumed by the running app."""
+    from pythonnative.hot_reload import ModuleReloader
+
+    rel_files = sorted(os.path.relpath(path, project_dir) for path in changed_files)
+    return {
+        "version": version or str(time.time_ns()),
+        "files": rel_files,
+        "modules": ModuleReloader.modules_from_files(rel_files),
+    }
+
+
+def _write_hot_reload_manifest(changed_files: List[str], project_dir: str, build_dir: str) -> str:
+    """Write a local hot-reload manifest and return its path."""
+    manifest_dir = os.path.join(build_dir, "hot_reload")
+    os.makedirs(manifest_dir, exist_ok=True)
+    manifest_path = os.path.join(manifest_dir, "reload.json")
+    with open(manifest_path, "w", encoding="utf-8") as f:
+        json.dump(_hot_reload_manifest_payload(changed_files, project_dir), f)
+    return manifest_path
+
+
+def _android_hot_reload_dest(rel_path: str) -> str:
+    """Return a `run-as` relative destination for an app source file."""
+    return os.path.join("files", HOT_RELOAD_DEV_ROOT, rel_path)
+
+
+def _push_android_hot_reload_file(local_path: str, rel_path: str) -> bool:
+    """Push one file into the Android app's writable hot-reload overlay."""
+    tmp_path = f"/data/local/tmp/pythonnative-hot-reload-{os.getpid()}-{os.path.basename(local_path)}"
+    dest_path = _android_hot_reload_dest(rel_path)
+    dest_dir = os.path.dirname(dest_path)
+    push = subprocess.run(["adb", "push", local_path, tmp_path], check=False, capture_output=True)
+    if push.returncode != 0:
+        return False
+    subprocess.run(
+        ["adb", "shell", "run-as", ANDROID_PACKAGE_ID, "mkdir", "-p", dest_dir],
+        check=False,
+        capture_output=True,
+    )
+    copy = subprocess.run(
+        ["adb", "shell", "run-as", ANDROID_PACKAGE_ID, "cp", tmp_path, dest_path],
+        check=False,
+        capture_output=True,
+    )
+    subprocess.run(["adb", "shell", "rm", "-f", tmp_path], check=False, capture_output=True)
+    return copy.returncode == 0
+
+
+def _ios_data_container() -> Optional[str]:
+    """Return the booted simulator's app data container, if available."""
+    try:
+        result = subprocess.run(
+            ["xcrun", "simctl", "get_app_container", "booted", IOS_BUNDLE_ID, "data"],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError:
+        return None
+    if result.returncode != 0:
+        return None
+    container = result.stdout.strip()
+    return container or None
+
+
+def _push_ios_hot_reload_file(local_path: str, rel_path: str) -> bool:
+    """Copy one file into the booted iOS Simulator's hot-reload overlay."""
+    container = _ios_data_container()
+    if container is None:
+        return False
+    dest_path = os.path.join(container, "Documents", HOT_RELOAD_DEV_ROOT, rel_path)
+    os.makedirs(os.path.dirname(dest_path), exist_ok=True)
+    shutil.copy2(local_path, dest_path)
+    return True
+
+
+def _clear_android_hot_reload_overlay() -> bool:
+    """Remove stale Android hot-reload files before launching."""
+    result = subprocess.run(
+        ["adb", "shell", "run-as", ANDROID_PACKAGE_ID, "rm", "-rf", f"files/{HOT_RELOAD_DEV_ROOT}"],
+        check=False,
+        capture_output=True,
+    )
+    return result.returncode == 0
+
+
+def _clear_ios_hot_reload_overlay() -> bool:
+    """Remove stale iOS Simulator hot-reload files before launching."""
+    container = _ios_data_container()
+    if container is None:
+        return False
+    shutil.rmtree(os.path.join(container, "Documents", HOT_RELOAD_DEV_ROOT), ignore_errors=True)
+    return True
+
+
+def _clear_hot_reload_overlay(platform: str) -> bool:
+    """Remove stale hot-reload overlay files for `platform`."""
+    if platform == "android":
+        return _clear_android_hot_reload_overlay()
+    if platform == "ios":
+        return _clear_ios_hot_reload_overlay()
+    return False
+
+
+def _push_hot_reload_file(platform: str, local_path: str, rel_path: str) -> bool:
+    """Push a changed source file to the running app."""
+    if platform == "android":
+        return _push_android_hot_reload_file(local_path, rel_path)
+    if platform == "ios":
+        return _push_ios_hot_reload_file(local_path, rel_path)
+    return False
+
+
 def run_project(args: argparse.Namespace) -> None:
-    """
-    Run the specified project.
+    """Build and run the project on the requested platform.
+
+    Stages templates, copies the user's `app/` into the platform
+    project, optionally installs Python requirements, and (unless
+    `--prepare-only` is set) builds and launches the app on a
+    connected device or simulator. With `--hot-reload`, also watches
+    `app/` for changes and pushes updates to the device.
+
+    Args:
+        args: Parsed argparse namespace. Recognized attributes:
+
+            - `platform` (`"android"` | `"ios"`): Build target.
+            - `prepare_only` (`bool`): Stage files but skip the build.
+            - `hot_reload` (`bool`): Watch `app/` and push changes.
+            - `no_logs` (`bool`): Don't stream device logs after launch.
     """
     # Determine the platform
     platform: str = args.platform
@@ -407,6 +614,8 @@ def run_project(args: argparse.Namespace) -> None:
                 pass
         subprocess.run(["./gradlew", "installDebug"], check=True, env=env)
 
+        _clear_hot_reload_overlay(platform)
+
         # Run the Android app
         # Assumes that the package name of your app is "com.example.myapp" and the main activity is "MainActivity"
         # Replace "com.example.myapp" and ".MainActivity" with your actual package name and main activity
@@ -417,7 +626,7 @@ def run_project(args: argparse.Namespace) -> None:
                 "am",
                 "start",
                 "-n",
-                "com.pythonnative.android_template/.MainActivity",
+                f"{ANDROID_PACKAGE_ID}/.MainActivity",
             ],
             check=True,
         )
@@ -708,6 +917,7 @@ def run_project(args: argparse.Namespace) -> None:
                 subprocess.run(["xcrun", "simctl", "boot", udid], check=False, capture_output=True)
                 # Install
                 subprocess.run(["xcrun", "simctl", "install", udid, app_path], check=False)
+                _clear_hot_reload_overlay(platform)
                 if show_logs and not hot_reload:
                     # Attach the app's stdout/stderr to this terminal so Python
                     # print() calls and exceptions are visible. SIMCTL_CHILD_*
@@ -754,25 +964,37 @@ def run_project(args: argparse.Namespace) -> None:
 
 
 def _run_hot_reload(platform: str, project_dir: str, build_dir: str, show_logs: bool = True) -> None:
-    """Watch ``app/`` for changes and push updated files to the device.
+    """Watch `app/` for changes and push updated files to the device.
 
-    When ``show_logs`` is true and targeting Android, ``adb logcat`` is
-    streamed in parallel so Python print/exception output stays visible
-    alongside hot-reload notifications.
+    When `show_logs` is true and targeting Android, `adb logcat` is
+    streamed in parallel so Python print and exception output stays
+    visible alongside hot-reload notifications.
+
+    Args:
+        platform: Either `"android"` or `"ios"`.
+        project_dir: Absolute path to the user's project root.
+        build_dir: Absolute path to the staged build directory.
+        show_logs: Whether to stream device logs in parallel.
     """
-    from .hot_reload import FileWatcher
+    from ..hot_reload import FileWatcher
 
     app_dir = os.path.join(project_dir, "app")
 
     def on_change(changed_files: List[str]) -> None:
+        pushed: List[str] = []
         for fpath in changed_files:
             rel = os.path.relpath(fpath, project_dir)
             print(f"[hot-reload] Changed: {rel}")
-            if platform == "android":
-                dest = f"/data/data/com.pythonnative.android_template/files/{rel}"
-                subprocess.run(["adb", "push", fpath, dest], check=False, capture_output=True)
-            elif platform == "ios":
-                pass  # simctl file push would go here
+            if _push_hot_reload_file(platform, fpath, rel):
+                pushed.append(fpath)
+            else:
+                print(f"[hot-reload] Failed to push {rel}")
+        if pushed:
+            manifest = _write_hot_reload_manifest(pushed, project_dir, build_dir)
+            if _push_hot_reload_file(platform, manifest, "reload.json"):
+                print(f"[hot-reload] Signaled reload for {len(pushed)} file(s).")
+            else:
+                print("[hot-reload] Failed to signal reload; app will not refresh automatically.")
 
     print("[hot-reload] Watching app/ for changes. Press Ctrl+C to stop.")
     watcher = FileWatcher(app_dir, on_change, interval=1.0)
@@ -799,8 +1021,11 @@ def _run_hot_reload(platform: str, project_dir: str, build_dir: str, show_logs:
 
 
 def clean_project(args: argparse.Namespace) -> None:
-    """
-    Clean the specified project.
+    """Remove the local `build/` directory.
+
+    Args:
+        args: Parsed argparse namespace (unused; accepted for the
+            `set_defaults(func=...)` dispatch shape).
     """
     # Define the build directory
     build_dir: str = os.path.join(os.getcwd(), "build")
@@ -814,6 +1039,11 @@ def clean_project(args: argparse.Namespace) -> None:
 
 
 def main() -> None:
+    """Entry point for the `pn` console script.
+
+    Wires up the `init`, `run`, and `clean` subcommands and dispatches
+    to the corresponding handler.
+    """
     parser = argparse.ArgumentParser(prog="pn", description="PythonNative CLI")
     subparsers = parser.add_subparsers()