pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/native/android/src/main/java/com/pythonnative/runtime/PNBridge.kt

@@ -0,0 +1,261 @@
+package com.pythonnative.runtime
+
+import android.app.Activity
+import android.content.Context
+import android.util.Log
+import com.pythonnative.runtime.animation.PNAnimator
+import com.pythonnative.runtime.bridge.JsonUtil
+import com.pythonnative.runtime.bridge.MainThread
+import com.pythonnative.runtime.bridge.PNRegistry
+import com.pythonnative.runtime.bridge.TransactionApplier
+import com.pythonnative.runtime.bridge.ViewRegistry
+import com.pythonnative.runtime.modules.BuiltinModules
+import com.pythonnative.runtime.modules.ModuleEnvelope
+import com.pythonnative.runtime.modules.Promise
+import org.json.JSONObject
+import java.util.Locale
+
+/**
+ * The single Java class Python touches.
+ *
+ * Every entry point mirrors one C symbol of the iOS bridge and is
+ * expected to run on the main thread (Python's asyncio loop lives
+ * there). Calls from other threads are logged but still executed so a
+ * misbehaving caller fails loudly in logcat instead of silently.
+ */
+object PNBridge {
+    /** Logcat tag used by the whole runtime. */
+    const val TAG = "PythonNative"
+
+    /** Protocol version compiled into this library. */
+    const val PROTOCOL_VERSION = 2
+
+    private val pythonQueue = java.util.concurrent.Executors.newSingleThreadExecutor { runnable ->
+        Thread(runnable, "PythonNative-events").apply { isDaemon = true }
+    }
+    @Volatile private var host: PythonHost? = null
+    private var activity: Activity? = null
+    private val hostReadyListeners = ArrayList<Runnable>()
+    private val modulePromises = java.util.concurrent.ConcurrentHashMap<Long, Promise>()
+
+    /** Tag to view bookkeeping shared by the applier and managers. */
+    val registry = ViewRegistry()
+
+    private data class Message(val kind: String, val tag: Long, val name: String, val payload: String) {
+        val continuous get() = kind == "event" && (name in setOf("on_scroll", "on_selection_change", "on_gesture_update") ||
+            name.startsWith("gesture:") && JSONObject(payload).optJSONArray("args")?.optJSONObject(0)?.optString("state") == "changed")
+    }
+    private val mailbox = java.util.ArrayDeque<Message>()
+    private var draining = false
+
+    private val commits = com.pythonnative.runtime.bridge.CommitState()
+    private val applier by lazy { TransactionApplier(registry) }
+
+    /** The protocol version Python must match before starting. */
+    @JvmStatic
+    fun protocolVersion(): Int = PROTOCOL_VERSION
+
+    /** Install the Python callback target; flushes callbacks queued before it existed. */
+    @JvmStatic
+    fun setHost(host: PythonHost) {
+        this.host = host
+        val pending = ArrayList(hostReadyListeners)
+        hostReadyListeners.clear()
+        for (listener in pending) {
+            try {
+                listener.run()
+            } catch (e: Exception) {
+                Log.e(TAG, "host-ready listener failed", e)
+            }
+        }
+    }
+
+    /** Whether a [PythonHost] has been installed. */
+    fun hasHost(): Boolean = host != null
+
+    /** Run `runnable` now if a host is installed, otherwise once [setHost] is called. */
+    fun runWhenHostReady(runnable: Runnable) {
+        if (host != null) runnable.run() else hostReadyListeners.add(runnable)
+    }
+
+    /** Record the current activity; modules and managers derive their `Context` from it. */
+    @JvmStatic
+    fun setContext(activity: Activity) {
+        this.activity = activity
+        PNRegistry.ensureBuiltins()
+        BuiltinModules.onContextAttached(activity)
+    }
+
+    /** Forget `activity` if it is the current one (called from `Activity.onDestroy`). */
+    @JvmStatic
+    fun clearContext(activity: Activity) {
+        if (this.activity === activity) this.activity = null
+    }
+
+    /** The current activity, or `null` before [setContext]. */
+    fun activity(): Activity? = activity
+
+    /** The context used to create views; throws before [setContext]. */
+    fun context(): Context =
+        activity ?: throw IllegalStateException("PNBridge.setContext(activity) has not been called")
+
+    /** Display density of the current context (1.0 when no context is attached). */
+    fun density(): Float {
+        val ctx = activity ?: return 1f
+        val d = ctx.resources.displayMetrics.density
+        return if (d > 0f) d else 1f
+    }
+
+    // ------------------------------------------------------------------
+    // Python -> native
+    // ------------------------------------------------------------------
+
+    /** Apply one serialized transaction (a JSON array of ops). */
+    @JvmStatic
+    fun apply(transactionJson: String): String {
+        if (!MainThread.isMain()) return MainThread.call { apply(transactionJson) }
+        return commits.apply(transactionJson, applier)
+    }
+
+    /**
+     * Measure the view with `tag` under the given constraints (dp; `1e6`
+     * means unconstrained) and return `"w,h"` in dp.
+     */
+    @JvmStatic
+    fun measure(tag: Long, maxWidth: Double, maxHeight: Double): String {
+        if (!MainThread.isMain()) return MainThread.call { measure(tag, maxWidth, maxHeight) }
+        val record = registry.get(tag)
+        if (record == null) {
+            Log.w(TAG, "measure: unknown tag $tag")
+            return "0,0"
+        }
+        val size = try {
+            record.manager.measure(record.view, maxWidth, maxHeight)
+        } catch (e: Exception) {
+            Log.e(TAG, "measure failed for ${record.typeName}#$tag", e)
+            floatArrayOf(0f, 0f)
+        }
+        return String.format(Locale.US, "%.3f,%.3f", size[0], size[1])
+    }
+
+    /** Run an imperative command on one view and return its JSON result. */
+    @JvmStatic
+    fun command(tag: Long, name: String, argsJson: String): String? {
+        if (!MainThread.isMain()) return MainThread.call { command(tag, name, argsJson) }
+        val record = registry.get(tag) ?: return null
+        return try {
+            val args = if (argsJson.isBlank()) JSONObject() else JSONObject(argsJson)
+            JsonUtil.encode(record.manager.command(record.view, name, args))
+        } catch (e: Exception) {
+            Log.e(TAG, "command '$name' failed for ${record.typeName}#$tag", e)
+            null
+        }
+    }
+
+    /** Handle an animation request (`set`, `start`, or `cancel`) for one view. */
+    @JvmStatic
+    fun animate(tag: Long, requestJson: String): String? {
+        if (!MainThread.isMain()) return MainThread.call { animate(tag, requestJson) }
+        val record = registry.get(tag) ?: return null
+        return try {
+            PNAnimator.handle(record, JSONObject(requestJson))
+        } catch (e: Exception) {
+            Log.e(TAG, "animate failed for ${record.typeName}#$tag: $requestJson", e)
+            null
+        }
+    }
+
+    /** Call a native module method; `argsJson` is `{"call_id": n, "args": {...}}`. */
+    @JvmStatic
+    fun call(module: String, method: String, argsJson: String): String? {
+        if (!MainThread.isMain()) return MainThread.call { call(module, method, argsJson) }
+        val (callId, args) = try {
+            ModuleEnvelope.decodeCall(argsJson)
+        } catch (e: Exception) {
+            return ModuleEnvelope.error("malformed call envelope: ${e.message}", "bad_request")
+        }
+        if (method == "_pn_cancel") {
+            modulePromises.remove(args.optLong("call_id"))?.takeIf { it.module == module }?.cancel()
+            return ModuleEnvelope.ok(null)
+        }
+        if (module == "Runtime") return JSONObject().put("ok", true).put("value", JSONObject()
+            .put("protocol", 2).put("yoga", "3.2.1").put("schema", com.pythonnative.generated.PNContracts.fingerprint)
+            .put("animation_graph", true).put("logical_lists", true).put("native_layout", true)).toString()
+        if (module == "Layout") return JSONObject().put("ok", true).put("value",
+            com.pythonnative.runtime.layout.NativeLayout.compute(args)).toString()
+        val target = PNRegistry.module(module)
+            ?: return ModuleEnvelope.error("unknown module '$module'", "unknown_module")
+        val promise = Promise(callId, module)
+        if (callId > 0) {
+            modulePromises[callId] = promise
+            promise.onFinished = { modulePromises.remove(callId) }
+        }
+        try {
+            target.call(method, args, promise)
+        } catch (e: Exception) {
+            Log.e(TAG, "module $module.$method threw", e)
+            if (!promise.isSettled) promise.reject(e.message ?: e.toString(), "exception")
+        }
+        return promise.markReturned()
+    }
+
+    // ------------------------------------------------------------------
+    // native -> Python
+    // ------------------------------------------------------------------
+
+    /**
+     * Deliver one callback to Python. Returns `null` when no host is
+     * installed or the Python handler raised (the error is logged).
+     */
+    fun callPython(kind: String, tag: Long, name: String, payloadJson: String): String? {
+        val target = host
+        if (target == null) {
+            Log.w(TAG, "callPython($kind, $tag, $name) dropped: no PythonHost installed")
+            return null
+        }
+        if (kind == "event") com.pythonnative.runtime.animation.AnimationGraph.event(tag, name, org.json.JSONArray(payloadJson))
+        var editRevision = 0L
+        if (kind == "event" && name == "on_change") registry.get(tag)?.let { record ->
+            if (record.typeName == "TextInput") {
+                editRevision = ((record.state["edit_revision"] as? Number)?.toLong() ?: 0L) + 1L
+                record.state["edit_revision"] = editRevision
+            }
+        }
+        val payload = if (kind == "event") commits.event(org.json.JSONArray(payloadJson), editRevision) else payloadJson
+        val message = Message(kind, tag, name, payload)
+        val schedule = synchronized(mailbox) {
+            val last = mailbox.peekLast()
+            if (message.continuous && last?.continuous == true && last.tag == tag && last.name == name) mailbox.removeLast()
+            mailbox.addLast(message)
+            val needed = !draining
+            draining = true
+            needed
+        }
+        if (schedule) pythonQueue.execute {
+            while (true) {
+                val next = synchronized(mailbox) {
+                    mailbox.pollFirst().also { if (it == null) draining = false }
+                } ?: break
+                try { target.callback(next.kind, next.tag, next.name, next.payload) }
+                catch (error: Exception) { Log.e(TAG, "Python callback ${next.kind}/${next.name} raised", error) }
+            }
+        }
+        return null
+    }
+
+    // ------------------------------------------------------------------
+    // Threading helpers
+    // ------------------------------------------------------------------
+
+    /** Whether the caller is on the main thread. */
+    fun isMainThread(): Boolean = MainThread.isMain()
+
+    /** Post `runnable` to the main thread. */
+    fun post(runnable: Runnable) = MainThread.post(runnable)
+
+    private fun assertMain(entry: String) {
+        if (!MainThread.isMain()) {
+            Log.w(TAG, "PNBridge.$entry called off the main thread (${Thread.currentThread().name})")
+        }
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/PythonHost.kt

@@ -0,0 +1,20 @@
+package com.pythonnative.runtime
+
+/**
+ * The reverse direction of the bridge: native to Python.
+ *
+ * The app template installs an implementation that forwards to
+ * `pythonnative.bridge.native_callback` through Chaquopy. The runtime
+ * library itself never touches Chaquopy, which keeps it unit-testable
+ * with plain JUnit.
+ *
+ * `kind` is one of `event`, `module`, `host`, `animation`, or `pump`;
+ * see the bridge protocol documentation for the payload of each.
+ */
+interface PythonHost {
+    /**
+     * Deliver one callback to Python and return its (JSON-encoded)
+     * result, or `null` when the handler produced nothing.
+     */
+    fun callback(kind: String, tag: Long, name: String, payloadJson: String): String?
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/animation/AnimationGraph.kt

@@ -0,0 +1,108 @@
+package com.pythonnative.runtime.animation
+
+import com.pythonnative.runtime.PNBridge
+import org.json.JSONArray
+import org.json.JSONObject
+import kotlin.math.*
+
+/** Expressions and input bindings live on the UI thread, independent of Python. */
+object AnimationGraph {
+    private data class Graph(val nodes: List<JSONObject>, val bindings: JSONArray)
+    private val graphs = HashMap<Long, Graph>()
+    private val values = HashMap<Long, Double>()
+    private val previous = HashMap<Long, Double>()
+    private val output = HashMap<Long, Any>()
+
+    fun install(spec: JSONObject) {
+        val id = spec.getLong("id")
+        val bindings = spec.getJSONArray("bindings")
+        val raw = spec.getJSONArray("nodes")
+        val nodes = (0 until raw.length()).map { raw.getJSONObject(it) }
+        val ids = nodes.map { it.getLong("id") }.toSet()
+        graphs.entries.removeAll { (_, graph) -> graph.nodes.any { it.getLong("id") in ids } }
+        if (bindings.length() == 0) { collect(); return }
+        for (node in nodes) {
+            val key = node.getLong("id")
+            values.putIfAbsent(key, node.optDouble("value", 0.0))
+            previous.putIfAbsent(key, node.optDouble("previous", 0.0))
+        }
+        graphs[id] = Graph(nodes, bindings)
+        collect()
+        evaluate()
+    }
+    fun value(id: Long): Double = values[id] ?: 0.0
+    fun set(id: Long, value: Double) { if (value.isFinite()) { values[id] = value; evaluate() } }
+    fun event(tag: Long, name: String, args: JSONArray) {
+        val payload = args.optJSONObject(0) ?: return
+        val props = PNBridge.registry.get(tag)?.props ?: return
+        val fields = if (name.startsWith("gesture:")) {
+            val index = name.removePrefix("gesture:").toIntOrNull() ?: return
+            props.optJSONArray("gestures")?.optJSONObject(index)?.optJSONObject("animated_events")?.optJSONObject(payload.optString("state"))
+        } else props.optJSONObject("_pn_animated_events")?.optJSONObject(name)
+        if (fields == null) return
+        for (field in fields.keys()) if (payload.opt(field) is Number) values[fields.getLong(field)] = payload.getDouble(field)
+        evaluate()
+    }
+    fun forget(tag: Long) {
+        for ((id, graph) in graphs.toMap()) {
+            val kept = JSONArray()
+            for (i in 0 until graph.bindings.length()) if (graph.bindings.getJSONArray(i).getLong(0) != tag) kept.put(graph.bindings.getJSONArray(i))
+            if (kept.length() == 0) graphs.remove(id) else graphs[id] = Graph(graph.nodes, kept)
+        }
+        collect()
+    }
+    private fun collect() {
+        val live = graphs.values.flatMap { it.nodes }.map { it.getLong("id") }.toSet()
+        values.keys.retainAll(live); previous.keys.retainAll(live); output.keys.retainAll(live)
+    }
+    private fun input(node: JSONObject): Double = if (node.has("node")) values[node.getLong("node")] ?: 0.0 else node.optDouble("constant", 0.0)
+    private fun evaluate() {
+        for (graph in graphs.values) {
+            for (node in graph.nodes) {
+                val id = node.getLong("id")
+                val raw = node.optJSONArray("inputs") ?: JSONArray()
+                val inputs = (0 until raw.length()).map { input(raw.getJSONObject(it)) }
+                val a = inputs.getOrElse(0) { 0.0 }; val b = inputs.getOrElse(1) { 0.0 }
+                val value = when (node.getString("kind")) {
+                    "value" -> values[id] ?: 0.0
+                    "add" -> a + b; "subtract" -> a - b; "multiply" -> a * b
+                    "divide" -> if (b == 0.0) 0.0 else a / b
+                    "modulo" -> if (b == 0.0) 0.0 else a % b
+                    "negate" -> -a
+                    "diff_clamp" -> {
+                        val next = ((values[id] ?: 0.0) + a - (previous[id] ?: a)).coerceIn(node.getDouble("minimum"), node.getDouble("maximum"))
+                        previous[id] = a; next
+                    }
+                    "interpolate" -> interpolate(node, a, id)
+                    else -> 0.0
+                }
+                values[id] = if (value.isFinite()) value else 0.0
+                if (!node.optBoolean("color")) output[id] = values[id]!!
+            }
+            for (i in 0 until graph.bindings.length()) {
+                val binding = graph.bindings.getJSONArray(i)
+                val record = PNBridge.registry.get(binding.getLong(0)) ?: continue
+                record.manager.setAnimatedProperty(record.view, binding.getString(1), output[binding.getLong(2)])
+            }
+        }
+    }
+    private fun interpolate(node: JSONObject, input: Double, id: Long): Double {
+        val ranges = node.getJSONArray("ranges"); val outputs = node.getJSONArray("outputs")
+        val first = ranges.getDouble(0); val last = ranges.getDouble(ranges.length() - 1)
+        var x = input
+        val mode = if (x < first) node.getString("left") else if (x > last) node.getString("right") else "extend"
+        if (mode == "identity") return x
+        if (mode == "clamp") x = x.coerceIn(first, last)
+        var index = 0
+        while (index < ranges.length() - 2 && x >= ranges.getDouble(index + 1)) index++
+        val span = ranges.getDouble(index + 1) - ranges.getDouble(index)
+        val t = if (span == 0.0) 0.0 else (x - ranges.getDouble(index)) / span
+        if (node.optBoolean("color")) {
+            val from = outputs.getJSONArray(index); val to = outputs.getJSONArray(index + 1)
+            val channels = (0..3).map { (from.getDouble(it) + (to.getDouble(it) - from.getDouble(it)) * t.coerceIn(0.0, 1.0)).roundToInt().coerceIn(0, 255) }
+            output[id] = "#" + channels.joinToString("") { "%02X".format(it) }
+            return 0.0
+        }
+        return outputs.getDouble(index) + (outputs.getDouble(index + 1) - outputs.getDouble(index)) * t
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/animation/AnimationSpecs.kt

@@ -0,0 +1,141 @@
+package com.pythonnative.runtime.animation
+
+import org.json.JSONArray
+import org.json.JSONObject
+import kotlin.math.max
+import kotlin.math.sqrt
+
+/**
+ * Pure-Kotlin decoding of animation specs (`pn.Animated.timing`,
+ * `spring`, `decay`) and their mapping to Android animator parameters.
+ * Kept free of Android types so the math is unit-testable.
+ */
+object AnimationSpecs {
+    /** `FlingAnimation` scales `friction` by this constant internally (`DragForce`). */
+    const val FLING_FRICTION_SCALE = 4.2
+
+    /** Easing curves identical to the Python ticker's `_EASINGS`. */
+    val EASINGS: Map<String, (Float) -> Float> = mapOf(
+        "linear" to { t -> t },
+        "ease" to { t -> 3f * t * t - 2f * t * t * t },
+        "ease_in" to { t -> t * t },
+        "ease_out" to { t -> 1f - (1f - t) * (1f - t) },
+        "ease_in_out" to { t -> 3f * t * t - 2f * t * t * t },
+        "ease_in_quad" to { t -> t * t },
+        "ease_out_quad" to { t -> 1f - (1f - t) * (1f - t) },
+        "bounce" to { t -> bounceOut(t) },
+    )
+
+    /** Decoded `timing` parameters. */
+    data class Timing(val from: Double, val to: Double, val durationMs: Long, val easing: Any?)
+
+    /** Decoded `spring` parameters mapped to `SpringForce` terms. */
+    data class Spring(
+        val from: Double,
+        val to: Double,
+        /** `stiffness / mass`, so the natural frequency matches the Python integrator. */
+        val stiffness: Double,
+        /** `damping / (2 * sqrt(stiffness * mass))`. */
+        val dampingRatio: Double,
+        /** Units per second. */
+        val initialVelocity: Double,
+    )
+
+    /** Decoded `decay` parameters mapped to `FlingAnimation` terms. */
+    data class Decay(
+        val from: Double,
+        /** Units per second (Python specs use units per millisecond). */
+        val startVelocity: Double,
+        /** `FlingAnimation.setFriction` value reproducing `v(t) = v0 * exp(-k * 1000 * t)`. */
+        val friction: Double,
+        /** Where the value settles: `from + v0 / (k * 1000)`. */
+        val projectedFinal: Double,
+    )
+
+    fun kind(spec: JSONObject): String = spec.optString("kind", "")
+
+    fun timing(spec: JSONObject): Timing = Timing(
+        from = spec.optDouble("from", 0.0),
+        to = spec.optDouble("to", 0.0),
+        durationMs = max(0L, spec.optDouble("duration_ms", 300.0).toLong()),
+        easing = spec.opt("easing"),
+    )
+
+    fun spring(spec: JSONObject): Spring {
+        val stiffness = max(1e-6, spec.optDouble("stiffness", 100.0))
+        val damping = max(0.0, spec.optDouble("damping", 10.0))
+        val mass = max(1e-6, spec.optDouble("mass", 1.0))
+        return Spring(
+            from = spec.optDouble("from", 0.0),
+            to = spec.optDouble("to", 0.0),
+            stiffness = stiffness / mass,
+            dampingRatio = dampingRatio(stiffness, damping, mass),
+            initialVelocity = spec.optDouble("initial_velocity", 0.0),
+        )
+    }
+
+    /** `damping / (2 * sqrt(stiffness * mass))`. */
+    fun dampingRatio(stiffness: Double, damping: Double, mass: Double): Double =
+        damping / (2.0 * sqrt(max(1e-12, stiffness * mass)))
+
+    fun decay(spec: JSONObject): Decay {
+        val v0PerMs = spec.optDouble("velocity", 0.0)
+        val k = max(1e-6, spec.optDouble("deceleration", 0.997))
+        val from = spec.optDouble("from", 0.0)
+        return Decay(
+            from = from,
+            startVelocity = v0PerMs * 1000.0,
+            friction = decayFriction(k),
+            projectedFinal = from + v0PerMs / (k * 1000.0),
+        )
+    }
+
+    /**
+     * The Python ticker decays velocity as `exp(-k * dt_ms)`, that is
+     * `exp(-k * 1000 * t_s)`. `FlingAnimation` decays as
+     * `exp(-4.2 * friction * t_s)`, so `friction = k * 1000 / 4.2`.
+     */
+    fun decayFriction(deceleration: Double): Double = deceleration * 1000.0 / FLING_FRICTION_SCALE
+
+    /**
+     * Resolve an easing value. Names map to [EASINGS]; a four-number
+     * array is returned as cubic-bezier control points (`DoubleArray`)
+     * for the caller to build a `PathInterpolator`. Unknown names fall
+     * back to `ease_in_out` like the Python ticker.
+     */
+    fun resolveEasing(easing: Any?): Any {
+        if (easing is JSONArray && easing.length() == 4) {
+            return DoubleArray(4) { easing.optDouble(it, 0.0) }
+        }
+        if (easing is String) {
+            val trimmed = easing.trim()
+            if (trimmed.startsWith("cubic-bezier(") || trimmed.startsWith("cubic_bezier(")) {
+                val inner = trimmed.substringAfter('(').substringBeforeLast(')')
+                val parts = inner.split(',').mapNotNull { it.trim().toDoubleOrNull() }
+                if (parts.size == 4) return parts.toDoubleArray()
+            }
+            return EASINGS[trimmed] ?: EASINGS.getValue("ease_in_out")
+        }
+        return EASINGS.getValue("ease_in_out")
+    }
+
+    private fun bounceOut(t: Float): Float {
+        val n1 = 7.5625f
+        val d1 = 2.75f
+        return when {
+            t < 1f / d1 -> n1 * t * t
+            t < 2f / d1 -> {
+                val u = t - 1.5f / d1
+                n1 * u * u + 0.75f
+            }
+            t < 2.5f / d1 -> {
+                val u = t - 2.25f / d1
+                n1 * u * u + 0.9375f
+            }
+            else -> {
+                val u = t - 2.625f / d1
+                n1 * u * u + 0.984375f
+            }
+        }
+    }
+}