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

pythonnative/storage.py

@@ -321,7 +321,7 @@ class AsyncStorage:
         """Return the JSON-decoded value stored at ``key``, or ``None``.
 
         If the stored value isn't valid JSON, returns ``None`` rather
-        than raising — assume the entry was written by another
+        than raising; assume the entry was written by another
         process or an older version of the app.
         """
         raw = await AsyncStorage.get(key)
@@ -347,7 +347,7 @@ def use_persisted_state(
     Backed by [`AsyncStorage`][pythonnative.storage.AsyncStorage]:
     behaves like ``use_state`` but loads the prior value (if any) on
     mount and persists every subsequent update. Until the load
-    completes the value is ``initial`` — the same fallback React
+    completes the value is ``initial``, the same fallback React
     Native users get with ``AsyncStorage.getItem``.
 
     The setter accepts either a value or a ``current -> new``
@@ -362,7 +362,7 @@ def use_persisted_state(
         initial: Value used before the first load completes.
 
     Returns:
-        ``(value, setter)`` — same shape as
+        ``(value, setter)``, same shape as
         [`use_state`][pythonnative.use_state].
 
     Example:

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
@@ -208,7 +208,7 @@ class Style(TypedDict, total=False):
     [`Literal`][typing.Literal]. ``Style`` is a `total=False` TypedDict
     so any subset of keys is valid at construction time.
 
-    Custom native components may accept additional, unlisted keys —
+    Custom native components may accept additional, unlisted keys;
     they are ignored by the built-in handlers but flow through the
     reconciler unmodified, so third-party handlers can read them.
 
@@ -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);
+        }
+    }
+}

pythonnative/templates/ios_template/ios_template.xcodeproj/project.pbxproj

@@ -253,8 +253,8 @@
 			isa = XCRemoteSwiftPackageReference;
 			repositoryURL = "https://github.com/pvieito/PythonKit";
 			requirement = {
-				branch = master;
-				kind = branch;
+				kind = upToNextMinorVersion;
+				minimumVersion = 0.5.1;
 			};
 		};
 /* End XCRemoteSwiftPackageReference section */

pythonnative/templates/ios_template/ios_templateUITests/ios_templateUITests.swift

@@ -15,7 +15,7 @@ final class ios_templateUITests: XCTestCase {
         // In UI tests it is usually best to stop immediately when a failure occurs.
         continueAfterFailure = false
 
-        // In UI tests it’s important to set the initial state - such as interface orientation - required for your tests before they run. The setUp method is a good place to do this.
+        // In UI tests it's important to set the initial state - such as interface orientation - required for your tests before they run. The setUp method is a good place to do this.
     }
 
     override func tearDownWithError() throws {

pythonnative/virtual_rows.py

@@ -0,0 +1,137 @@
+"""Row subtrees for natively virtualized lists.
+
+Native virtualized lists (Android ``RecyclerView`` via
+``PNVirtualListView``, iOS ``UITableView``) own row lifecycle on the
+platform side: the platform decides when a row enters the viewport,
+hands PythonNative an empty native container, and recycles that
+container when the row scrolls away.
+
+Each visible row hosts a full PythonNative subtree driven by its own
+nested [`Reconciler`][pythonnative.reconciler.Reconciler]. The
+[`RowSubtree`][pythonnative.virtual_rows.RowSubtree] class wraps that
+per-row reconciler: it mounts the row element into fresh native views,
+re-reconciles in place when the platform rebinds the same container to
+a different row index (recycling), and tears everything down when the
+list is destroyed.
+
+State inside rows works: hooks like ``use_state`` mark the row's own
+reconciler dirty and a guarded flush re-renders just that row.
+"""
+
+from typing import Any, Callable, Dict
+
+from .element import Element
+
+__all__ = ["RowSubtree", "RowHostPool"]
+
+
+class RowSubtree:
+    """One list row's mounted PythonNative subtree.
+
+    Owns a nested reconciler whose viewport is the row's cell size.
+    The native root view produced by
+    [`mount`][pythonnative.virtual_rows.RowSubtree.mount] is what the
+    platform handler attaches to the recycled cell container.
+    """
+
+    def __init__(self) -> None:
+        from .native_views import get_registry
+        from .reconciler import Reconciler
+
+        self._reconciler = Reconciler(get_registry())
+        # Guarded synchronous flush so ``use_state`` inside a row
+        # re-renders the row. Re-entrant requests (a setter firing
+        # during the flush itself) are queued and drained after.
+        self._flushing = False
+        self._flush_queued = False
+        self._reconciler._screen_re_render = self._request_flush
+        self.native_root: Any = None
+
+    def _request_flush(self) -> None:
+        if self._flushing:
+            self._flush_queued = True
+            return
+        self._flushing = True
+        try:
+            for _ in range(8):
+                self._flush_queued = False
+                self.native_root = self._reconciler.flush_dirty()
+                if not self._flush_queued:
+                    break
+        finally:
+            self._flushing = False
+
+    def mount(self, element: Element, width: float, height: float) -> Any:
+        """Mount ``element`` at the given cell size; returns the native root."""
+        self.native_root = self._reconciler.mount(element)
+        self._reconciler.set_viewport_size(float(width), float(height))
+        return self.native_root
+
+    def rebind(self, element: Element, width: float, height: float) -> Any:
+        """Reconcile the subtree to ``element`` (cell recycled to a new row).
+
+        Cheaper than unmount + mount when consecutive rows share a
+        shape, which is the overwhelmingly common case in lists.
+        Returns the (possibly replaced) native root.
+        """
+        self._reconciler.set_viewport_size(float(width), float(height))
+        self.native_root = self._reconciler.reconcile(element)
+        return self.native_root
+
+    def unmount(self) -> None:
+        """Destroy the subtree and release its native views."""
+        try:
+            self._reconciler.unmount()
+        except Exception:
+            pass
+        self.native_root = None
+
+
+class RowHostPool:
+    """Per-list bookkeeping of row subtrees keyed by native container.
+
+    Platform handlers create one pool per virtualized list view. Keys
+    are platform-stable container identities (Java identity hash on
+    Android, ``contentView`` pointer on iOS).
+    """
+
+    def __init__(self) -> None:
+        self._subtrees: Dict[int, RowSubtree] = {}
+
+    def bind(
+        self,
+        container_key: int,
+        make_element: Callable[[], Element],
+        width: float,
+        height: float,
+    ) -> Any:
+        """Mount or rebind the subtree for ``container_key``.
+
+        Returns the subtree's native root. The caller must (re)attach
+        it to the container: platforms strip a recycled cell's
+        children before rebinding, so even an unchanged root needs
+        re-attachment.
+        """
+        element = make_element()
+        subtree = self._subtrees.get(container_key)
+        if subtree is None:
+            subtree = RowSubtree()
+            self._subtrees[container_key] = subtree
+            return subtree.mount(element, width, height)
+        return subtree.rebind(element, width, height)
+
+    def release(self, container_key: int) -> None:
+        """Unmount the subtree for one recycled container, if any."""
+        subtree = self._subtrees.pop(container_key, None)
+        if subtree is not None:
+            subtree.unmount()
+
+    def release_all(self) -> None:
+        """Unmount every subtree (list destroyed)."""
+        subtrees = list(self._subtrees.values())
+        self._subtrees.clear()
+        for subtree in subtrees:
+            subtree.unmount()
+
+    def __len__(self) -> int:
+        return len(self._subtrees)