pythonnative 0.22.1__py3-none-any.whl → 0.23.0__py3-none-any.whl

pythonnative/preview.py

@@ -43,6 +43,36 @@ _POLL_INTERVAL_MS = 16
 _WATCH_INTERVAL_S = 0.4
 
 
+def _publish_desktop_color_scheme() -> None:
+    """Publish the host OS appearance so `use_color_scheme` works in preview.
+
+    ``PN_COLOR_SCHEME=light|dark`` forces a value (handy for testing
+    both appearances); otherwise macOS is asked via ``defaults read``
+    (the key only exists when dark mode is on). Other platforms default
+    to light.
+    """
+    from . import appearance
+
+    forced = os.environ.get("PN_COLOR_SCHEME")
+    if forced in ("light", "dark"):
+        appearance.set_system_color_scheme(forced)
+        return
+    if sys.platform == "darwin":
+        import subprocess
+
+        try:
+            result = subprocess.run(
+                ["defaults", "read", "-g", "AppleInterfaceStyle"],
+                capture_output=True,
+                text=True,
+                timeout=2,
+            )
+            is_dark = result.returncode == 0 and result.stdout.strip() == "Dark"
+            appearance.set_system_color_scheme("dark" if is_dark else "light")
+        except Exception:
+            pass
+
+
 class DesktopApp:
     """Navigation-stack controller for the desktop preview window.
 
@@ -359,6 +389,7 @@ def run_preview(
         )
 
     root_dir, watched = _resolve_paths(component_path, project_root, watch_dir)
+    _publish_desktop_color_scheme()
 
     root = tk.Tk()
     root.title(title)

pythonnative/project/config.py

@@ -321,15 +321,7 @@ class AppConfig:
         root = Path(project_root) if project_root is not None else Path.cwd()
         config_path = root / CONFIG_FILENAME
         if not config_path.is_file():
-            legacy = root / "pythonnative.json"
-            hint = ""
-            if legacy.is_file():
-                hint = (
-                    "\nFound a legacy 'pythonnative.json'. PythonNative now uses "
-                    "'pythonnative.toml'.\nRun 'pn init --force' to scaffold one, then "
-                    "port your settings over."
-                )
-            raise ConfigError(f"No {CONFIG_FILENAME} found in {root}.{hint}")
+            raise ConfigError(f"No {CONFIG_FILENAME} found in {root}.")
         try:
             with open(config_path, "rb") as handle:
                 data = _toml.load(handle)

pythonnative/screen.py

@@ -678,6 +678,65 @@ if IS_ANDROID:
                 bottom_px / density,
                 right_px / density,
             )
+            # IME (soft keyboard) insets: API 30+ exposes them through
+            # the typed getInsets API. The keyboard overlaps the system
+            # navigation bar, so the visible keyboard height is the IME
+            # inset minus the permanent bottom bar inset. Older API
+            # levels don't report IME insets here; those devices rely
+            # on ``adjustResize`` shrinking the window (the viewport
+            # push handles the layout) and the height stays 0.
+            try:
+                ime = insets_obj.getInsets(Type.ime())
+                ime_px = max(0, int(ime.bottom) - bottom_px)
+                platform_metrics.set_keyboard_height(ime_px / density)
+            except Exception:
+                pass
+        except Exception:
+            pass
+
+    def _android_publish_color_scheme(activity: Any) -> None:
+        """Read the system night mode from the activity and publish it.
+
+        Android delivers appearance changes as a configuration change,
+        which recreates the activity by default, so publishing on
+        ``on_create`` / ``on_resume`` covers both the initial value and
+        subsequent flips.
+        """
+        try:
+            from . import appearance
+
+            Configuration = jclass("android.content.res.Configuration")
+            ui_mode = int(activity.getResources().getConfiguration().uiMode)
+            night = ui_mode & int(Configuration.UI_MODE_NIGHT_MASK)
+            is_dark = night == int(Configuration.UI_MODE_NIGHT_YES)
+            appearance.set_system_color_scheme("dark" if is_dark else "light")
+        except Exception:
+            pass
+
+    def _android_register_insets_listener(host: Any, view: Any) -> None:
+        """Re-publish insets whenever the window's insets change.
+
+        The ``OnLayoutChangeListener`` in ``_android_register_layout_listener``
+        only fires when the container is re-measured, which covers
+        ``adjustResize`` keyboards but not inset-only changes (e.g. an
+        edge-to-edge window where the IME floats over the content).
+        ``setOnApplyWindowInsetsListener`` fires on every insets pass,
+        so keyboard show/hide reaches ``platform_metrics`` immediately.
+        """
+        try:
+            View = jclass("android.view.View")
+
+            class _PNInsetsListener(dynamic_proxy(View.OnApplyWindowInsetsListener)):  # type: ignore[misc]
+                def onApplyWindowInsets(self, v: Any, insets: Any) -> Any:
+                    try:
+                        _android_publish_window_insets(v)
+                    except Exception:
+                        pass
+                    return insets
+
+            listener = _PNInsetsListener()
+            view.setOnApplyWindowInsetsListener(listener)
+            host._insets_listener = listener  # retain to prevent GC
         except Exception:
             pass
 
@@ -761,12 +820,14 @@ if IS_ANDROID:
             _init_host_common(self, component_path, component_func)
 
         def on_create(self) -> None:
+            _android_publish_color_scheme(self.native_instance)
             _on_create(self)
 
         def on_start(self) -> None:
             pass
 
         def on_resume(self) -> None:
+            _android_publish_color_scheme(self.native_instance)
             _set_host_focused(self, True)
 
         def on_layout(self) -> None:
@@ -873,6 +934,7 @@ if IS_ANDROID:
 
             if container is not None:
                 _android_register_layout_listener(self, container)
+                _android_register_insets_listener(self, container)
                 _android_push_initial_viewport(self, container)
 
         def _detach_root(self, native_view: Any) -> None:
@@ -1128,6 +1190,24 @@ else:
         except Exception:
             pass
 
+    def _ios_publish_color_scheme() -> None:
+        """Read the current UIKit interface style and publish it.
+
+        ``UITraitCollection.currentTraitCollection`` reflects the
+        active appearance; ``userInterfaceStyle`` is 1 for light and
+        2 for dark (0 = unspecified, treated as light). Called from
+        the lifecycle callbacks that fire on appearance flips
+        (``viewDidLayoutSubviews`` / ``viewDidAppear``).
+        """
+        try:
+            from . import appearance
+
+            UITraitCollection = ObjCClass("UITraitCollection")
+            style_value = int(UITraitCollection.currentTraitCollection.userInterfaceStyle)
+            appearance.set_system_color_scheme("dark" if style_value == 2 else "light")
+        except Exception:
+            pass
+
     def _ios_register_screen(vc_instance: Any, host_obj: Any) -> None:
         ptr = _objc_addr(vc_instance)
         if ptr is None:
@@ -1273,6 +1353,7 @@ else:
                     _ios_register_screen(self.native_instance, self)
 
             def on_create(self) -> None:
+                _ios_publish_color_scheme()
                 _on_create(self)
 
             def on_start(self) -> None:
@@ -1483,6 +1564,9 @@ else:
                 # insets are now valid (initial layout, rotation,
                 # multitasking, …). Re-sync the root frame and push the
                 # viewport so the layout engine matches the visible area.
+                # Appearance flips also trigger a layout pass, so the
+                # color scheme is re-published here too.
+                _ios_publish_color_scheme()
                 if self._root_native_view is None:
                     _log_pn("on_layout: no root_native_view yet, skipping")
                     return
@@ -1494,6 +1578,7 @@ else:
                 # ``viewDidAppear`` always follows ``viewDidLayoutSubviews``,
                 # but trigger one extra sync here for safety in case a
                 # template overrides the layout call without forwarding.
+                _ios_publish_color_scheme()
                 _set_host_focused(self, True)
                 if self._root_native_view is None:
                     _log_pn("on_resume: no root_native_view yet, skipping")

pythonnative/style.py

@@ -36,7 +36,7 @@ Example:
 
 from typing import Any, Dict, List, Literal, Optional, Tuple, TypedDict, Union
 
-from .hooks import Context, create_context
+from .hooks import Context, create_context, use_color_scheme, use_context
 
 # ======================================================================
 # Atomic value types
@@ -283,6 +283,14 @@ class Style(TypedDict, total=False):
     # --- Visual: borders ---
     border_width: float
     border_radius: float
+    border_top_width: float
+    border_right_width: float
+    border_bottom_width: float
+    border_left_width: float
+    border_top_color: Color
+    border_right_color: Color
+    border_bottom_color: Color
+    border_left_color: Color
 
     # --- Visual: typography ---
     font_size: float
@@ -481,6 +489,7 @@ DEFAULT_LIGHT_THEME: Dict[str, Any] = {
     "spacing_large": 16,
     "border_radius": 8,
 }
+"""Built-in light theme selected by [`use_theme`][pythonnative.use_theme]."""
 
 DEFAULT_DARK_THEME: Dict[str, Any] = {
     "primary_color": "#0A84FF",
@@ -500,17 +509,65 @@ DEFAULT_DARK_THEME: Dict[str, Any] = {
     "spacing_large": 16,
     "border_radius": 8,
 }
+"""Built-in dark theme selected by [`use_theme`][pythonnative.use_theme]."""
 
-ThemeContext: Context = create_context(DEFAULT_LIGHT_THEME)
-"""Default theme context populated with `DEFAULT_LIGHT_THEME`.
+_FOLLOW_SYSTEM_THEME = object()
+"""Sentinel default for `ThemeContext`: resolve from the color scheme."""
 
