pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/suspense.py

@@ -0,0 +1,183 @@
+"""Suspense resources backed by standard asyncio tasks."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from typing import Any, Callable, Generic, Optional, Tuple, TypeVar
+
+T = TypeVar("T")
+
+_UNSET = object()
+
+
+class Suspend(BaseException):
+    """Signal that a render is blocked on pending async work.
+
+    Raised while a component renders, either by
+    [`Resource.read`][pythonnative.suspense.Resource.read] or by an
+    ``async def`` component body blocking on a pending await. The
+    reconciler catches it: the nearest
+    [`Suspense`][pythonnative.Suspense] boundary shows its fallback
+    (initial mounts), or the component keeps its previous content and
+    re-renders when the work finishes (updates).
+
+    Derives from :class:`BaseException` so
+    [`ErrorBoundary`][pythonnative.ErrorBoundary] (which catches
+    :class:`Exception`) never mistakes a suspension for a crash.
+
+    Attributes:
+        waitable: The pending work; exposes ``done()`` and
+            ``add_done_callback(cb)``.
+        hook_state: The suspended component's hook state, carried so
+            a Suspense boundary can preserve it across retries (its
+            cached resources survive, so the retry doesn't refetch).
+        key: ``(component identity, element key)`` used to re-match
+            ``hook_state`` on retry.
+        label: Component name for diagnostics.
+    """
+
+    def __init__(self, waitable: Any, hook_state: Any = None, label: str = "") -> None:
+        super().__init__(label or "render suspended")
+        self.waitable = waitable
+        self.hook_state = hook_state
+        self.key: Optional[Tuple[int, Any]] = None
+        self.label = label
+
+
+class Resource(Generic[T]):
+    """A cached async value with Suspense integration.
+
+    Returned by [`use_resource`][pythonnative.use_resource]. A resource
+    starts fetching as soon as the hook runs and remembers its result
+    across renders (until its dependencies change), so re-renders never
+    refetch.
+
+    Two ways to consume it:
+
+    - ``resource.read()`` in a regular component: returns the value
+      when ready, re-raises the fetcher's error if it failed, and
+      **suspends the render** while pending.
+    - ``await resource`` in an ``async def`` component: same
+      semantics, expressed as a plain await.
+    """
+
+    __slots__ = ("_driver",)
+
+    def __init__(self, driver: asyncio.Future[T]) -> None:
+        self._driver = driver
+
+    @property
+    def ready(self) -> bool:
+        """Whether the fetch has finished (successfully or not)."""
+        return self._driver.done()
+
+    def read(self) -> T:
+        """Return the fetched value, or suspend the render while pending.
+
+        Raises:
+            Suspend: While the fetch is still in flight (caught by the
+                reconciler, never by user code).
+            BaseException: Whatever the fetcher raised, re-raised so an
+                enclosing [`ErrorBoundary`][pythonnative.ErrorBoundary]
+                can catch it.
+        """
+        driver = self._driver
+        if driver.done():
+            return driver.result()
+        raise Suspend(driver, label="Resource.read")
+
+    def __await__(self) -> Any:
+        # One consumer's cancellation must not cancel a shared resource.
+        return asyncio.shield(self._driver).__await__()
+
+    def cancel(self) -> None:
+        """Cancel the in-flight fetch (no-op when already done)."""
+        self._driver.cancel()
+
+
+def start_resource(fetcher: Callable[[], Any]) -> Resource[Any]:
+    """Start ``fetcher`` immediately and wrap it in a [`Resource`][pythonnative.Resource].
+
+    The fetcher may be an ``async def`` (typical) or a plain function;
+    synchronous results resolve the resource immediately, so reading
+    it never suspends.
+
+    This is the non-hook constructor used for module-level resources
+    (preloading data before a screen mounts) and by
+    [`lazy`][pythonnative.lazy]. Inside components, prefer
+    [`use_resource`][pythonnative.use_resource], which caches per
+    component instance and re-fetches when dependencies change.
+    """
+    from .runtime import get_loop, run_async
+
+    try:
+        value = fetcher()
+    except Exception as exc:
+        future = get_loop().create_future()
+        future.set_exception(exc)
+        return Resource(future)
+    if inspect.isawaitable(value):
+        return Resource(run_async(value))
+    future = get_loop().create_future()
+    future.set_result(value)
+    return Resource(future)
+
+
+def lazy(loader: Callable[[], Any]) -> Callable[..., Any]:
+    """Define a component that loads its implementation on first render.
+
+    ``loader`` runs once, the first time the returned component
+    renders; until it resolves, renders suspend (so wrap usages in a
+    [`Suspense`][pythonnative.Suspense] boundary to show a loading
+    state). The loaded value must be a component (a ``@component``
+    function or any element factory).
+
+    Args:
+        loader: A zero-arg callable returning the component, or an
+            ``async def`` resolving to it. Synchronous loaders (a
+            deferred ``import``) resolve immediately and never
+            suspend.
+
+    Returns:
+        A component. Props (and children) pass through to the loaded
+        component unchanged.
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+        Chart = pn.lazy(lambda: __import__("app.chart", fromlist=["Chart"]).Chart)
+
+        @pn.component
+        def Dashboard():
+            return pn.Suspense(
+                Chart(points=[1, 2, 3]),
+                fallback=pn.ActivityIndicator(),
+            )
+        ```
+    """
+    from .component import Component
+
+    state: dict = {}
+
+    def Lazy(*children: Any, **props: Any) -> Any:
+        resource = state.get("resource")
+        if resource is None:
+            resource = start_resource(loader)
+            state["resource"] = resource
+        loaded = resource.read()
+        return loaded(*children, **props)
+
+    name = getattr(loader, "__name__", "Lazy")
+    if name == "<lambda>":
+        name = "Lazy"
+    return Component(Lazy, display_name=name)
+
+
+__all__ = [
+    "Resource",
+    "Suspend",
+    "lazy",
+    "start_resource",
+]

pythonnative/templates/android_template/app/build.gradle

@@ -0,0 +1,75 @@
+plugins {
+    id 'com.android.application'
+    id 'org.jetbrains.kotlin.android'
+    id 'com.chaquo.python'
+}
+
+android {
+    namespace 'com.pythonnative.android_template'
+    compileSdk 34
+
+    defaultConfig {
+        applicationId "com.pythonnative.android_template"
+        minSdk 24
+        targetSdk 34
+        versionCode 1
+        versionName "1.0"
+
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+        ndk {
+            abiFilters "arm64-v8a", "x86_64"
+        }
+        python {
+            // Rewritten from app.python_version by the pn CLI (project/android.py).
+            version "3.13"
+            pyc {
+                // Rewritten by the pn CLI: debug builds keep the .py sources
+                // (tracebacks show code; the dev client can seed its overlay
+                // from them), release builds ship bytecode only.
+                src false
+            }
+            pip {
+                // `options` lines for [requirements].extra_index_urls are
+                // injected above `install` by the pn CLI.
+                install "-r", "requirements.txt"
+            }
+        }
+    }
+
+    buildFeatures {
+        // MainActivity gates dev-only behavior (hot reload) on BuildConfig.DEBUG.
+        buildConfig true
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+    kotlinOptions {
+        jvmTarget = '1.8'
+    }
+}
+
+dependencies {
+
+    // The PythonNative runtime: component managers, native modules,
+    // gestures, animations, and the screen fragment. Its AndroidX and
+    // Material dependencies are exposed transitively.
+    implementation project(':pythonnative')
+
+    implementation 'androidx.core:core-ktx:1.8.0'
+    implementation 'androidx.appcompat:appcompat:1.4.1'
+    implementation 'com.google.android.material:material:1.5.0'
+    // AndroidX Navigation for Fragment-based navigation (activity_main.xml)
+    implementation 'androidx.navigation:navigation-fragment-ktx:2.7.7'
+    implementation 'androidx.navigation:navigation-ui-ktx:2.7.7'
+    testImplementation 'junit:junit:4.13.2'
+    androidTestImplementation 'androidx.test.ext:junit:1.1.3'
+    androidTestImplementation 'androidx.test.espresso:espresso-core:3.4.0'
+}

pythonnative/templates/android_template/app/proguard-rules.pro

@@ -0,0 +1,21 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
+
+# Uncomment this to preserve the line number information for
+# debugging stack traces.
+#-keepattributes SourceFile,LineNumberTable
+
+# If you keep the line number information, uncomment this to
+# hide the original source file name.
+#-renamesourcefileattribute SourceFile

pythonnative/templates/android_template/app/src/androidTest/java/com/pythonnative/android_template/ExampleInstrumentedTest.kt

@@ -0,0 +1,24 @@
+package com.pythonnative.android_template
+
+import androidx.test.platform.app.InstrumentationRegistry
+import androidx.test.ext.junit.runners.AndroidJUnit4
+
+import org.junit.Test
+import org.junit.runner.RunWith
+
+import org.junit.Assert.*
+
+/**
+ * Instrumented test, which will execute on an Android device.
+ *
+ * See [testing documentation](http://d.android.com/tools/testing).
+ */
+@RunWith(AndroidJUnit4::class)
+class ExampleInstrumentedTest {
+    @Test
+    fun useAppContext() {
+        // Context of the app under test.
+        val appContext = InstrumentationRegistry.getInstrumentation().targetContext
+        assertEquals("com.pythonnative.android_template", appContext.packageName)
+    }
+}

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Debug builds are dev clients: they open a WebSocket to `pn start`
+     to sync sources and stream logs. Release builds don't merge this
+     file, so they gain no network permission the app didn't ask for. -->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
+</manifest>

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

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <!-- Runtime-gated on Android 13+ (API 33); requested by the
+         pythonnative notifications module before posting. -->
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+    <application
+        android:allowBackup="true"
+        android:dataExtractionRules="@xml/data_extraction_rules"
+        android:fullBackupContent="@xml/backup_rules"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.Android_template"
+        tools:targetApi="31">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:launchMode="singleTask"
+            android:windowSoftInputMode="adjustResize">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>

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

@@ -0,0 +1,130 @@
+package com.pythonnative.android_template
+
+import android.content.Intent
+import android.graphics.Color
+import android.graphics.Typeface
+import android.os.Bundle
+import android.util.Log
+import android.util.TypedValue
+import android.widget.ScrollView
+import android.widget.TextView
+import androidx.appcompat.app.AppCompatActivity
+import com.chaquo.python.Python
+import com.chaquo.python.android.AndroidPlatform
+import com.pythonnative.runtime.PNBridge
+import com.pythonnative.runtime.PythonHost
+import com.pythonnative.runtime.modules.BuiltinModules
+
+/**
+ * The single activity. It starts Python, wires the `PNBridge` host
+ * callback into `pythonnative.bridge.native_callback`, runs the
+ * protocol handshake, and forwards activity callbacks to the Kotlin
+ * native modules. Screens live in `ScreenFragment`s inside the
+ * `NavHostFragment` from `activity_main.xml`.
+ */
+class MainActivity : AppCompatActivity() {
+    private val TAG = javaClass.simpleName
+    private var pythonReady = false
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        Log.d(TAG, "onCreate() called")
+
+        if (!Python.isStarted()) {
+            Python.start(AndroidPlatform(this))
+        }
+        try {
+            PNBridge.setContext(this)
+            val py = Python.getInstance()
+            PNBridge.setHost(object : PythonHost {
+                override fun callback(kind: String, tag: Long, name: String, payloadJson: String): String? =
+                    py.getModule("pythonnative.bridge")
+                        .callAttr("native_callback", kind, tag, name, payloadJson)
+                        ?.toString()
+            })
+            if (BuildConfig.DEBUG) {
+                // Dev-only: the writable source overlay the dev client syncs
+                // into, and the dev server `pn run` asked us to connect to
+                // (an intent extra; a remembered server is used otherwise).
+                py.getModule("pythonnative.hot_reload").callAttr(
+                    "configure_dev_environment",
+                    filesDir.absolutePath,
+                    intent?.getStringExtra("pn_dev_server")
+                )
+            }
+            // Handshake with the runtime library (raises on a protocol
+            // mismatch, before any screen is created), enable dev mode in
+            // debug builds, and warm the asyncio runtime.
+            py.getModule("pythonnative.bootstrap").callAttr("start", BuildConfig.DEBUG, true)
+            // Import the entry module now so a broken app fails here,
+            // with a full traceback, instead of inside the first fragment.
+            py.getModule(getString(R.string.pn_entry_module))
+            pythonReady = true
+            // Set content view to the NavHost layout; the initial screen
+            // loads via nav_graph startDestination.
+            setContentView(R.layout.activity_main)
+        } catch (e: Exception) {
+            Log.e("PythonNative", "Bootstrap failed", e)
+            showBootstrapError(e)
+            return
+        }
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        BuiltinModules.onActivityDestroyed(this)
+        PNBridge.clearContext(this)
+    }
+
+    @Deprecated("Deprecated in Java")
+    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
+        @Suppress("DEPRECATION")
+        super.onActivityResult(requestCode, resultCode, data)
+        BuiltinModules.onActivityResult(requestCode, resultCode, data)
+    }
+
+    override fun onRequestPermissionsResult(
+        requestCode: Int,
+        permissions: Array<out String>,
+        grantResults: IntArray
+    ) {
+        super.onRequestPermissionsResult(requestCode, permissions, grantResults)
+        BuiltinModules.onRequestPermissionsResult(requestCode, permissions, grantResults)
+    }
+
+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent)
+        setIntent(intent)
+        BuiltinModules.onNewIntent(intent)
+    }
+
+    override fun onResume() {
+        super.onResume()
+        if (pythonReady) BuiltinModules.onActivityResumed()
+    }
+
+    override fun onPause() {
+        super.onPause()
+        if (pythonReady) BuiltinModules.onActivityPaused()
+    }
+
+    override fun onStop() {
+        super.onStop()
+        if (pythonReady) BuiltinModules.onActivityStopped()
+    }
+
+    private fun showBootstrapError(error: Exception) {
+        val text = TextView(this)
+        text.text = "PythonNative could not start\n\n" + Log.getStackTraceString(error)
+        text.setTextColor(Color.WHITE)
+        text.setBackgroundColor(Color.rgb(191, 26, 26))
+        text.typeface = Typeface.MONOSPACE
+        text.setTextSize(TypedValue.COMPLEX_UNIT_SP, 12f)
+        val pad = (16 * resources.displayMetrics.density).toInt()
+        text.setPadding(pad, pad * 3, pad, pad * 2)
+        val scroll = ScrollView(this)
+        scroll.setBackgroundColor(Color.rgb(191, 26, 26))
+        scroll.addView(text)
+        setContentView(scroll)
+    }
+}

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

@@ -0,0 +1,13 @@
+package com.pythonnative.android_template
+
+import com.pythonnative.runtime.screens.PNScreenFragment
+
+/**
+ * The app's screen fragment (named by `nav_graph.xml`). The start
+ * destination has no `screen_path` argument, so it shows the entry
+ * module from `pythonnative.toml` (staged into `R.string.pn_entry_module`);
+ * pushed screens carry an explicit path.
+ */
+class ScreenFragment : PNScreenFragment() {
+    override fun defaultPath(): String = getString(R.string.pn_entry_module)
+}

pythonnative/templates/android_template/app/src/main/res/drawable/ic_launcher_background.xml

@@ -0,0 +1,170 @@
+<?xml version="1.0" encoding="utf-8"?>
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <path
+        android:fillColor="#3DDC84"
+        android:pathData="M0,0h108v108h-108z" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M9,0L9,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,0L19,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M29,0L29,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M39,0L39,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M49,0L49,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M59,0L59,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M69,0L69,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M79,0L79,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M89,0L89,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M99,0L99,108"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,9L108,9"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,19L108,19"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,29L108,29"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,39L108,39"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,49L108,49"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,59L108,59"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,69L108,69"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,79L108,79"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,89L108,89"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,99L108,99"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,29L89,29"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,39L89,39"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,49L89,49"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,59L89,59"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,69L89,69"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M19,79L89,79"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M29,19L29,89"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M39,19L39,89"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M49,19L49,89"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M59,19L59,89"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M69,19L69,89"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M79,19L79,89"
+        android:strokeWidth="0.8"
+        android:strokeColor="#33FFFFFF" />
+</vector>