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

pythonnative/style.py

@@ -34,9 +34,11 @@ Example:
     ```
 """
 
+import difflib
 from typing import Any, Dict, List, Literal, Optional, Tuple, TypedDict, Union
 
-from .hooks import Context, create_context
+from . import diagnostics
+from .hooks import Context, create_context, use_color_scheme, use_context
 
 # ======================================================================
 # Atomic value types
@@ -74,6 +76,30 @@ EdgeValue = Union[Dimension, EdgeInsets]
 [`EdgeInsets`][pythonnative.EdgeInsets] dict."""
 
 
+class AccessibilityState(TypedDict, total=False):
+    """Current widget state exposed to assistive technology.
+
+    Passed via the ``accessibility_state=`` prop on interactive
+    components. All keys are optional; omitted keys are treated as
+    unset (not ``False``).
+
+    Attributes:
+        disabled: The widget is visible but not interactive.
+        selected: The widget is currently selected (e.g. the active
+            tab).
+        checked: Toggle/checkbox state. ``"mixed"`` represents a
+            tri-state checkbox.
+        busy: The widget is loading or otherwise temporarily busy.
+        expanded: A disclosure/accordion is currently expanded.
+    """
+
+    disabled: bool
+    selected: bool
+    checked: Union[bool, Literal["mixed"]]
+    busy: bool
+    expanded: bool
+
+
 class ShadowOffset(TypedDict):
     """Shadow displacement in points."""
 
@@ -136,6 +162,17 @@ TransformSpec = Union[TransformEntry, List[TransformEntry]]
 # ----------------------------------------------------------------------
 
 FlexDirection = Literal["row", "column", "row_reverse", "column_reverse"]
+FlexWrap = Literal["nowrap", "wrap", "wrap_reverse"]
+AlignContent = Literal[
+    "flex_start",
+    "center",
+    "flex_end",
+    "stretch",
+    "space_between",
+    "space_around",
+    "space_evenly",
+]
+LayoutDirection = Literal["ltr", "rtl"]
 JustifyContent = Literal[
     "flex_start",
     "center",
@@ -241,9 +278,12 @@ class Style(TypedDict, total=False):
     flex_shrink: float
     flex_basis: Dimension
     flex_direction: FlexDirection
+    flex_wrap: FlexWrap
     justify_content: JustifyContent
     align_items: AlignItems
     align_self: AlignSelf
+    align_content: AlignContent
+    direction: LayoutDirection
 
     # --- Layout: position ---
     position: Position
@@ -251,6 +291,8 @@ class Style(TypedDict, total=False):
     right: Dimension
     bottom: Dimension
     left: Dimension
+    start: Dimension
+    end: Dimension
 
     # --- Layout: spacing ---
     padding: EdgeValue
@@ -258,6 +300,8 @@ class Style(TypedDict, total=False):
     padding_bottom: Dimension
     padding_left: Dimension
     padding_right: Dimension
+    padding_start: Dimension
+    padding_end: Dimension
     padding_horizontal: Dimension
     padding_vertical: Dimension
     margin: EdgeValue
@@ -265,10 +309,14 @@ class Style(TypedDict, total=False):
     margin_bottom: Dimension
     margin_left: Dimension
     margin_right: Dimension
+    margin_start: Dimension
+    margin_end: Dimension
     margin_horizontal: Dimension
     margin_vertical: Dimension
     spacing: float
     gap: float
+    row_gap: float
+    column_gap: float
 
     # --- Visual: clipping & overflow ---
     overflow: Overflow
@@ -283,6 +331,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
@@ -370,6 +426,40 @@ def resolve_style(value: StyleProp) -> Dict[str, Any]:
     return result
 
 
+_KNOWN_STYLE_KEYS = frozenset(Style.__annotations__)
+"""Every key declared on the [`Style`][pythonnative.Style] TypedDict."""
+
+
+def validate_style_keys(style_dict: Dict[str, Any], owner: str = "") -> None:
+    """Warn (once per key) about style keys no built-in handler reads.
+
+    Dev-mode only; production skips the scan entirely. Typos get a
+    "did you mean" suggestion via fuzzy matching against the declared
+    [`Style`][pythonnative.Style] keys. Unknown keys still flow through
+    to handlers untouched, so custom components that read extra keys
+    keep working (at the cost of one dev warning).
+
+    Args:
+        style_dict: The flattened style dict about to be merged into an
+            element's props.
+        owner: Element type name for the warning message (e.g.
+            ``"Text"``).
+    """
+    if not diagnostics.is_dev() or not style_dict:
+        return
+    for key in style_dict:
+        if key in _KNOWN_STYLE_KEYS:
+            continue
+        matches = difflib.get_close_matches(str(key), _KNOWN_STYLE_KEYS, n=1)
+        hint = f" Did you mean {matches[0]!r}?" if matches else ""
+        diagnostics.warn_once(
+            f"Unknown style key {key!r}"
+            + (f" on {owner}" if owner else "")
+            + f".{hint} Built-in components ignore keys they don't recognize.",
+            key=f"style:{owner}:{key}",
+        )
+
+
 # ======================================================================
 # StyleSheet
 # ======================================================================
@@ -481,6 +571,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 +591,65 @@ DEFAULT_DARK_THEME: Dict[str, Any] = {
     "spacing_large": 16,
     "border_radius": 8,
 }
+"""Built-in dark theme selected by [`use_theme`][pythonnative.use_theme]."""
+
+_FOLLOW_SYSTEM_THEME = object()
+"""Sentinel default for `ThemeContext`: resolve from the color scheme."""
 
-ThemeContext: Context = create_context(DEFAULT_LIGHT_THEME)
-"""Default theme context populated with `DEFAULT_LIGHT_THEME`.
+ThemeContext: Context = create_context(_FOLLOW_SYSTEM_THEME)
+"""Theme context that follows the system color scheme by default.
 
-Wrap a subtree in
+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 +682,9 @@ __all__ = [
     "TransformScaleY",
     "TransformSpec",
     "TransformTranslate",
+    "default_theme",
     "resolve_style",
     "style",
+    "use_theme",
+    "validate_style_keys",
 ]

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/android_template/app/src/main/java/com/pythonnative/android_template/ScreenFragment.kt

@@ -8,6 +8,7 @@ import android.view.LayoutInflater
 import android.view.View
 import android.view.ViewGroup
 import android.widget.FrameLayout
+import androidx.activity.OnBackPressedCallback
 import androidx.core.os.bundleOf
 import androidx.fragment.app.Fragment
 import com.chaquo.python.PyObject
@@ -54,6 +55,27 @@ class ScreenFragment : Fragment() {
         } catch (e: Exception) {
             Log.e(TAG, "Failed to instantiate screen", e)
         }
+
+        // Offer the system back action to Python (`use_back_handler`)
+        // before running the default pop/finish behavior.
+        requireActivity().onBackPressedDispatcher.addCallback(
+            this,
+            object : OnBackPressedCallback(true) {
+                override fun handleOnBackPressed() {
+                    val consumed = try {
+                        screen?.callAttr("on_back_pressed")?.toBoolean() ?: false
+                    } catch (e: Exception) {
+                        Log.w(TAG, "on_back_pressed failed", e)
+                        false
+                    }
+                    if (!consumed) {
+                        isEnabled = false
+                        requireActivity().onBackPressedDispatcher.onBackPressed()
+                        isEnabled = true
+                    }
+                }
+            }
+        )
     }
 
     override fun onCreateView(