-Wrap a subtree in
+ThemeContext: Context = create_context(_FOLLOW_SYSTEM_THEME)
+"""Theme context that follows the system color scheme by default.
+
+Without a provider, [`use_theme`][pythonnative.use_theme] resolves to
+[`DEFAULT_LIGHT_THEME`][pythonnative.style.DEFAULT_LIGHT_THEME] or
+[`DEFAULT_DARK_THEME`][pythonnative.style.DEFAULT_DARK_THEME] based on
+the current appearance. Wrap a subtree in
 [`Provider(ThemeContext, my_theme, ...)`][pythonnative.Provider] to
-override the theme for that subtree, then read it inside descendants
-via [`use_context(ThemeContext)`][pythonnative.use_context].
+pin an explicit theme for that subtree, then read it inside
+descendants via [`use_theme`][pythonnative.use_theme] (or
+[`use_context(ThemeContext)`][pythonnative.use_context]).
 """
 
 
+def default_theme(scheme: str) -> Dict[str, Any]:
+    """Return the built-in theme dict for ``scheme`` (``"light"`` / ``"dark"``)."""
+    return DEFAULT_DARK_THEME if scheme == "dark" else DEFAULT_LIGHT_THEME
+
+
+def use_theme() -> Dict[str, Any]:
+    """Return the active theme, following the system appearance by default.
+
+    If an ancestor mounted a ``Provider(ThemeContext, ...)``, that
+    theme is returned as-is. Otherwise the built-in light or dark
+    theme is selected from the effective color scheme (via
+    [`use_color_scheme`][pythonnative.use_color_scheme], so the
+    component re-renders when the system appearance flips).
+
+    Returns:
+        The active theme dict.
+
+    Raises:
+        RuntimeError: If called outside a `@component` function.
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+        @pn.component
+        def Card():
+            theme = pn.use_theme()
+            return pn.View(
+                pn.Text("Hello", style=pn.style(color=theme["text_color"])),
+                style=pn.style(background_color=theme["surface_color"]),
+            )
+        ```
+    """
+    scheme = use_color_scheme()
+    theme = use_context(ThemeContext)
+    if theme is _FOLLOW_SYSTEM_THEME:
+        return default_theme(scheme)
+    return theme
+
+
 __all__ = [
     "AlignItems",
     "AlignSelf",
@@ -543,6 +600,8 @@ __all__ = [
     "TransformScaleY",
     "TransformSpec",
     "TransformTranslate",
+    "default_theme",
     "resolve_style",
     "style",
+    "use_theme",
 ]

pythonnative/templates/android_template/app/src/main/AndroidManifest.xml

@@ -14,7 +14,8 @@
         tools:targetApi="31">
         <activity
             android:name=".MainActivity"
-            android:exported="true">
+            android:exported="true"
+            android:windowSoftInputMode="adjustResize">
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />
 

pythonnative/templates/android_template/app/src/main/java/com/pythonnative/android_template/PNAccessibilityDelegate.kt

@@ -0,0 +1,47 @@
+package com.pythonnative.android_template
+
+import android.os.Build
+import android.view.View
+import android.view.accessibility.AccessibilityNodeInfo
+
+/**
+ * Accessibility delegate that exposes PythonNative's `test_id` and
+ * `accessibility_state` props through the Android accessibility tree.
+ *
+ * `test_id` is surfaced as the node's view-id resource name, which
+ * UI Automator-based tools (Maestro, UiAutomator2, Appium) match as
+ * `resource-id`. State flags map onto the closest
+ * [AccessibilityNodeInfo] equivalents so TalkBack announces them.
+ *
+ * Instances are created and configured from Python (the Android view
+ * handlers); fields left null are not applied.
+ */
+class PNAccessibilityDelegate : View.AccessibilityDelegate() {
+    var testId: String? = null
+    var stateDisabled: Boolean? = null
+    var stateSelected: Boolean? = null
+    var stateChecked: Boolean? = null
+    var stateBusy: Boolean? = null
+    var stateExpanded: Boolean? = null
+
+    override fun onInitializeAccessibilityNodeInfo(host: View, info: AccessibilityNodeInfo) {
+        super.onInitializeAccessibilityNodeInfo(host, info)
+        testId?.let { info.viewIdResourceName = it }
+        stateDisabled?.let { info.isEnabled = !it }
+        stateSelected?.let { info.isSelected = it }
+        stateChecked?.let {
+            info.isCheckable = true
+            info.isChecked = it
+        }
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            val states = mutableListOf<String>()
+            if (stateBusy == true) states.add("busy")
+            when (stateExpanded) {
+                true -> states.add("expanded")
+                false -> states.add("collapsed")
+                null -> {}
+            }
+            if (states.isNotEmpty()) info.stateDescription = states.joinToString(", ")
+        }
+    }
+}

