pythonnative 0.22.0__tar.gz → 0.23.0__tar.gz

{pythonnative-0.22.0/src/pythonnative.egg-info → pythonnative-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonnative
-Version: 0.22.0
+Version: 0.23.0
 Summary: Cross-platform native UI toolkit for Android and iOS
 Author: Owen Carey
 License: MIT License
@@ -28,7 +28,7 @@ License: MIT License
 Project-URL: Homepage, https://github.com/pythonnative/pythonnative
 Project-URL: Repository, https://github.com/pythonnative/pythonnative
 Project-URL: Issues, https://github.com/pythonnative/pythonnative/issues
-Project-URL: Documentation, https://docs.pythonnative.com/
+Project-URL: Documentation, https://pythonnative.com/
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -83,13 +83,13 @@ Dynamic: license-file
   <a href="https://pypi.org/project/pythonnative/"><img src="https://img.shields.io/pypi/v/pythonnative" alt="PyPI Version" /></a>
   <a href="https://pypi.org/project/pythonnative/"><img src="https://img.shields.io/pypi/pyversions/pythonnative" alt="Python Versions" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/pypi/l/pythonnative" alt="License: MIT" /></a>
-  <a href="https://docs.pythonnative.com/"><img src="https://img.shields.io/website?url=https%3A%2F%2Fdocs.pythonnative.com&label=docs" alt="Docs" /></a>
+  <a href="https://pythonnative.com/"><img src="https://img.shields.io/website?url=https%3A%2F%2Fpythonnative.com&label=docs" alt="Docs" /></a>
 </p>
 
 <p align="center">
-  <a href="https://docs.pythonnative.com/">Documentation</a> ·
-  <a href="https://docs.pythonnative.com/getting-started/">Getting Started</a> ·
-  <a href="https://docs.pythonnative.com/examples/">Examples</a> ·
+  <a href="https://pythonnative.com/">Documentation</a> ·
+  <a href="https://pythonnative.com/getting-started/">Getting Started</a> ·
+  <a href="https://pythonnative.com/examples/">Examples</a> ·
   <a href="CONTRIBUTING.md">Contributing</a>
 </p>
 
@@ -102,19 +102,19 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 ## Features
 
 - **Declarative UI:** Describe *what* your UI should look like with element functions (`Text`, `Button`, `Column`, `Row`, etc.). PythonNative creates and updates native views automatically.
-- **Rich component library:** 25+ built-in components backed by real native widgets — `TextInput`, `Image` / `ImageBackground`, `ScrollView`, `FlatList` / `SectionList`, `Modal`, `Pressable` / `TouchableOpacity`, `Switch` / `Checkbox`, `Slider`, `SegmentedControl`, `Picker`, `DatePicker`, `ProgressBar` / `ActivityIndicator`, `WebView`, and more.
-- **Device APIs:** Cross-platform modules for `Camera`, `Location`, `FileSystem`, `Notifications`, `Clipboard`, `Share`, `Linking`, `Permissions`, `AppState`, `NetInfo`, `SecureStore`, `Battery`, `Haptics` / `Vibration`, and `Biometrics` — plus reactive `use_app_state` and `use_net_info` hooks.
+- **Rich component library:** 25+ built-in components backed by real native widgets: `TextInput`, `Image` / `ImageBackground`, `ScrollView`, `FlatList` / `SectionList`, `Modal`, `Pressable` / `TouchableOpacity`, `Switch` / `Checkbox`, `Slider`, `SegmentedControl`, `Picker`, `DatePicker`, `ProgressBar` / `ActivityIndicator`, `WebView`, and more.
+- **Device APIs:** Cross-platform modules for `Camera`, `Location`, `FileSystem`, `Notifications`, `Clipboard`, `Share`, `Linking`, `Permissions`, `AppState`, `NetInfo`, `SecureStore`, `Battery`, `Haptics` / `Vibration`, and `Biometrics`, plus reactive `use_app_state` and `use_net_info` hooks.
 - **Hooks and function components:** Manage state with `use_state`, side effects with `use_effect`, and navigation with `use_navigation`, all through one consistent pattern.
 - **Typed `style` prop:** Pass all visual and layout properties through a single `style` dict, fully described by the `pn.Style` `TypedDict` and the ergonomic `pn.style(...)` helper for IDE autocomplete and static checking. Compose reusable styles with `StyleSheet`.
 - **Cross-platform flexbox engine:** A pure-Python, Yoga-style layout engine computes frames once and applies them to native views, so `flex`, `padding`, `aspect_ratio`, and `position: "absolute"` produce the same geometry on Android and iOS.
-- **Virtual view tree + reconciler:** Element trees are diffed and patched with minimal native mutations, similar to React's reconciliation. Each commit lands as **one batched transaction** of mutation ops, and event callbacks are routed through a tag-based registry so re-renders that only change closures cost zero native calls. State updates re-render **locally** — only the component whose state changed (and its subtree) re-runs, and unchanged leaves reuse cached intrinsic measurements — so deep UIs stay responsive instead of re-rendering the whole app from the root on every tap.
+- **Virtual view tree + reconciler:** Element trees are diffed and patched with minimal native mutations, similar to React's reconciliation. Each commit lands as **one batched transaction** of mutation ops, and event callbacks are routed through a tag-based registry so re-renders that only change closures cost zero native calls. State updates re-render **locally**: only the component whose state changed (and its subtree) re-runs, and unchanged leaves reuse cached intrinsic measurements, so deep UIs stay responsive instead of re-rendering the whole app from the root on every tap.
 - **Native-driven animations:** The `Animated` API (timing / spring / decay, awaitable or fire-and-forget) hands animations to Core Animation and `ViewPropertyAnimator` whenever possible, so no Python code runs per frame; a pure-Python ticker covers the rest.
-- **Native gesture system:** Attach `Tap`, `LongPress`, `Pan`, `Swipe`, `Pinch`, and `Rotation` recognizers to any view via the `gestures=` prop — backed by `UIGestureRecognizer` on iOS and a unit-testable pure-Python arbiter on Android and desktop.
-- **Virtualized lists:** `FlatList` / `SectionList` window their rows in Python over the platform scroll view — uniform, exact, or measured variable heights, grids, headers/footers, infinite scroll, and an imperative scroll controller, identical on every platform.
+- **Native gesture system:** Attach `Tap`, `LongPress`, `Pan`, `Swipe`, `Pinch`, and `Rotation` recognizers to any view via the `gestures=` prop, backed by `UIGestureRecognizer` on iOS and a unit-testable pure-Python arbiter on Android and desktop.
+- **Virtualized lists:** `FlatList` / `SectionList` window their rows in Python over the platform scroll view: uniform, exact, or measured variable heights, grids, headers/footers, infinite scroll, and an imperative scroll controller, identical on every platform.
 - **Direct native bindings:** Python calls platform APIs directly through Chaquopy and rubicon-objc, with no JavaScript bridge.
 - **Custom-component SDK:** Wrap any platform widget as a first-class element with type-checked props via `pythonnative.sdk` (`Props`, `@native_component`, `element_factory`). Plugins distributed on PyPI auto-register through the `pythonnative.handlers` entry-point group.
 - **CLI scaffolding:** `pn init` creates a ready-to-run project; `pn run android` and `pn run ios` build and launch your app.
-- **Instant desktop preview:** `pn preview` renders your app in a native desktop window via Tkinter with Fast Refresh on every save — iterate on layout, state, and navigation in milliseconds without booting a simulator or device. The reconciler, hooks, layout engine, and navigation are the same code that ships to the phone.
+- **Instant desktop preview:** `pn preview` renders your app in a native desktop window via Tkinter with Fast Refresh on every save: iterate on layout, state, and navigation in milliseconds without booting a simulator or device. The reconciler, hooks, layout engine, and navigation are the same code that ships to the phone.
 - **Native-backed navigation:** Declarative `Stack`, `Tab`, and `Drawer` navigators inspired by React Navigation. The root stack drives the platform's native navigation controller (`UINavigationController` on iOS, AndroidX Navigation Component on Android), so transitions, back gestures, and the hardware back button match what users expect.
 - **Fast Refresh hot reload:** `pn run --hot-reload` watches `app/` and patches edits into the running app on save, preserving component state across most changes.
 - **Bundled templates:** Android Gradle and iOS Xcode templates are included, so scaffolding requires no network access.
@@ -148,7 +148,7 @@ def App():
 
 ## Documentation
 
-Visit [docs.pythonnative.com](https://docs.pythonnative.com/) for the full documentation, including getting started guides, platform-specific instructions for Android and iOS, API reference, and working examples.
+Visit [pythonnative.com](https://pythonnative.com/) for the full documentation, including getting started guides, platform-specific instructions for Android and iOS, API reference, and working examples.
 
 ## Contributing
 

{pythonnative-0.22.0 → pythonnative-0.23.0}/README.md

@@ -12,13 +12,13 @@
   <a href="https://pypi.org/project/pythonnative/"><img src="https://img.shields.io/pypi/v/pythonnative" alt="PyPI Version" /></a>
   <a href="https://pypi.org/project/pythonnative/"><img src="https://img.shields.io/pypi/pyversions/pythonnative" alt="Python Versions" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/pypi/l/pythonnative" alt="License: MIT" /></a>
-  <a href="https://docs.pythonnative.com/"><img src="https://img.shields.io/website?url=https%3A%2F%2Fdocs.pythonnative.com&label=docs" alt="Docs" /></a>
+  <a href="https://pythonnative.com/"><img src="https://img.shields.io/website?url=https%3A%2F%2Fpythonnative.com&label=docs" alt="Docs" /></a>
 </p>
 
 <p align="center">
-  <a href="https://docs.pythonnative.com/">Documentation</a> ·
-  <a href="https://docs.pythonnative.com/getting-started/">Getting Started</a> ·
-  <a href="https://docs.pythonnative.com/examples/">Examples</a> ·
+  <a href="https://pythonnative.com/">Documentation</a> ·
+  <a href="https://pythonnative.com/getting-started/">Getting Started</a> ·
+  <a href="https://pythonnative.com/examples/">Examples</a> ·
   <a href="CONTRIBUTING.md">Contributing</a>
 </p>
 
@@ -31,19 +31,19 @@ PythonNative is a cross-platform toolkit for building native Android and iOS app
 ## Features
 
 - **Declarative UI:** Describe *what* your UI should look like with element functions (`Text`, `Button`, `Column`, `Row`, etc.). PythonNative creates and updates native views automatically.
-- **Rich component library:** 25+ built-in components backed by real native widgets — `TextInput`, `Image` / `ImageBackground`, `ScrollView`, `FlatList` / `SectionList`, `Modal`, `Pressable` / `TouchableOpacity`, `Switch` / `Checkbox`, `Slider`, `SegmentedControl`, `Picker`, `DatePicker`, `ProgressBar` / `ActivityIndicator`, `WebView`, and more.
-- **Device APIs:** Cross-platform modules for `Camera`, `Location`, `FileSystem`, `Notifications`, `Clipboard`, `Share`, `Linking`, `Permissions`, `AppState`, `NetInfo`, `SecureStore`, `Battery`, `Haptics` / `Vibration`, and `Biometrics` — plus reactive `use_app_state` and `use_net_info` hooks.
+- **Rich component library:** 25+ built-in components backed by real native widgets: `TextInput`, `Image` / `ImageBackground`, `ScrollView`, `FlatList` / `SectionList`, `Modal`, `Pressable` / `TouchableOpacity`, `Switch` / `Checkbox`, `Slider`, `SegmentedControl`, `Picker`, `DatePicker`, `ProgressBar` / `ActivityIndicator`, `WebView`, and more.
+- **Device APIs:** Cross-platform modules for `Camera`, `Location`, `FileSystem`, `Notifications`, `Clipboard`, `Share`, `Linking`, `Permissions`, `AppState`, `NetInfo`, `SecureStore`, `Battery`, `Haptics` / `Vibration`, and `Biometrics`, plus reactive `use_app_state` and `use_net_info` hooks.
 - **Hooks and function components:** Manage state with `use_state`, side effects with `use_effect`, and navigation with `use_navigation`, all through one consistent pattern.
 - **Typed `style` prop:** Pass all visual and layout properties through a single `style` dict, fully described by the `pn.Style` `TypedDict` and the ergonomic `pn.style(...)` helper for IDE autocomplete and static checking. Compose reusable styles with `StyleSheet`.
 - **Cross-platform flexbox engine:** A pure-Python, Yoga-style layout engine computes frames once and applies them to native views, so `flex`, `padding`, `aspect_ratio`, and `position: "absolute"` produce the same geometry on Android and iOS.
-- **Virtual view tree + reconciler:** Element trees are diffed and patched with minimal native mutations, similar to React's reconciliation. Each commit lands as **one batched transaction** of mutation ops, and event callbacks are routed through a tag-based registry so re-renders that only change closures cost zero native calls. State updates re-render **locally** — only the component whose state changed (and its subtree) re-runs, and unchanged leaves reuse cached intrinsic measurements — so deep UIs stay responsive instead of re-rendering the whole app from the root on every tap.
+- **Virtual view tree + reconciler:** Element trees are diffed and patched with minimal native mutations, similar to React's reconciliation. Each commit lands as **one batched transaction** of mutation ops, and event callbacks are routed through a tag-based registry so re-renders that only change closures cost zero native calls. State updates re-render **locally**: only the component whose state changed (and its subtree) re-runs, and unchanged leaves reuse cached intrinsic measurements, so deep UIs stay responsive instead of re-rendering the whole app from the root on every tap.
 - **Native-driven animations:** The `Animated` API (timing / spring / decay, awaitable or fire-and-forget) hands animations to Core Animation and `ViewPropertyAnimator` whenever possible, so no Python code runs per frame; a pure-Python ticker covers the rest.
-- **Native gesture system:** Attach `Tap`, `LongPress`, `Pan`, `Swipe`, `Pinch`, and `Rotation` recognizers to any view via the `gestures=` prop — backed by `UIGestureRecognizer` on iOS and a unit-testable pure-Python arbiter on Android and desktop.
-- **Virtualized lists:** `FlatList` / `SectionList` window their rows in Python over the platform scroll view — uniform, exact, or measured variable heights, grids, headers/footers, infinite scroll, and an imperative scroll controller, identical on every platform.
+- **Native gesture system:** Attach `Tap`, `LongPress`, `Pan`, `Swipe`, `Pinch`, and `Rotation` recognizers to any view via the `gestures=` prop, backed by `UIGestureRecognizer` on iOS and a unit-testable pure-Python arbiter on Android and desktop.
+- **Virtualized lists:** `FlatList` / `SectionList` window their rows in Python over the platform scroll view: uniform, exact, or measured variable heights, grids, headers/footers, infinite scroll, and an imperative scroll controller, identical on every platform.
 - **Direct native bindings:** Python calls platform APIs directly through Chaquopy and rubicon-objc, with no JavaScript bridge.
 - **Custom-component SDK:** Wrap any platform widget as a first-class element with type-checked props via `pythonnative.sdk` (`Props`, `@native_component`, `element_factory`). Plugins distributed on PyPI auto-register through the `pythonnative.handlers` entry-point group.
 - **CLI scaffolding:** `pn init` creates a ready-to-run project; `pn run android` and `pn run ios` build and launch your app.
-- **Instant desktop preview:** `pn preview` renders your app in a native desktop window via Tkinter with Fast Refresh on every save — iterate on layout, state, and navigation in milliseconds without booting a simulator or device. The reconciler, hooks, layout engine, and navigation are the same code that ships to the phone.
+- **Instant desktop preview:** `pn preview` renders your app in a native desktop window via Tkinter with Fast Refresh on every save: iterate on layout, state, and navigation in milliseconds without booting a simulator or device. The reconciler, hooks, layout engine, and navigation are the same code that ships to the phone.
 - **Native-backed navigation:** Declarative `Stack`, `Tab`, and `Drawer` navigators inspired by React Navigation. The root stack drives the platform's native navigation controller (`UINavigationController` on iOS, AndroidX Navigation Component on Android), so transitions, back gestures, and the hardware back button match what users expect.
 - **Fast Refresh hot reload:** `pn run --hot-reload` watches `app/` and patches edits into the running app on save, preserving component state across most changes.
 - **Bundled templates:** Android Gradle and iOS Xcode templates are included, so scaffolding requires no network access.
@@ -77,7 +77,7 @@ def App():
 
 ## Documentation
 
-Visit [docs.pythonnative.com](https://docs.pythonnative.com/) for the full documentation, including getting started guides, platform-specific instructions for Android and iOS, API reference, and working examples.
+Visit [pythonnative.com](https://pythonnative.com/) for the full documentation, including getting started guides, platform-specific instructions for Android and iOS, API reference, and working examples.
 
 ## Contributing
 

{pythonnative-0.22.0 → pythonnative-0.23.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythonnative"
-version = "0.22.0"
+version = "0.23.0"
 description = "Cross-platform native UI toolkit for Android and iOS"
 authors = [
   { name = "Owen Carey" }
@@ -66,7 +66,8 @@ pn = "pythonnative.cli.pn:main"
 Homepage = "https://github.com/pythonnative/pythonnative"
 Repository = "https://github.com/pythonnative/pythonnative"
 Issues = "https://github.com/pythonnative/pythonnative/issues"
-Documentation = "https://docs.pythonnative.com/"
+Documentation = "https://pythonnative.com/"
+
 
 
 
@@ -97,8 +98,6 @@ pythonnative = [
 target-version = "py39"
 line-length = 120
 extend-exclude = [
-  "experiments",
-  "apps",
   "templates",
   "docs",
 ]

{pythonnative-0.22.0 → pythonnative-0.23.0}/src/pythonnative/__init__.py

@@ -60,9 +60,9 @@ Example:
     ```
 """
 
-__version__ = "0.22.0"
+__version__ = "0.23.0"
 
-from . import gestures, runtime, sdk
+from . import appearance, gestures, images, runtime, sdk
 from .alerts import Alert
 from .animated import Animated, AnimatedValue, use_animated_value
 from .components import (
@@ -132,6 +132,7 @@ from .hooks import (
     memo,
     use_async_effect,
     use_callback,
+    use_color_scheme,
     use_context,
     use_effect,
     use_keyboard_height,
@@ -185,6 +186,8 @@ from .sdk import (
 )
 from .storage import AsyncStorage, use_persisted_state
 from .style import (
+    DEFAULT_DARK_THEME,
+    DEFAULT_LIGHT_THEME,
     AlignItems,
     AlignSelf,
     AutoCapitalize,
@@ -207,8 +210,10 @@ from .style import (
     TextDecoration,
     ThemeContext,
     TransformSpec,
+    default_theme,
     resolve_style,
     style,
+    use_theme,
 )
 
 __all__ = [
@@ -280,6 +285,7 @@ __all__ = [
     "QueryResult",
     "use_async_effect",
     "use_callback",
+    "use_color_scheme",
     "use_context",
     "use_effect",
     "use_focus_effect",
@@ -306,6 +312,8 @@ __all__ = [
     "AlignSelf",
     "AutoCapitalize",
     "Color",
+    "DEFAULT_DARK_THEME",
+    "DEFAULT_LIGHT_THEME",
     "Dimension",
     "EdgeInsets",
     "FlexDirection",
@@ -324,8 +332,14 @@ __all__ = [
     "TextDecoration",
     "ThemeContext",
     "TransformSpec",
+    "default_theme",
     "resolve_style",
     "style",
+    "use_theme",
+    # Appearance
+    "appearance",
+    # Image pipeline
+    "images",
     # Animation
     "Animated",
     "AnimatedValue",

{pythonnative-0.22.0 → pythonnative-0.23.0}/src/pythonnative/animated.py

@@ -24,7 +24,7 @@ native view the value is attached to
 
 - **Accepted** (iOS Core Animation, Android ``ViewPropertyAnimator`` /
   ``DynamicAnimation``): the platform animates the property entirely
-  natively — no Python code runs per frame. Python receives exactly one
+  natively; no Python code runs per frame. Python receives exactly one
   callback when the animation settles, updates the
   [`AnimatedValue`][pythonnative.animated.AnimatedValue], and resolves
   any awaiting tasks.
@@ -135,7 +135,7 @@ class AnimatedValue:
     Animated components (``Animated.View`` et al.) **attach** the value
     to ``(tag, prop)`` bindings after mount. Setting the value pushes
     the new number to every attached native view through the registry's
-    ``set_animated_property`` — and when an animation can be driven
+    ``set_animated_property``, and when an animation can be driven
     natively, the platform animates those same bindings directly.
 
     Python-side listeners registered via
@@ -217,7 +217,7 @@ class AnimatedValue:
     def add_listener(self, prop: str, callback: Callable[[float], None]) -> Callable[[], None]:
         """Register ``callback`` for Python-driven changes to this value.
 
-        Returns an unsubscribe callable. ``prop`` is metadata only — it
+        Returns an unsubscribe callable. ``prop`` is metadata only; it
         lets the subscriber differentiate this binding from others on
         the same ``AnimatedValue``.
         """
@@ -686,7 +686,7 @@ class _AnimationHandle(_AwaitableAnimation):
 
     Each ``.start()`` call snapshots the value's current state, prefers
     the native driver, and falls back to a fresh Python-ticked
-    animation otherwise (matches React Native — the ``Animated.timing``
+    animation otherwise (matches React Native: the ``Animated.timing``
     return value is reusable).
     """
 
@@ -780,7 +780,7 @@ class _CompositeAnimation(_AwaitableAnimation):
         if item is None:
             return
         # ``_AwaitableAnimation`` and plain awaitables/coroutines are
-        # both supported — lets users mix in ``asyncio.sleep``.
+        # both supported: lets users mix in ``asyncio.sleep``.
         await item
 
 
@@ -824,7 +824,7 @@ def _make_animated_factory(
 
         # ``@component`` packs positional children into the ``children``
         # prop (this function declares ``*args``), and the reconciler
-        # re-invokes it with keyword props only — so at render time the
+        # re-invokes it with keyword props only, so at render time the
         # payload arrives in ``kwargs``, never in ``args``.
         children = list(args) or list(kwargs.pop("children", ()) or ())
 

pythonnative-0.23.0/src/pythonnative/appearance.py

@@ -0,0 +1,124 @@
+"""System color-scheme (light / dark mode) tracking.
+
+The platform screen host publishes the operating system's current
+appearance here (Android: ``Configuration.uiMode``; iOS:
+``UITraitCollection.userInterfaceStyle``), and components read it back
+through [`use_color_scheme`][pythonnative.use_color_scheme] or
+[`use_theme`][pythonnative.use_theme], both of which re-render when
+the scheme changes.
+
+Apps can also *override* the scheme (e.g. an in-app appearance
+setting) with [`set_color_scheme`][pythonnative.appearance.set_color_scheme];
+the override wins over the system value until cleared with ``None``.
+
+Example:
+    >>> from pythonnative import appearance
+    >>> appearance.get_color_scheme()
+    'light'
+    >>> appearance.set_color_scheme("dark")   # app-level override
+    >>> appearance.get_color_scheme()
+    'dark'
+    >>> appearance.set_color_scheme(None)     # follow the system again
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Callable, List, Literal, Optional
+
+ColorScheme = Literal["light", "dark"]
+"""The two supported appearance values."""
+
+_system_scheme: str = "light"
+_override_scheme: Optional[str] = None
+
+_subscribers: List[Callable[[], None]] = []
+_subscribers_lock = threading.Lock()
+
+
+def _notify_subscribers() -> None:
+    """Invoke every registered subscriber, swallowing exceptions."""
+    with _subscribers_lock:
+        callbacks = list(_subscribers)
+    for cb in callbacks:
+        try:
+            cb()
+        except Exception:
+            pass
+
+
+def subscribe(callback: Callable[[], None]) -> Callable[[], None]:
+    """Register ``callback`` to fire whenever the effective scheme changes.
+
+    Returns an unsubscribe function. Threadsafe.
+    """
+    with _subscribers_lock:
+        _subscribers.append(callback)
+
+    def _unsub() -> None:
+        with _subscribers_lock:
+            try:
+                _subscribers.remove(callback)
+            except ValueError:
+                pass
+
+    return _unsub
+
+
+def _coerce(scheme: object) -> Optional[str]:
+    if scheme in ("light", "dark"):
+        return str(scheme)
+    return None
+
+
+def set_system_color_scheme(scheme: str) -> None:
+    """Publish the operating system's current scheme.
+
+    Called by the platform screen host on create/resume and whenever
+    the system reports an appearance change. Invalid values are
+    ignored. Subscribers are only notified when the *effective* scheme
+    (after any app override) actually changes.
+    """
+    global _system_scheme
+    coerced = _coerce(scheme)
+    if coerced is None or coerced == _system_scheme:
+        return
+    effective_before = get_color_scheme()
+    _system_scheme = coerced
+    if get_color_scheme() != effective_before:
+        _notify_subscribers()
+
+
+def set_color_scheme(scheme: Optional[str]) -> None:
+    """Set (or clear) the app-level scheme override.
+
+    Args:
+        scheme: ``"light"`` or ``"dark"`` to force that appearance
+            regardless of the system setting, or ``None`` to follow
+            the system again.
+    """
+    global _override_scheme
+    coerced = _coerce(scheme) if scheme is not None else None
+    if scheme is not None and coerced is None:
+        return
+    effective_before = get_color_scheme()
+    _override_scheme = coerced
+    if get_color_scheme() != effective_before:
+        _notify_subscribers()
+
+
+def get_color_scheme() -> str:
+    """Return the effective scheme: the app override if set, else the system value."""
+    return _override_scheme if _override_scheme is not None else _system_scheme
+
+
+def get_system_color_scheme() -> str:
+    """Return the system-reported scheme, ignoring any app override."""
+    return _system_scheme
+
+
+def reset_color_scheme() -> None:
+    """Reset to system ``"light"`` with no override. Intended for tests."""
+    global _system_scheme, _override_scheme
+    _system_scheme = "light"
+    _override_scheme = None

{pythonnative-0.22.0 → pythonnative-0.23.0}/src/pythonnative/cli/pn.py

@@ -5,7 +5,7 @@ The console script `pn` (declared in `pyproject.toml`) dispatches to:
 - `pn init [name]`: scaffold a new project (``pythonnative.toml`` + ``app/``).
 - `pn doctor [platform]`: diagnose the local toolchain and config.
 - `pn preview [component]`: render the app in a desktop (Tkinter) window
-  with Fast Refresh — the fast inner dev loop, no device required.
+  with Fast Refresh, the fast inner dev loop, no device required.
 - `pn run android|ios`: stage + build + install + launch on a device or
   simulator, with optional on-device hot reload.
 - `pn build android|ios`: produce standalone artifacts (signed APK/AAB,