pythonnative 0.36.0__py3-none-any.whl → 0.37.0__py3-none-any.whl

pythonnative/templates/android_template/app/build.gradle

@@ -49,18 +49,15 @@ android {
 
 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'
-    implementation 'androidx.constraintlayout:constraintlayout:2.1.3'
-    implementation 'androidx.recyclerview:recyclerview:1.3.2'
-    // Pull-to-refresh (ScrollView's refresh_control prop)
-    implementation 'androidx.swiperefreshlayout:swiperefreshlayout:1.1.0'
-    // SecureStore (EncryptedSharedPreferences)
-    implementation 'androidx.security:security-crypto:1.1.0'
-    // Biometrics (BiometricPrompt)
-    implementation 'androidx.biometric:biometric:1.1.0'
-    // AndroidX Navigation for Fragment-based navigation
+    // 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'

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

@@ -1,15 +1,8 @@
 package com.pythonnative.android_template
 
-import android.content.BroadcastReceiver
-import android.content.Context
 import android.content.Intent
-import android.content.IntentFilter
-import android.os.BatteryManager
 import android.graphics.Color
 import android.graphics.Typeface
-import android.net.ConnectivityManager
-import android.net.Network
-import android.net.NetworkCapabilities
 import android.os.Bundle
 import android.util.Log
 import android.util.TypedValue
@@ -18,12 +11,20 @@ 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
-    private var networkCallback: ConnectivityManager.NetworkCallback? = null
-    private var batteryReceiver: BroadcastReceiver? = null
 
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
@@ -33,10 +34,14 @@ class MainActivity : AppCompatActivity() {
             Python.start(AndroidPlatform(this))
         }
         try {
-            // Set content view to the NavHost layout; the initial screen
-            // loads via nav_graph startDestination.
-            setContentView(R.layout.activity_main)
+            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 writable source overlay for hot reload.
                 py.getModule("pythonnative.hot_reload").callAttr(
@@ -44,55 +49,35 @@ class MainActivity : AppCompatActivity() {
                     filesDir.absolutePath
                 )
             }
+            // 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
         }
-
-        // A cold start from a deep link carries the URL on the launch intent.
-        intent?.dataString?.let { dispatchUrl(it) }
-
-        registerNetworkCallback()
-        registerBatteryReceiver()
     }
 
     override fun onDestroy() {
         super.onDestroy()
-        batteryReceiver?.let {
-            try {
-                unregisterReceiver(it)
-            } catch (e: Exception) {
-                Log.e("PythonNative", "unregisterReceiver(battery) failed", e)
-            }
-            batteryReceiver = null
-        }
-        networkCallback?.let {
-            try {
-                (getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager)
-                    .unregisterNetworkCallback(it)
-            } catch (e: Exception) {
-                Log.e("PythonNative", "unregisterNetworkCallback failed", e)
-            }
-            networkCallback = null
-        }
+        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)
-        if (!pythonReady) return
-        try {
-            Python.getInstance()
-                .getModule("pythonnative.native_modules")
-                .callAttr("dispatch_activity_result", requestCode, resultCode, data)
-        } catch (e: Exception) {
-            Log.e("PythonNative", "dispatch_activity_result failed", e)
-        }
+        BuiltinModules.onActivityResult(requestCode, resultCode, data)
     }
 
     override fun onRequestPermissionsResult(
@@ -101,147 +86,30 @@ class MainActivity : AppCompatActivity() {
         grantResults: IntArray
     ) {
         super.onRequestPermissionsResult(requestCode, permissions, grantResults)
-        if (!pythonReady) return
-        try {
-            Python.getInstance()
-                .getModule("pythonnative.native_modules")
-                .callAttr("dispatch_permissions_result", requestCode, permissions.toList(), grantResults.toList())
-        } catch (e: Exception) {
-            Log.e("PythonNative", "dispatch_permissions_result failed", e)
-        }
+        BuiltinModules.onRequestPermissionsResult(requestCode, permissions, grantResults)
     }
 
     override fun onNewIntent(intent: Intent) {
         super.onNewIntent(intent)
         setIntent(intent)
-        intent.dataString?.let { dispatchUrl(it) }
+        BuiltinModules.onNewIntent(intent)
     }
 
-    // MARK: - AppState forwarding
-
     override fun onResume() {
         super.onResume()
-        dispatchAppState("active")
+        if (pythonReady) BuiltinModules.onActivityResumed()
     }
 
     override fun onPause() {
         super.onPause()
-        dispatchAppState("inactive")
+        if (pythonReady) BuiltinModules.onActivityPaused()
     }
 
     override fun onStop() {
         super.onStop()
-        dispatchAppState("background")
-    }
-
-    private fun dispatchAppState(state: String) {
-        if (!pythonReady) return
-        try {
-            Python.getInstance()
-                .getModule("pythonnative.native_modules.app_state")
-                .callAttr("dispatch_app_state", state)
-        } catch (e: Exception) {
-            Log.e("PythonNative", "dispatch_app_state($state) failed", e)
-        }
+        if (pythonReady) BuiltinModules.onActivityStopped()
     }
 
-    // MARK: - NetInfo forwarding
-
-    // Live connectivity updates. The callback must be a NetworkCallback
-    // subclass, which Chaquopy's dynamic_proxy can't create from Python
-    // (interfaces only), so the registration lives here and forwards
-    // into the pythonnative net_info module.
-    private fun registerNetworkCallback() {
-        if (!pythonReady || networkCallback != null) return
-        try {
-            val manager = getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
-            val callback = object : ConnectivityManager.NetworkCallback() {
-                override fun onAvailable(network: Network) = dispatchNetInfo()
-                override fun onLost(network: Network) = dispatchNetInfo()
-                override fun onCapabilitiesChanged(
-                    network: Network,
-                    capabilities: NetworkCapabilities
-                ) = dispatchNetInfo()
-            }
-            manager.registerDefaultNetworkCallback(callback)
-            networkCallback = callback
-        } catch (e: Exception) {
-            Log.e("PythonNative", "registerDefaultNetworkCallback failed", e)
-        }
-    }
-
-    private fun dispatchNetInfo() {
-        // NetworkCallback fires on a ConnectivityManager binder thread;
-        // hop to the main thread before crossing into Python.
-        runOnUiThread {
-            if (!pythonReady) return@runOnUiThread
-            try {
-                Python.getInstance()
-                    .getModule("pythonnative.native_modules.net_info")
-                    .callAttr("dispatch_android_change")
-            } catch (e: Exception) {
-                Log.e("PythonNative", "dispatch_android_change failed", e)
-            }
-        }
-    }
-
-    // MARK: - Battery forwarding
-
-    // ACTION_BATTERY_CHANGED is a sticky broadcast, so registering also
-    // delivers the current level immediately.
-    private fun registerBatteryReceiver() {
-        if (!pythonReady || batteryReceiver != null) return
-        try {
-            val receiver = object : BroadcastReceiver() {
-                override fun onReceive(context: Context?, intent: Intent?) {
-                    if (intent == null) return
-                    val level = intent.getIntExtra(BatteryManager.EXTRA_LEVEL, -1)
-                    val scale = intent.getIntExtra(BatteryManager.EXTRA_SCALE, -1)
-                    val status = intent.getIntExtra(BatteryManager.EXTRA_STATUS, -1)
-                    val fraction = if (level >= 0 && scale > 0) level.toDouble() / scale.toDouble() else -1.0
-                    val state = when (status) {
-                        BatteryManager.BATTERY_STATUS_CHARGING -> "charging"
-                        BatteryManager.BATTERY_STATUS_FULL -> "full"
-                        BatteryManager.BATTERY_STATUS_DISCHARGING,
-                        BatteryManager.BATTERY_STATUS_NOT_CHARGING -> "unplugged"
-                        else -> "unknown"
-                    }
-                    dispatchBattery(fraction, state)
-                }
-            }
-            registerReceiver(receiver, IntentFilter(Intent.ACTION_BATTERY_CHANGED))
-            batteryReceiver = receiver
-        } catch (e: Exception) {
-            Log.e("PythonNative", "registerReceiver(battery) failed", e)
-        }
-    }
-
-    private fun dispatchBattery(level: Double, state: String) {
-        if (!pythonReady) return
-        try {
-            Python.getInstance()
-                .getModule("pythonnative.native_modules.battery")
-                .callAttr("dispatch_battery", level, state)
-        } catch (e: Exception) {
-            Log.e("PythonNative", "dispatch_battery failed", e)
-        }
-    }
-
-    // MARK: - Deep links
-
-    private fun dispatchUrl(url: String) {
-        if (!pythonReady) return
-        try {
-            Python.getInstance()
-                .getModule("pythonnative.native_modules.linking")
-                .callAttr("dispatch_url", url)
-        } catch (e: Exception) {
-            Log.e("PythonNative", "dispatch_url failed", e)
-        }
-    }
-
-    // MARK: - Bootstrap error UI
-
     private fun showBootstrapError(error: Exception) {
         val text = TextView(this)
         text.text = "PythonNative could not start\n\n" + Log.getStackTraceString(error)

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

@@ -1,154 +1,16 @@
 package com.pythonnative.android_template
 
-import android.os.Bundle
-import android.os.Handler
-import android.os.Looper
-import android.util.Log
-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
-import com.chaquo.python.Python
-import com.chaquo.python.android.AndroidPlatform
-
-class ScreenFragment : Fragment() {
-    private val TAG = javaClass.simpleName
-    private var screen: PyObject? = null
-    private val hotReloadHandler = Handler(Looper.getMainLooper())
-    private val hotReloadRunnable = object : Runnable {
-        override fun run() {
-            try {
-                screen?.callAttr("hot_reload_tick")
-            } catch (e: Exception) {
-                Log.w(TAG, "hot_reload_tick failed", e)
-            } finally {
-                hotReloadHandler.postDelayed(this, 500)
-            }
-        }
-    }
-
-    override fun onCreate(savedInstanceState: Bundle?) {
-        super.onCreate(savedInstanceState)
-        if (!Python.isStarted()) {
-            context?.let { Python.start(AndroidPlatform(it)) }
-        }
-        try {
-            val py = Python.getInstance()
-            // PythonNative imports the entry module (app.entry_point in
-            // pythonnative.toml, staged into R.string.pn_entry_module)
-            // and looks up its top-level `App` attribute. Pushed screens
-            // pass an explicit path in the fragment arguments.
-            val screenPath = arguments?.getString("screen_path") ?: getString(R.string.pn_entry_module)
-            val argsJson = arguments?.getString("args_json")
-            val filesRoot = requireContext().filesDir.absolutePath
-            val devRoot = "$filesRoot/pythonnative_dev"
-            val hotReload = py.getModule("pythonnative.hot_reload")
-            hotReload.callAttr("configure_dev_environment", filesRoot)
-            val pnScreen = py.getModule("pythonnative.hosts")
-            screen = pnScreen.callAttr("create_screen", screenPath, requireActivity(), argsJson)
-            screen?.callAttr("enable_hot_reload", "$devRoot/reload.json", devRoot)
-        } 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(
-        inflater: LayoutInflater,
-        container: ViewGroup?,
-        savedInstanceState: Bundle?
-    ): View? {
-        // Create a simple container which Python-native views can be attached to.
-        val frame = FrameLayout(requireContext())
-        frame.layoutParams = ViewGroup.LayoutParams(
-            ViewGroup.LayoutParams.MATCH_PARENT,
-            ViewGroup.LayoutParams.MATCH_PARENT
-        )
-        return frame
-    }
-
-    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
-        super.onViewCreated(view, savedInstanceState)
-        // Python side will call set_root_view to attach a native view to Activity.
-        // In fragment-based architecture, the Activity will set contentView once,
-        // so we ensure the fragment's container is available for Python to target.
-        // Expose the fragment container to Python so the screen host can attach into it.
-        try {
-            val py = Python.getInstance()
-            val utils = py.getModule("pythonnative.utils")
-            utils.callAttr("set_android_fragment_container", view)
-            // Now that container exists, invoke on_create so Python can attach its root view
-            screen?.callAttr("on_create")
-            hotReloadHandler.removeCallbacks(hotReloadRunnable)
-            hotReloadHandler.postDelayed(hotReloadRunnable, 500)
-        } catch (e: Exception) {
-            Log.e(TAG, "on_create failed", e)
-        }
-    }
-
-    override fun onStart() {
-        super.onStart()
-        try { screen?.callAttr("on_start") } catch (e: Exception) { Log.w(TAG, "on_start failed", e) }
-    }
-
-    override fun onResume() {
-        super.onResume()
-        try { screen?.callAttr("on_resume") } catch (e: Exception) { Log.w(TAG, "on_resume failed", e) }
-    }
-
-    override fun onPause() {
-        super.onPause()
-        try { screen?.callAttr("on_pause") } catch (e: Exception) { Log.w(TAG, "on_pause failed", e) }
-    }
-
-    override fun onStop() {
-        super.onStop()
-        try { screen?.callAttr("on_stop") } catch (e: Exception) { Log.w(TAG, "on_stop failed", e) }
-    }
-
-    override fun onDestroyView() {
-        super.onDestroyView()
-        hotReloadHandler.removeCallbacks(hotReloadRunnable)
-    }
-
-    override fun onDestroy() {
-        super.onDestroy()
-        hotReloadHandler.removeCallbacks(hotReloadRunnable)
-        try { screen?.callAttr("on_destroy") } catch (e: Exception) { Log.w(TAG, "on_destroy failed", e) }
-    }
-
-    companion object {
-        fun newInstance(screenPath: String, argsJson: String?): ScreenFragment {
-            val f = ScreenFragment()
-            f.arguments = bundleOf(
-                "screen_path" to screenPath,
-                "args_json" to argsJson
-            )
-            return f
-        }
-    }
+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)
+
+    override fun defaultDevRoot(): String? =
+        if (BuildConfig.DEBUG) "${requireContext().filesDir.absolutePath}/pythonnative_dev" else null
 }

pythonnative/templates/android_template/pythonnative/build.gradle

@@ -0,0 +1,48 @@
+plugins {
+    id 'com.android.library'
+    id 'org.jetbrains.kotlin.android'
+}
+
+android {
+    namespace 'com.pythonnative.runtime'
+    compileSdk 34
+
+    defaultConfig {
+        minSdk 24
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+
+    buildFeatures {
+        buildConfig false
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+    kotlinOptions {
+        jvmTarget = '1.8'
+    }
+
+    testOptions {
+        unitTests.returnDefaultValues = true
+    }
+}
+
+dependencies {
+    api 'androidx.core:core-ktx:1.8.0'
+    api 'androidx.appcompat:appcompat:1.4.1'
+    api 'com.google.android.material:material:1.5.0'
+    api 'androidx.recyclerview:recyclerview:1.3.2'
+    api 'androidx.swiperefreshlayout:swiperefreshlayout:1.1.0'
+    api 'androidx.security:security-crypto:1.1.0'
+    api 'androidx.biometric:biometric:1.1.0'
+    api 'androidx.dynamicanimation:dynamicanimation:1.0.0'
+    // Screen navigation (PNScreenFragment inside the app's NavHostFragment).
+    api 'androidx.navigation:navigation-fragment-ktx:2.7.7'
+    api 'androidx.navigation:navigation-ui-ktx:2.7.7'
+
+    testImplementation 'junit:junit:4.13.2'
+    // Real org.json for host-side unit tests (the android.jar stubs are empty).
+    testImplementation 'org.json:json:20231013'
+}

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

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- Runtime-gated on Android 13+ (API 33); requested by the
+         Notifications module before posting. -->
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.VIBRATE" />
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+
+</manifest>