pythonnative/templates/android_template/app/src/main/java/com/pythonnative/android_template/PNBorderDrawable.kt

@@ -0,0 +1,67 @@
+package com.pythonnative.android_template
+
+import android.graphics.Canvas
+import android.graphics.ColorFilter
+import android.graphics.Paint
+import android.graphics.PixelFormat
+import android.graphics.RectF
+import android.graphics.drawable.Drawable
+
+/**
+ * Background drawable that renders an optional rounded fill plus four
+ * independent border strips. Used for PythonNative's
+ * `border_<side>_width` / `border_<side>_color` style props, which
+ * `GradientDrawable`'s single uniform stroke cannot express.
+ *
+ * Widths are in pixels; sides are ordered left, top, right, bottom.
+ */
+class PNBorderDrawable(
+    private val hasBackground: Boolean,
+    private val backgroundColor: Int,
+    private val cornerRadius: Float,
+    private val widths: FloatArray,
+    private val colors: IntArray,
+) : Drawable() {
+    private val paint = Paint(Paint.ANTI_ALIAS_FLAG)
+
+    override fun draw(canvas: Canvas) {
+        val b = RectF(bounds)
+        if (hasBackground) {
+            paint.style = Paint.Style.FILL
+            paint.color = backgroundColor
+            if (cornerRadius > 0f) {
+                canvas.drawRoundRect(b, cornerRadius, cornerRadius, paint)
+            } else {
+                canvas.drawRect(b, paint)
+            }
+        }
+        paint.style = Paint.Style.FILL
+        if (widths[0] > 0f) {
+            paint.color = colors[0]
+            canvas.drawRect(b.left, b.top, b.left + widths[0], b.bottom, paint)
+        }
+        if (widths[1] > 0f) {
+            paint.color = colors[1]
+            canvas.drawRect(b.left, b.top, b.right, b.top + widths[1], paint)
+        }
+        if (widths[2] > 0f) {
+            paint.color = colors[2]
+            canvas.drawRect(b.right - widths[2], b.top, b.right, b.bottom, paint)
+        }
+        if (widths[3] > 0f) {
+            paint.color = colors[3]
+            canvas.drawRect(b.left, b.bottom - widths[3], b.right, b.bottom, paint)
+        }
+    }
+
+    override fun setAlpha(alpha: Int) {
+        paint.alpha = alpha
+    }
+
+    override fun setColorFilter(colorFilter: ColorFilter?) {
+        paint.colorFilter = colorFilter
+    }
+
+    @Deprecated("Deprecated in Java")
+    override fun getOpacity(): Int = PixelFormat.TRANSLUCENT
+}

