pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/native/android/src/main/java/com/pythonnative/runtime/modules/NativeModule.kt

@@ -0,0 +1,158 @@
+package com.pythonnative.runtime.modules
+
+import com.pythonnative.runtime.PNBridge
+import com.pythonnative.runtime.bridge.JsonUtil
+import com.pythonnative.runtime.bridge.MainThread
+import org.json.JSONObject
+
+/**
+ * A named native module exposing methods to Python through
+ * `PNBridge.call(module, method, argsJson)`.
+ *
+ * Implementations settle the [Promise] synchronously (the result is
+ * returned inline) or later from any thread (the result is delivered
+ * as a `module` callback on the main thread). Unknown methods should
+ * call [Promise.rejectUnknownMethod].
+ */
+interface NativeModule {
+    /** The module name Python addresses, for example `"Clipboard"`. */
+    val name: String
+
+    /** Handle one call; must settle `promise` exactly once (now or later). */
+    fun call(method: String, args: JSONObject, promise: Promise)
+}
+
+/**
+ * Result envelopes for module calls and events, as JSON strings.
+ */
+object ModuleEnvelope {
+    /** Decode `{"call_id": n, "args": {...}}` into `(callId, args)`. */
+    fun decodeCall(argsJson: String): Pair<Long, JSONObject> {
+        val obj = if (argsJson.isBlank()) JSONObject() else JSONObject(argsJson)
+        val callId = obj.optLong("call_id", 0L)
+        val args = obj.optJSONObject("args") ?: JSONObject()
+        return callId to args
+    }
+
+    /** `{"ok": true, "value": ...}` */
+    fun ok(value: Any?): String = JSONObject().put("ok", true).put("value", JsonUtil.wrap(value)).toString()
+
+    /** `{"ok": false, "error": message, "code": code}` */
+    fun error(message: String, code: String? = null): String {
+        val obj = JSONObject().put("ok", false).put("error", message)
+        if (code != null) obj.put("code", code)
+        return obj.toString()
+    }
+
+    /** `{"pending": true}` */
+    fun pending(): String = JSONObject().put("pending", true).toString()
+
+    /** `{"call_id": n, "ok": true, "value": ...}` for asynchronous settlement. */
+    fun settled(callId: Long, value: Any?): String =
+        JSONObject().put("call_id", callId).put("ok", true).put("value", JsonUtil.wrap(value)).toString()
+
+    /** `{"call_id": n, "ok": false, "error": message, "code": code}` for asynchronous rejection. */
+    fun settledError(callId: Long, message: String, code: String?): String {
+        val obj = JSONObject().put("call_id", callId).put("ok", false).put("error", message)
+        if (code != null) obj.put("code", code)
+        return obj.toString()
+    }
+
+    /** `{"event": name, "payload": {...}}` */
+    fun event(event: String, payload: Any?): String =
+        JSONObject().put("event", event).put("payload", JsonUtil.wrap(payload)).toString()
+}
+
+/**
+ * The settlement handle for one module call.
+ *
+ * If [resolve] or [reject] runs before the module's `call` returns,
+ * the result is returned inline to Python. Otherwise Python receives
+ * `{"pending": true}` and the eventual settlement is delivered on the
+ * main thread as a `module` callback carrying the `call_id`.
+ */
+class Promise(val callId: Long, val module: String, private val dispatch: (Runnable) -> Unit = defaultDispatcher) {
+    private var returned = false
+    private var settledInline: String? = null
+    internal var onFinished: (() -> Unit)? = null
+    private var cancellation: (() -> Unit)? = null
+    var isCancelled = false
+        private set
+
+    /** Release native work when the Python awaiter is cancelled. */
+    @Synchronized fun onCancel(callback: () -> Unit) {
+        if (isCancelled) callback() else if (!isSettled) cancellation = callback
+    }
+
+    @Synchronized fun cancel() {
+        if (isSettled) return
+        isCancelled = true
+        isSettled = true
+        val callback = cancellation
+        cancellation = null
+        onFinished?.invoke()
+        runCatching { callback?.invoke() }
+    }
+
+    /** Whether the promise has been resolved or rejected. */
+    var isSettled = false
+        private set
+
+    /** Resolve with `value` (JSON-encodable: primitives, maps, lists, `JSONObject`). */
+    @Synchronized fun resolve(value: Any?) {
+        if (isSettled) return
+        isSettled = true
+        cancellation = null
+        onFinished?.invoke()
+        if (!returned) {
+            settledInline = ModuleEnvelope.ok(value)
+        } else {
+            deliver(ModuleEnvelope.settled(callId, value))
+        }
+    }
+
+    /** Reject with `message` and an optional machine-readable `code`. */
+    @Synchronized fun reject(message: String, code: String? = null) {
+        if (isSettled) return
+        isSettled = true
+        cancellation = null
+        onFinished?.invoke()
+        if (!returned) {
+            settledInline = ModuleEnvelope.error(message, code)
+        } else {
+            deliver(ModuleEnvelope.settledError(callId, message, code))
+        }
+    }
+
+    /** Reject because the module has no method named `method`. */
+    fun rejectUnknownMethod(method: String) = reject("$module has no method '$method'", "unknown_method")
+
+    /**
+     * Called by the bridge after `call` returns: yields the inline
+     * envelope when already settled, otherwise `{"pending": true}` and
+     * arms asynchronous delivery.
+     */
+    @Synchronized fun markReturned(): String {
+        returned = true
+        return settledInline ?: ModuleEnvelope.pending()
+    }
+
+    private fun deliver(payload: String) {
+        val moduleName = module
+        dispatch(Runnable { PNBridge.callPython("module", 0, moduleName, payload) })
+    }
+
+    companion object {
+        /** How asynchronous settlements reach the main thread (replaceable in tests). */
+        var defaultDispatcher: (Runnable) -> Unit = { MainThread.post(it) }
+    }
+}
+
+/** Unsolicited module events (`{"event": name, "payload": {...}}`). */
+object ModuleEvents {
+    /** Emit `event` for `module` on the main thread (posting if needed). */
+    fun emit(module: String, event: String, payload: Any?) {
+        val json = ModuleEnvelope.event(event, payload)
+        MainThread.runOnMain { PNBridge.callPython("module", 0, module, json) }
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/modules/NotificationsModule.kt

@@ -0,0 +1,100 @@
+package com.pythonnative.runtime.modules
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.content.Context
+import android.os.Build
+import com.pythonnative.runtime.PNBridge
+import com.pythonnative.runtime.bridge.JsonUtil
+import com.pythonnative.runtime.bridge.MainThread
+import com.pythonnative.runtime.bridge.PNLog
+import com.pythonnative.runtime.bridge.str
+import org.json.JSONObject
+import kotlin.math.abs
+
+/**
+ * `Notifications`: `request_permission()` (async; `POST_NOTIFICATIONS`
+ * on API 33+), `schedule({title, body, delay_seconds, identifier})`
+ * (a Handler-delayed local notification, in-process only),
+ * `cancel(identifier)`, and `get_device_token()` (`null`; no built-in
+ * push on Android).
+ */
+class NotificationsModule : NativeModule {
+    override val name = "Notifications"
+    private val delayed = HashMap<String, Runnable>()
+
+    override fun call(method: String, args: JSONObject, promise: Promise) {
+        when (method) {
+            "request_permission" -> requestPermission(promise)
+            "schedule" -> promise.resolve(schedule(args))
+            "cancel" -> {
+                cancel(args.str("identifier") ?: "")
+                promise.resolve(null)
+            }
+            "get_device_token" -> promise.resolve(null)
+            else -> promise.rejectUnknownMethod(method)
+        }
+    }
+
+    private fun requestPermission(promise: Promise) {
+        if (Build.VERSION.SDK_INT < 33) return promise.resolve(true)
+        BuiltinModules.permissions.request("notifications") { status ->
+            promise.resolve(status == PermissionsModule.GRANTED)
+        }
+    }
+
+    private fun schedule(args: JSONObject): Boolean {
+        val title = args.str("title") ?: ""
+        val body = args.str("body") ?: ""
+        val identifier = args.str("identifier") ?: "pn_${System.currentTimeMillis()}"
+        val delaySeconds = JsonUtil.toDouble(args.opt("delay_seconds"), 0.0)
+        cancel(identifier)
+        if (delaySeconds <= 0.0) return post(title, body, identifier)
+        val runnable = Runnable {
+            delayed.remove(identifier)
+            post(title, body, identifier)
+        }
+        delayed[identifier] = runnable
+        MainThread.postDelayed(runnable, (delaySeconds * 1000).toLong())
+        return true
+    }
+
+    private fun cancel(identifier: String) {
+        delayed.remove(identifier)?.let { MainThread.remove(it) }
+        try {
+            manager()?.cancel(notificationId(identifier))
+        } catch (e: Exception) {
+            PNLog.swallowed("Notifications.cancel", e)
+        }
+    }
+
+    private fun manager(): NotificationManager? =
+        PNBridge.context().getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager
+
+    private fun post(title: String, body: String, identifier: String): Boolean {
+        return try {
+            val ctx = PNBridge.context()
+            val nm = manager() ?: return false
+            val builder = if (Build.VERSION.SDK_INT >= 26) {
+                nm.createNotificationChannel(NotificationChannel(CHANNEL_ID, "PythonNative", NotificationManager.IMPORTANCE_DEFAULT))
+                Notification.Builder(ctx, CHANNEL_ID)
+            } else {
+                @Suppress("DEPRECATION")
+                Notification.Builder(ctx)
+            }
+            builder.setContentTitle(title).setContentText(body).setSmallIcon(android.R.drawable.ic_dialog_info)
+            nm.notify(notificationId(identifier), builder.build())
+            true
+        } catch (e: Exception) {
+            PNLog.swallowed("Notifications.post", e)
+            false
+        }
+    }
+
+    private fun notificationId(identifier: String): Int = abs(identifier.hashCode()) % Int.MAX_VALUE
+
+    private companion object {
+        const val CHANNEL_ID = "pn_default"
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/modules/PermissionsModule.kt

@@ -0,0 +1,99 @@
+package com.pythonnative.runtime.modules
+
+import android.content.pm.PackageManager
+import android.os.Build
+import androidx.core.app.ActivityCompat
+import androidx.core.content.ContextCompat
+import com.pythonnative.runtime.PNBridge
+import com.pythonnative.runtime.bridge.str
+import org.json.JSONObject
+
+/**
+ * `Permissions.check(permission)` (sync) and `request(permission)`
+ * (async, routed through `onRequestPermissionsResult`). Statuses are
+ * `granted`, `denied`, `blocked`, and `undetermined`.
+ *
+ * Permission names are the `[permissions]` keys from pythonnative.toml
+ * (`camera`, `microphone`, `photo_library`, `location_when_in_use`,
+ * `contacts`, `notifications`); the Python facade validates them before
+ * the call reaches this module, so an unknown name here is a bug rather
+ * than user input, and is rejected rather than answered.
+ */
+class PermissionsModule : NativeModule {
+    override val name = "Permissions"
+    private val pending = HashMap<Int, Pair<String, (String) -> Unit>>()
+
+    override fun call(method: String, args: JSONObject, promise: Promise) {
+        val permission = args.str("permission") ?: ""
+        if (method == "check" || method == "request") {
+            if (!MANIFEST.containsKey(permission)) {
+                return promise.reject("unknown permission '$permission'", "bad_args")
+            }
+        }
+        when (method) {
+            "check" -> promise.resolve(check(permission))
+            "request" -> request(permission) { promise.resolve(it) }
+            else -> promise.rejectUnknownMethod(method)
+        }
+    }
+
+    /** Current status of `permission` without prompting. */
+    fun check(permission: String): String {
+        val manifest = MANIFEST[permission] ?: return UNDETERMINED
+        if (permission == "notifications" && Build.VERSION.SDK_INT < 33) return GRANTED
+        if (permission == "photo_library" && Build.VERSION.SDK_INT < 33) {
+            return statusOf("android.permission.READ_EXTERNAL_STORAGE")
+        }
+        return statusOf(manifest)
+    }
+
+    private fun statusOf(manifest: String): String {
+        val ctx = PNBridge.activity() ?: return UNDETERMINED
+        val granted = ContextCompat.checkSelfPermission(ctx, manifest) == PackageManager.PERMISSION_GRANTED
+        if (granted) return GRANTED
+        // "denied" with no rationale after a previous denial means "don't ask again".
+        val asked = ctx.getSharedPreferences("pn_permissions", 0).getBoolean(manifest, false)
+        return if (asked && !ActivityCompat.shouldShowRequestPermissionRationale(ctx, manifest)) BLOCKED else DENIED
+    }
+
+    /** Prompt for `permission` if needed and report the resulting status to `onDone`. */
+    fun request(permission: String, onDone: (String) -> Unit) {
+        val manifest = MANIFEST[permission] ?: return onDone(UNDETERMINED)
+        if (check(permission) == GRANTED) return onDone(GRANTED)
+        val activity = PNBridge.activity() ?: return onDone(check(permission))
+        val target = if (permission == "photo_library" && Build.VERSION.SDK_INT < 33) "android.permission.READ_EXTERNAL_STORAGE" else manifest
+        val code = RequestCodes.next()
+        pending[code] = target to onDone
+        try {
+            ActivityCompat.requestPermissions(activity, arrayOf(target), code)
+        } catch (e: Exception) {
+            pending.remove(code)
+            onDone(check(permission))
+        }
+    }
+
+    /** Route `Activity.onRequestPermissionsResult`; `true` when a pending request matched. */
+    fun onRequestPermissionsResult(requestCode: Int, grantResults: IntArray): Boolean {
+        val (manifest, onDone) = pending.remove(requestCode) ?: return false
+        PNBridge.activity()?.getSharedPreferences("pn_permissions", 0)?.edit()?.putBoolean(manifest, true)?.apply()
+        val granted = grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED
+        onDone(if (granted) GRANTED else statusOf(manifest))
+        return true
+    }
+
+    companion object {
+        const val GRANTED = "granted"
+        const val DENIED = "denied"
+        const val BLOCKED = "blocked"
+        const val UNDETERMINED = "undetermined"
+
+        val MANIFEST = mapOf(
+            "camera" to "android.permission.CAMERA",
+            "microphone" to "android.permission.RECORD_AUDIO",
+            "photo_library" to "android.permission.READ_MEDIA_IMAGES",
+            "location_when_in_use" to "android.permission.ACCESS_FINE_LOCATION",
+            "contacts" to "android.permission.READ_CONTACTS",
+            "notifications" to "android.permission.POST_NOTIFICATIONS",
+        )
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/modules/StorageModules.kt

@@ -0,0 +1,89 @@
+package com.pythonnative.runtime.modules
+
+import android.content.Context
+import android.content.SharedPreferences
+import com.pythonnative.runtime.PNBridge
+import com.pythonnative.runtime.bridge.PNLog
+import com.pythonnative.runtime.bridge.str
+import org.json.JSONObject
+
+/** `Storage`: `get/set/delete/all_keys/clear` over the `pn_async_storage` SharedPreferences file. */
+class StorageModule : NativeModule {
+    override val name = "Storage"
+
+    private fun prefs(): SharedPreferences =
+        PNBridge.context().getSharedPreferences("pn_async_storage", Context.MODE_PRIVATE)
+
+    override fun call(method: String, args: JSONObject, promise: Promise) {
+        val key = args.str("key")
+        when (method) {
+            "get", "get_item" -> promise.resolve(prefs().getString(key ?: "", null))
+            "set", "set_item" -> {
+                prefs().edit().putString(key ?: "", args.str("value") ?: "").apply()
+                promise.resolve(null)
+            }
+            "delete", "remove", "remove_item" -> {
+                prefs().edit().remove(key ?: "").apply()
+                promise.resolve(null)
+            }
+            "all_keys", "get_all_keys" -> promise.resolve(prefs().all.keys.sorted())
+            "clear" -> {
+                prefs().edit().clear().apply()
+                promise.resolve(null)
+            }
+            else -> promise.rejectUnknownMethod(method)
+        }
+    }
+}
+
+/**
+ * `SecureStore`: `set_item/get_item/delete_item` over `EncryptedSharedPreferences`.
+ *
+ * security-crypto 1.1 deprecates the whole API in favour of hand-rolled Keystore code, but the
+ * file name and schemes must stay identical to what earlier PythonNative releases wrote so that
+ * existing secrets remain readable, hence the suppression.
+ */
+@Suppress("DEPRECATION")
+class SecureStoreModule : NativeModule {
+    override val name = "SecureStore"
+    private var prefs: SharedPreferences? = null
+
+    private fun prefs(): SharedPreferences? {
+        prefs?.let { return it }
+        return try {
+            val ctx = PNBridge.context()
+            val master = androidx.security.crypto.MasterKey.Builder(ctx)
+                .setKeyScheme(androidx.security.crypto.MasterKey.KeyScheme.AES256_GCM)
+                .build()
+            androidx.security.crypto.EncryptedSharedPreferences.create(
+                ctx,
+                "com.pythonnative.securestore",
+                master,
+                androidx.security.crypto.EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+                androidx.security.crypto.EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM,
+            ).also { prefs = it }
+        } catch (e: Exception) {
+            PNLog.rateLimited("securestore", "EncryptedSharedPreferences unavailable", e)
+            null
+        }
+    }
+
+    override fun call(method: String, args: JSONObject, promise: Promise) {
+        val key = args.str("key") ?: ""
+        val store = prefs()
+        when (method) {
+            "set_item" -> {
+                if (store == null) return promise.resolve(false)
+                store.edit().putString(key, args.str("value") ?: "").apply()
+                promise.resolve(true)
+            }
+            "get_item" -> promise.resolve(store?.getString(key, null))
+            "delete_item" -> {
+                if (store == null) return promise.resolve(false)
+                store.edit().remove(key).apply()
+                promise.resolve(true)
+            }
+            else -> promise.rejectUnknownMethod(method)
+        }
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/modules/SystemModules.kt

@@ -0,0 +1,178 @@
+package com.pythonnative.runtime.modules
+
+import android.app.Activity
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.net.ConnectivityManager
+import android.net.Network
+import android.net.NetworkCapabilities
+import android.os.BatteryManager
+import com.pythonnative.runtime.PNBridge
+import com.pythonnative.runtime.bridge.MainThread
+import com.pythonnative.runtime.bridge.PNLog
+import org.json.JSONObject
+
+/**
+ * `Battery`: `get_level()` (0..1 or -1) and `get_state()`
+ * (`unknown|unplugged|charging|full`), plus `change` events from the
+ * sticky `ACTION_BATTERY_CHANGED` broadcast.
+ */
+class BatteryModule : NativeModule {
+    override val name = "Battery"
+    private var receiver: BroadcastReceiver? = null
+
+    override fun call(method: String, args: JSONObject, promise: Promise) {
+        when (method) {
+            "get_level" -> promise.resolve(level())
+            "get_state" -> promise.resolve(state())
+            else -> promise.rejectUnknownMethod(method)
+        }
+    }
+
+    private fun manager(): BatteryManager? =
+        PNBridge.context().getSystemService(Context.BATTERY_SERVICE) as? BatteryManager
+
+    private fun level(): Double {
+        val pct = manager()?.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY) ?: return -1.0
+        return if (pct in 0..100) pct / 100.0 else -1.0
+    }
+
+    private fun state(): String = stateName(manager()?.getIntProperty(BatteryManager.BATTERY_PROPERTY_STATUS) ?: -1)
+
+    private fun stateName(status: Int): String = when (status) {
+        BatteryManager.BATTERY_STATUS_CHARGING -> "charging"
+        BatteryManager.BATTERY_STATUS_FULL -> "full"
+        BatteryManager.BATTERY_STATUS_DISCHARGING, BatteryManager.BATTERY_STATUS_NOT_CHARGING -> "unplugged"
+        else -> "unknown"
+    }
+
+    fun attach(activity: Activity) {
+        if (receiver != null) return
+        val r = 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
+                ModuleEvents.emit(name, "change", JSONObject().put("level", fraction).put("state", stateName(status)))
+            }
+        }
+        try {
+            activity.registerReceiver(r, IntentFilter(Intent.ACTION_BATTERY_CHANGED))
+            receiver = r
+        } catch (e: Exception) {
+            PNLog.swallowed("Battery.attach", e)
+        }
+    }
+
+    fun detach(activity: Activity) {
+        receiver?.let {
+            try {
+                activity.unregisterReceiver(it)
+            } catch (e: Exception) {
+                PNLog.swallowed("Battery.detach", e)
+            }
+        }
+        receiver = null
+    }
+}
+
+/**
+ * `NetInfo.fetch()` → `{is_connected, type, is_internet_reachable}`;
+ * a default `NetworkCallback` emits `change` events on the main thread.
+ */
+class NetInfoModule : NativeModule {
+    override val name = "NetInfo"
+    private var callback: ConnectivityManager.NetworkCallback? = null
+    private var last: JSONObject? = null
+
+    override fun call(method: String, args: JSONObject, promise: Promise) {
+        when (method) {
+            "fetch" -> promise.resolve(snapshot())
+            else -> promise.rejectUnknownMethod(method)
+        }
+    }
+
+    private fun manager(): ConnectivityManager? =
+        PNBridge.context().getSystemService(Context.CONNECTIVITY_SERVICE) as? ConnectivityManager
+
+    fun snapshot(): JSONObject {
+        val offline = JSONObject().put("is_connected", false).put("type", "none").put("is_internet_reachable", false)
+        return try {
+            val manager = manager() ?: return offline
+            val network = manager.activeNetwork ?: return offline
+            val caps = manager.getNetworkCapabilities(network) ?: return offline
+            val kind = when {
+                caps.hasTransport(NetworkCapabilities.TRANSPORT_WIFI) -> "wifi"
+                caps.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR) -> "cellular"
+                caps.hasTransport(NetworkCapabilities.TRANSPORT_ETHERNET) -> "ethernet"
+                else -> "other"
+            }
+            JSONObject()
+                .put("is_connected", true)
+                .put("type", kind)
+                .put("is_internet_reachable", caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET))
+        } catch (e: Exception) {
+            offline
+        }
+    }
+
+    fun attach(activity: Activity) {
+        if (callback != null) return
+        try {
+            val manager = activity.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
+            val cb = object : ConnectivityManager.NetworkCallback() {
+                override fun onAvailable(network: Network) = changed()
+                override fun onLost(network: Network) = changed()
+                override fun onCapabilitiesChanged(network: Network, capabilities: NetworkCapabilities) = changed()
+            }
+            manager.registerDefaultNetworkCallback(cb)
+            callback = cb
+        } catch (e: Exception) {
+            PNLog.swallowed("NetInfo.attach", e)
+        }
+    }
+
+    private fun changed() {
+        // NetworkCallback fires on a binder thread; hop to main before reading state.
+        MainThread.post {
+            val current = snapshot()
+            if (last?.toString() == current.toString()) return@post
+            last = current
+            ModuleEvents.emit(name, "change", current)
+        }
+    }
+
+    fun detach(activity: Activity) {
+        callback?.let {
+            try {
+                (activity.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager).unregisterNetworkCallback(it)
+            } catch (e: Exception) {
+                PNLog.swallowed("NetInfo.detach", e)
+            }
+        }
+        callback = null
+    }
+}
+
+/** `AppState.current_state()` plus `change` events (`active|inactive|background`). */
+class AppStateModule : NativeModule {
+    override val name = "AppState"
+    private var state = "active"
+
+    override fun call(method: String, args: JSONObject, promise: Promise) {
+        when (method) {
+            "current_state" -> promise.resolve(state)
+            else -> promise.rejectUnknownMethod(method)
+        }
+    }
+
+    fun transition(next: String) {
+        if (state == next) return
+        state = next
+        ModuleEvents.emit(name, "change", JSONObject().put("state", next))
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/plugins/GeneratedPlugins.kt

@@ -0,0 +1,16 @@
+package com.pythonnative.runtime.plugins
+
+import com.pythonnative.runtime.bridge.PNRegistry
+
+/**
+ * Plugin registrations generated by `pn build`.
+ *
+ * The build tool overwrites this file with one `register` call per
+ * plugin entry declared in the project's `pythonnative.plugins` entry
+ * points. Nothing else may depend on its content beyond [registerAll].
+ */
+object GeneratedPlugins {
+    /** Register every generated plugin with `registry`. */
+    @Suppress("UNUSED_PARAMETER")
+    fun registerAll(registry: PNRegistry) {}
+}