pythonnative/templates/android_template/app/src/main/java/com/pythonnative/android_template/PNVirtualListView.java

@@ -0,0 +1,172 @@
+package com.pythonnative.android_template;
+
+import android.content.Context;
+import android.util.TypedValue;
+import android.view.ViewGroup;
+import android.widget.FrameLayout;
+
+import androidx.annotation.NonNull;
+import androidx.recyclerview.widget.LinearLayoutManager;
+import androidx.recyclerview.widget.RecyclerView;
+
+/**
+ * RecyclerView-backed virtualized list used by PythonNative's Android bridge.
+ *
+ * <p>Chaquopy can proxy Java interfaces from Python, but it can't subclass Java
+ * abstract classes such as RecyclerView.Adapter or RecyclerView.ViewHolder. This
+ * helper owns those abstract-class implementations in Java and delegates row
+ * content back to Python through the small Delegate interface below.</p>
+ *
+ * <p>Rows may have per-position heights (section lists interleave headers and
+ * items); the delegate reports each row's height in dp. Scroll changes are
+ * forwarded to the delegate in dp so the Python side can drive on_scroll,
+ * on_end_reached, and viewability callbacks with one code path per platform.</p>
+ */
+public class PNVirtualListView extends RecyclerView {
+    public interface Delegate {
+        int getCount();
+
+        float getRowHeightDp(int position);
+
+        void mountRow(int position, FrameLayout container, float widthDp, float heightDp);
+
+        void onRowPress(int position);
+
+        void onRowRecycled(FrameLayout container);
+
+        void onScrolled(float offsetDp, float extentDp, float rangeDp);
+    }
+
+    private final float density;
+    private final RowAdapter rowAdapter;
+    private Delegate delegate;
+
+    public PNVirtualListView(@NonNull Context context, @NonNull Delegate delegate) {
+        super(context);
+        this.delegate = delegate;
+        this.density = context.getResources().getDisplayMetrics().density;
+        setLayoutManager(new LinearLayoutManager(context));
+        rowAdapter = new RowAdapter();
+        setAdapter(rowAdapter);
+        addOnScrollListener(new OnScrollListener() {
+            @Override
+            public void onScrolled(@NonNull RecyclerView rv, int dx, int dy) {
+                PNVirtualListView.this.delegate.onScrolled(
+                    rv.computeVerticalScrollOffset() / PNVirtualListView.this.density,
+                    rv.computeVerticalScrollExtent() / PNVirtualListView.this.density,
+                    rv.computeVerticalScrollRange() / PNVirtualListView.this.density
+                );
+            }
+        });
+    }
+
+    public void setDelegate(@NonNull Delegate delegate) {
+        this.delegate = delegate;
+        rowAdapter.notifyDataSetChanged();
+    }
+
+    public void notifyDataChanged() {
+        rowAdapter.notifyDataSetChanged();
+    }
+
+    public void scrollToOffsetDp(float offsetDp, boolean animated) {
+        int targetPx = Math.round(offsetDp * density);
+        int currentPx = computeVerticalScrollOffset();
+        if (animated) {
+            smoothScrollBy(0, targetPx - currentPx);
+        } else {
+            scrollBy(0, targetPx - currentPx);
+        }
+    }
+
+    public void scrollToIndex(int position, boolean animated) {
+        int clamped = Math.max(0, Math.min(position, Math.max(0, delegate.getCount() - 1)));
+        if (animated) {
+            smoothScrollToPosition(clamped);
+        } else {
+            scrollToPosition(clamped);
+        }
+    }
+
+    private int rowHeightPx(int position) {
+        return Math.max(
+            1,
+            Math.round(TypedValue.applyDimension(
+                TypedValue.COMPLEX_UNIT_DIP,
+                delegate.getRowHeightDp(position),
+                getResources().getDisplayMetrics()
+            ))
+        );
+    }
+
+    private float currentWidthDp(FrameLayout container) {
+        int widthPx = container.getWidth();
+        if (widthPx <= 0) {
+            widthPx = getWidth();
+        }
+        if (widthPx <= 0) {
+            widthPx = getResources().getDisplayMetrics().widthPixels;
+        }
+        return widthPx / density;
+    }
+
+    private class RowHolder extends RecyclerView.ViewHolder {
+        final FrameLayout container;
+
+        RowHolder(@NonNull FrameLayout container) {
+            super(container);
+            this.container = container;
+        }
+    }
+
+    private class RowAdapter extends RecyclerView.Adapter<RowHolder> {
+        @Override
+        public int getItemCount() {
+            return delegate.getCount();
+        }
+
+        @NonNull
+        @Override
+        public RowHolder onCreateViewHolder(@NonNull ViewGroup parent, int viewType) {
+            FrameLayout container = new FrameLayout(parent.getContext());
+            container.setLayoutParams(
+                new RecyclerView.LayoutParams(
+                    ViewGroup.LayoutParams.MATCH_PARENT,
+                    ViewGroup.LayoutParams.WRAP_CONTENT
+                )
+            );
+            return new RowHolder(container);
+        }
+
+        @Override
+        public void onBindViewHolder(@NonNull RowHolder holder, int position) {
+            RecyclerView.LayoutParams params = (RecyclerView.LayoutParams) holder.container.getLayoutParams();
+            int heightPx = rowHeightPx(position);
+            if (params.height != heightPx) {
+                params.height = heightPx;
+                holder.container.setLayoutParams(params);
+            }
+            holder.container.removeAllViews();
+            holder.container.setOnClickListener(v -> {
+                int pos = holder.getBindingAdapterPosition();
+                if (pos != RecyclerView.NO_POSITION) {
+                    delegate.onRowPress(pos);
+                }
+            });
+            delegate.mountRow(
+                position,
+                holder.container,
+                currentWidthDp(holder.container),
+                delegate.getRowHeightDp(position)
+            );
+        }
+
+        @Override
+        public void onViewRecycled(@NonNull RowHolder holder) {
+            holder.container.removeAllViews();
+            holder.container.setOnClickListener(null);
+            delegate.onRowRecycled(holder.container);
+            super.onViewRecycled(holder);
+        }
+    }
+}