pythonnative 0.40.0__cp313-cp313-win_amd64.whl

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

@@ -0,0 +1,257 @@
+package com.pythonnative.runtime.animation
+
+import android.animation.Animator
+import android.animation.AnimatorListenerAdapter
+import android.animation.ArgbEvaluator
+import android.animation.TimeInterpolator
+import android.animation.ValueAnimator
+import android.view.View
+import android.view.animation.PathInterpolator
+import android.widget.TextView
+import androidx.dynamicanimation.animation.DynamicAnimation
+import androidx.dynamicanimation.animation.FlingAnimation
+import androidx.dynamicanimation.animation.FloatPropertyCompat
+import androidx.dynamicanimation.animation.SpringAnimation
+import androidx.dynamicanimation.animation.SpringForce
+import com.pythonnative.runtime.PNBridge
+import com.pythonnative.runtime.bridge.JsonUtil
+import com.pythonnative.runtime.bridge.PNLog
+import com.pythonnative.runtime.bridge.ViewRecord
+import com.pythonnative.runtime.components.PNColor
+import com.pythonnative.runtime.components.ViewStyler
+import org.json.JSONObject
+
+/**
+ * Native driver for `animate` requests on the animatable props
+ * (`opacity`, `background_color`, `translate_x`, `translate_y`,
+ * `scale`, `scale_x`, `scale_y`, `rotate`, plus `color` for text).
+ *
+ * `timing` runs on a `ValueAnimator`, `spring` on a `SpringAnimation`,
+ * and `decay` on a `FlingAnimation`. Completion is reported with
+ * `callback("animation", 0, "", {"id": n, "finished": bool})`.
+ */
+object PNAnimator {
+    private class Running(val view: View, val prop: String, val cancel: () -> Unit)
+
+    private val running = HashMap<Long, Running>()
+
+    /** Handle one request object; returns the JSON reply string per the spec. */
+    fun handle(record: ViewRecord, request: JSONObject): String? {
+        val view = record.view
+        return when (request.optString("op")) {
+            "graph" -> { AnimationGraph.install(request.getJSONObject("graph")); null }
+            "set" -> {
+                record.manager.setAnimatedProperty(view, request.optString("prop"), request.opt("value"))
+                null
+            }
+            "start" -> {
+                val id = request.optLong("id")
+                val spec = request.optJSONObject("spec") ?: JSONObject()
+                val ok = record.manager.startAnimation(view, id, request.optString("prop"), spec)
+                JSONObject().put("ok", ok).toString()
+            }
+            "cancel" -> {
+                val value = record.manager.cancelAnimation(view, request.optLong("id"))
+                if (value == null) null else JSONObject().put("value", JsonUtil.wrap(value)).toString()
+            }
+            else -> null
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // Property access
+    // ------------------------------------------------------------------
+
+    /** Apply one animation frame to `view`. Unknown props are ignored. */
+    fun setProperty(view: View, prop: String, value: Any?) {
+        if (JsonUtil.isNull(value)) return
+        if (prop.startsWith("_pn_graph:")) {
+            AnimationGraph.set(prop.substringAfter(":").toLong(), JsonUtil.toDouble(value))
+            return
+        }
+        try {
+            when (prop) {
+                "opacity" -> view.alpha = JsonUtil.toDouble(value).toFloat()
+                "translate_x" -> view.translationX = px(JsonUtil.toDouble(value))
+                "translate_y" -> view.translationY = px(JsonUtil.toDouble(value))
+                "scale" -> {
+                    val s = JsonUtil.toDouble(value).toFloat()
+                    view.scaleX = s
+                    view.scaleY = s
+                }
+                "scale_x" -> view.scaleX = JsonUtil.toDouble(value).toFloat()
+                "scale_y" -> view.scaleY = JsonUtil.toDouble(value).toFloat()
+                "rotate" -> view.rotation = ViewStyler.angleDegrees(value)
+                "background_color" -> ViewStyler.setAnimatedBackground(view, value)
+                "color" -> (view as? TextView)?.setTextColor(PNColor.parseOr(value, 0xFF000000.toInt()))
+            }
+        } catch (e: Exception) {
+            PNLog.swallowed("PNAnimator.setProperty", e)
+        }
+    }
+
+    /** Read the current (presentation) value of an animatable prop, or `null`. */
+    fun readProperty(view: View, prop: String): Any? = if (prop.startsWith("_pn_graph:")) AnimationGraph.value(prop.substringAfter(":").toLong()) else when (prop) {
+        "opacity" -> view.alpha.toDouble()
+        "translate_x" -> view.translationX / PNBridge.density().toDouble()
+        "translate_y" -> view.translationY / PNBridge.density().toDouble()
+        "scale", "scale_x" -> view.scaleX.toDouble()
+        "scale_y" -> view.scaleY.toDouble()
+        "rotate" -> view.rotation.toDouble()
+        else -> null
+    }
+
+    // ------------------------------------------------------------------
+    // Start / cancel
+    // ------------------------------------------------------------------
+
+    /** Start a native animation; `false` means Python should tick it instead. */
+    fun start(view: View, id: Long, prop: String, spec: JSONObject): Boolean {
+        cancelQuietly(id)
+        return try {
+            when (AnimationSpecs.kind(spec)) {
+                "timing" -> startTiming(view, id, prop, spec)
+                "spring" -> startSpring(view, id, prop, spec)
+                "decay" -> startDecay(view, id, prop, spec)
+                else -> false
+            }
+        } catch (e: Exception) {
+            PNLog.rateLimited("anim-start", "native animation failed for '$prop'", e)
+            running.remove(id)
+            false
+        }
+    }
+
+    /** Cancel `id` and return the presentation value of its prop, if readable. */
+    fun cancel(id: Long): Any? {
+        val entry = running.remove(id) ?: return null
+        try {
+            entry.cancel()
+        } catch (e: Exception) {
+            PNLog.swallowed("PNAnimator.cancel", e)
+        }
+        return readProperty(entry.view, entry.prop)
+    }
+
+    private fun cancelQuietly(id: Long) {
+        running.remove(id)?.let { runCatching { it.cancel() } }
+    }
+
+    private fun complete(id: Long, finished: Boolean) {
+        if (running.remove(id) == null) return
+        PNBridge.callPython("animation", 0, "", JSONObject().put("id", id).put("finished", finished).toString())
+    }
+
+    private fun startTiming(view: View, id: Long, prop: String, spec: JSONObject): Boolean {
+        val timing = AnimationSpecs.timing(spec)
+        val animator: ValueAnimator
+        if (prop == "background_color") {
+            val from = PNColor.parse(spec.opt("from")) ?: return false
+            val to = PNColor.parse(spec.opt("to")) ?: return false
+            animator = ValueAnimator.ofObject(ArgbEvaluator(), from, to)
+            animator.addUpdateListener { ViewStyler.setAnimatedBackground(view, it.animatedValue as Int) }
+        } else if (prop == "color") {
+            val from = PNColor.parse(spec.opt("from")) ?: return false
+            val to = PNColor.parse(spec.opt("to")) ?: return false
+            animator = ValueAnimator.ofObject(ArgbEvaluator(), from, to)
+            animator.addUpdateListener { (view as? TextView)?.setTextColor(it.animatedValue as Int) }
+        } else {
+            if (!isFloatProp(prop)) return false
+            animator = ValueAnimator.ofFloat(timing.from.toFloat(), timing.to.toFloat())
+            animator.addUpdateListener { setProperty(view, prop, it.animatedValue as Float) }
+        }
+        animator.duration = timing.durationMs
+        animator.interpolator = interpolator(timing.easing)
+        var cancelled = false
+        animator.addListener(object : AnimatorListenerAdapter() {
+            override fun onAnimationCancel(animation: Animator) {
+                cancelled = true
+            }
+
+            override fun onAnimationEnd(animation: Animator) {
+                complete(id, !cancelled)
+            }
+        })
+        running[id] = Running(view, prop) { animator.cancel() }
+        animator.start()
+        return true
+    }
+
+    private fun startSpring(view: View, id: Long, prop: String, spec: JSONObject): Boolean {
+        val params = AnimationSpecs.spring(spec)
+        val property = floatProperty(prop) ?: return false
+        val scale = unitScale(prop)
+        val anim = SpringAnimation(view, property, (params.to * scale).toFloat())
+        anim.spring = SpringForce((params.to * scale).toFloat())
+            .setStiffness(params.stiffness.toFloat())
+            .setDampingRatio(params.dampingRatio.toFloat())
+        anim.setStartValue((params.from * scale).toFloat())
+        anim.setStartVelocity((params.initialVelocity * scale).toFloat())
+        anim.addEndListener { _, canceled, _, _ -> complete(id, !canceled) }
+        running[id] = Running(view, prop) { anim.cancel() }
+        anim.start()
+        return true
+    }
+
+    private fun startDecay(view: View, id: Long, prop: String, spec: JSONObject): Boolean {
+        val params = AnimationSpecs.decay(spec)
+        val property = floatProperty(prop) ?: return false
+        val scale = unitScale(prop)
+        val anim = FlingAnimation(view, property)
+        anim.setStartValue((params.from * scale).toFloat())
+        anim.setStartVelocity((params.startVelocity * scale).toFloat())
+        anim.friction = params.friction.toFloat()
+        anim.addEndListener { _, canceled, _, _ -> complete(id, !canceled) }
+        running[id] = Running(view, prop) { anim.cancel() }
+        anim.start()
+        return true
+    }
+
+    // ------------------------------------------------------------------
+    // Helpers
+    // ------------------------------------------------------------------
+
+    private fun px(dp: Double): Float = (dp * PNBridge.density()).toFloat()
+
+    private fun isFloatProp(prop: String): Boolean =
+        prop.startsWith("_pn_graph:") || prop in setOf("opacity", "translate_x", "translate_y", "scale", "scale_x", "scale_y", "rotate")
+
+    /** Multiplier from spec units to native units (dp to px for translations). */
+    private fun unitScale(prop: String): Double =
+        if (prop == "translate_x" || prop == "translate_y") PNBridge.density().toDouble() else 1.0
+
+    /** A `FloatPropertyCompat` for physics animations; `null` for unsupported props. */
+    private fun floatProperty(prop: String): FloatPropertyCompat<View>? = if (prop.startsWith("_pn_graph:")) object : FloatPropertyCompat<View>(prop) {
+        override fun getValue(view: View): Float = AnimationGraph.value(prop.substringAfter(":").toLong()).toFloat()
+        override fun setValue(view: View, value: Float) { AnimationGraph.set(prop.substringAfter(":").toLong(), value.toDouble()) }
+    } else when (prop) {
+        "opacity" -> DynamicAnimation.ALPHA
+        "translate_x" -> DynamicAnimation.TRANSLATION_X
+        "translate_y" -> DynamicAnimation.TRANSLATION_Y
+        "scale_x" -> DynamicAnimation.SCALE_X
+        "scale_y" -> DynamicAnimation.SCALE_Y
+        "rotate" -> DynamicAnimation.ROTATION
+        "scale" -> object : FloatPropertyCompat<View>("pnScale") {
+            override fun getValue(v: View): Float = v.scaleX
+            override fun setValue(v: View, value: Float) {
+                v.scaleX = value
+                v.scaleY = value
+            }
+        }
+        // Color props are not floats; physics specs on them fall back to the Python ticker.
+        else -> null
+    }
+
+    private fun interpolator(easing: Any?): TimeInterpolator {
+        return when (val resolved = AnimationSpecs.resolveEasing(easing)) {
+            is DoubleArray -> PathInterpolator(
+                resolved[0].toFloat(), resolved[1].toFloat(), resolved[2].toFloat(), resolved[3].toFloat(),
+            )
+            else -> {
+                @Suppress("UNCHECKED_CAST")
+                val fn = resolved as (Float) -> Float
+                TimeInterpolator { t -> fn(t) }
+            }
+        }
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/bridge/CommitState.kt

@@ -0,0 +1,106 @@
+package com.pythonnative.runtime.bridge
+
+import org.json.JSONArray
+import org.json.JSONObject
+
+/** Revision and structural validation before native mutation. */
+class CommitState {
+    private var application = ""
+    private var surface = 0
+    private var revision = 0
+    private var live = mutableSetOf<Long>()
+    private var parents = mutableMapOf<Long, Long>()
+    private var types = mutableMapOf<Long, String>()
+    private var failed = false
+
+    private var sequence = 0L
+    @Synchronized fun event(args: JSONArray, editRevision: Long = 0): String = JSONObject()
+        .put("application", application).put("surface", surface).put("revision", revision)
+        .put("sequence", ++sequence).put("args", args).put("edit_revision", editRevision).toString()
+
+    fun apply(json: String, applier: TransactionApplier): String {
+        try {
+            val envelope = JSONObject(json)
+            val app = envelope.getString("application")
+            val target = envelope.getInt("surface")
+            val next = envelope.getInt("revision")
+            require(envelope.getInt("version") == 2 && app.isNotEmpty() && target > 0) { "invalid v2 envelope" }
+            val replacing = app != application
+            require(next == (if (replacing) 1 else revision + 1)) { "stale revision" }
+            require(replacing || (!failed && target == surface)) { "failed or foreign surface" }
+            val tags = if (replacing) mutableSetOf() else live.toMutableSet()
+            val links = if (replacing) mutableMapOf() else parents.toMutableMap()
+            val names = if (replacing) mutableMapOf() else types.toMutableMap()
+            val raw = envelope.getJSONArray("ops")
+            val ops = ArrayList<Op>()
+            for (i in 0 until raw.length()) {
+                val parts = raw.getJSONArray(i)
+                val code = parts.getString(0)
+                require(parts.length() == mapOf("c" to 4, "u" to 3, "i" to 4, "d" to 2, "f" to 6)[code]) { "invalid operation" }
+                val tag = parts.getLong(1)
+                require(tag > 0 && parts.getDouble(1) == tag.toDouble()) { "invalid tag" }
+                if (code == "c") {
+                    require(tags.add(tag) && parts.getString(2).isNotEmpty()) { "duplicate create" }
+                    parts.getJSONObject(3)
+                    require(PNRegistry.managerFor(parts.getString(2)) != null) { "unknown component" }
+                    require(com.pythonnative.generated.PNContracts.validate(parts.getString(2), parts.getJSONObject(3))) { "invalid typed props" }
+                    names[tag] = parts.getString(2)
+                } else {
+                    require(tag in tags) { "unknown tag" }
+                    when (code) {
+                        "u" -> {
+                            val props = parts.getJSONObject(2)
+                            val type = names[tag]
+                            require(type == null || com.pythonnative.generated.PNContracts.validate(type, props, true)) { "invalid typed update" }
+                        }
+                        "i" -> {
+                            val child = parts.getLong(2)
+                            require(child in tags && parts.getInt(3) >= 0) { "invalid insertion" }
+                            var ancestor: Long? = tag
+                            while (ancestor != null) {
+                                require(ancestor != child) { "cycle" }
+                                ancestor = links[ancestor]
+                            }
+                            require(parts.getInt(3) <= links.count { (key, value) -> value == tag && key != child }) { "insertion index exceeds child count" }
+                            links[child] = tag
+                        }
+                        "d" -> {
+                            require(tag !in links.values) { "destroy children first" }
+                            tags.remove(tag)
+                            names.remove(tag)
+                            links.remove(tag)
+                        }
+                        "f" -> {
+                            for (j in 2..5) require(parts.getDouble(j).isFinite()) { "invalid frame" }
+                            require(parts.getDouble(4) >= 0 && parts.getDouble(5) >= 0) { "negative size" }
+                        }
+                    }
+                }
+                ops.add(PNTransaction.decodeOp(parts))
+            }
+            try {
+                if (replacing) {
+                    for (tag in live) applier.applyOp(Op.Destroy(tag))
+                    com.pythonnative.runtime.layout.NativeLayout.reset()
+                }
+                for (op in ops) applier.applyOp(op)
+                com.pythonnative.runtime.layout.NativeLayout.observe(ops)
+            } catch (error: Exception) {
+                failed = true
+                for (tag in tags) runCatching { applier.applyOp(Op.Destroy(tag)) }
+                throw error
+            }
+            application = app
+            surface = target
+            revision = next
+            live = tags
+            parents = links
+            types = names
+            failed = false
+            return JSONObject().put("ok", true).put("application", app)
+                .put("surface", target).put("revision", next).toString()
+        } catch (error: Exception) {
+            return JSONObject().put("ok", false).put("error", error.message).toString()
+        }
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/bridge/JsonUtil.kt

@@ -0,0 +1,175 @@
+package com.pythonnative.runtime.bridge
+
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Helpers for the JSON shapes the bridge exchanges with Python.
+ *
+ * Python normalizes values before encoding: `math.inf` arrives as the
+ * string `"inf"`, removed props arrive as JSON `null`, and tuples and
+ * frozensets arrive as arrays. These helpers hide those conventions.
+ */
+object JsonUtil {
+    /** Whether `value` is absent or an explicit JSON null. */
+    fun isNull(value: Any?): Boolean = value == null || value === JSONObject.NULL
+
+    /** Coerce a JSON value to a double; `"inf"` / `"-inf"` become infinities. */
+    fun toDoubleOrNull(value: Any?): Double? {
+        return when (value) {
+            null, JSONObject.NULL -> null
+            is Number -> value.toDouble()
+            is Boolean -> if (value) 1.0 else 0.0
+            is String -> {
+                val s = value.trim()
+                when (s.lowercase()) {
+                    "inf", "+inf", "infinity", "+infinity" -> Double.POSITIVE_INFINITY
+                    "-inf", "-infinity" -> Double.NEGATIVE_INFINITY
+                    "nan" -> Double.NaN
+                    else -> s.toDoubleOrNull()
+                }
+            }
+            else -> null
+        }
+    }
+
+    /** Coerce a JSON value to a double with `default` for missing or unparseable input. */
+    fun toDouble(value: Any?, default: Double = 0.0): Double = toDoubleOrNull(value) ?: default
+
+    /** Coerce a JSON value to an int (truncating), with `default` for bad input. */
+    fun toInt(value: Any?, default: Int = 0): Int {
+        val d = toDoubleOrNull(value) ?: return default
+        if (d.isNaN() || d.isInfinite()) return default
+        return d.toInt()
+    }
+
+    /** Coerce a JSON value to a long (truncating), with `default` for bad input. */
+    fun toLong(value: Any?, default: Long = 0L): Long {
+        return when (value) {
+            is Number -> value.toLong()
+            else -> {
+                val d = toDoubleOrNull(value) ?: return default
+                if (d.isNaN() || d.isInfinite()) default else d.toLong()
+            }
+        }
+    }
+
+    /** Python-style truthiness for JSON values. */
+    fun truthy(value: Any?): Boolean {
+        return when (value) {
+            null, JSONObject.NULL -> false
+            is Boolean -> value
+            is Number -> value.toDouble() != 0.0
+            is String -> value.isNotEmpty()
+            is JSONArray -> value.length() > 0
+            is JSONObject -> value.length() > 0
+            else -> true
+        }
+    }
+
+    /** `value` as a string, or `null` when absent or JSON null. */
+    fun stringOrNull(value: Any?): String? = if (isNull(value)) null else value.toString()
+
+    /** Copy `changed` into `target`, keeping explicit nulls as [JSONObject.NULL]. */
+    fun merge(target: JSONObject, changed: JSONObject) {
+        val keys = changed.keys()
+        while (keys.hasNext()) {
+            val key = keys.next()
+            target.put(key, changed.opt(key) ?: JSONObject.NULL)
+        }
+    }
+
+    /** Convert a [JSONArray] to a Kotlin list (JSON nulls become `null`). */
+    fun toList(array: JSONArray?): List<Any?> {
+        if (array == null) return emptyList()
+        val out = ArrayList<Any?>(array.length())
+        for (i in 0 until array.length()) {
+            val v = array.opt(i)
+            out.add(if (v === JSONObject.NULL) null else v)
+        }
+        return out
+    }
+
+    /** Convert a [JSONObject] to a Kotlin map (JSON nulls become `null`). */
+    fun toMap(obj: JSONObject?): Map<String, Any?> {
+        if (obj == null) return emptyMap()
+        val out = LinkedHashMap<String, Any?>()
+        val keys = obj.keys()
+        while (keys.hasNext()) {
+            val key = keys.next()
+            val v = obj.opt(key)
+            out[key] = if (v === JSONObject.NULL) null else v
+        }
+        return out
+    }
+
+    /** Wrap a Kotlin value into something `org.json` can hold (maps, lists, nulls). */
+    fun wrap(value: Any?): Any {
+        return when (value) {
+            null -> JSONObject.NULL
+            is JSONObject, is JSONArray, is String, is Boolean -> value
+            is Float -> if (value.isFinite()) value.toDouble() else JSONObject.NULL
+            is Double -> if (value.isFinite()) value else JSONObject.NULL
+            is Number -> value
+            is Map<*, *> -> {
+                val obj = JSONObject()
+                for ((k, v) in value) obj.put(k.toString(), wrap(v))
+                obj
+            }
+            is Iterable<*> -> {
+                val arr = JSONArray()
+                for (v in value) arr.put(wrap(v))
+                arr
+            }
+            is Array<*> -> wrap(value.asList())
+            is DoubleArray -> wrap(value.asList())
+            is FloatArray -> wrap(value.asList())
+            is IntArray -> wrap(value.asList())
+            else -> value.toString()
+        }
+    }
+
+    /** Build a JSON array of positional arguments. */
+    fun args(vararg values: Any?): JSONArray {
+        val arr = JSONArray()
+        for (v in values) arr.put(wrap(v))
+        return arr
+    }
+
+    /** Encode a command or module result as a JSON string; `null` stays `null`. */
+    fun encode(value: Any?): String? {
+        if (value == null || value === JSONObject.NULL) return null
+        return when (val wrapped = wrap(value)) {
+            is JSONObject, is JSONArray -> wrapped.toString()
+            is String -> JSONObject.quote(wrapped)
+            else -> wrapped.toString()
+        }
+    }
+}
+
+/** The value under `key`, or `null` for missing keys and JSON nulls. */
+fun JSONObject.value(key: String): Any? {
+    val v = opt(key) ?: return null
+    return if (v === JSONObject.NULL) null else v
+}
+
+/** String prop or `null`. */
+fun JSONObject.str(key: String): String? = JsonUtil.stringOrNull(opt(key))
+
+/** Numeric prop (accepting `"inf"`) or `null`. */
+fun JSONObject.num(key: String): Double? = JsonUtil.toDoubleOrNull(opt(key))
+
+/** Boolean prop using Python truthiness, or `null` when absent. */
+fun JSONObject.bool(key: String): Boolean? {
+    val v = value(key) ?: return null
+    return JsonUtil.truthy(v)
+}
+
+/** Object prop or `null`. */
+fun JSONObject.obj(key: String): JSONObject? = value(key) as? JSONObject
+
+/** Array prop or `null`. */
+fun JSONObject.arr(key: String): JSONArray? = value(key) as? JSONArray
+
+/** Whether the prop is present with a non-null value. */
+fun JSONObject.present(key: String): Boolean = value(key) != null

pythonnative/native/android/src/main/java/com/pythonnative/runtime/bridge/MainThread.kt

@@ -0,0 +1,40 @@
+package com.pythonnative.runtime.bridge
+
+import android.os.Handler
+import android.os.Looper
+
+/** Main-looper helpers shared by the bridge, modules, and managers. */
+object MainThread {
+    private val handler: Handler by lazy { Handler(Looper.getMainLooper()) }
+
+    /** Run UI work synchronously from the application worker. */
+    fun <T> call(body: () -> T): T {
+        if (isMain()) return body()
+        val task = java.util.concurrent.FutureTask<T> { body() }
+        handler.post(task)
+        return task.get()
+    }
+
+    /** Whether the current thread is the main thread. */
+    fun isMain(): Boolean = Looper.myLooper() == Looper.getMainLooper()
+
+    /** Post `runnable` to the main looper. */
+    fun post(runnable: Runnable) {
+        handler.post(runnable)
+    }
+
+    /** Post `runnable` to the main looper after `delayMs`. */
+    fun postDelayed(runnable: Runnable, delayMs: Long) {
+        handler.postDelayed(runnable, delayMs)
+    }
+
+    /** Remove a pending `runnable`. */
+    fun remove(runnable: Runnable) {
+        handler.removeCallbacks(runnable)
+    }
+
+    /** Run `runnable` inline when already on the main thread, otherwise post it. */
+    fun runOnMain(runnable: Runnable) {
+        if (isMain()) runnable.run() else post(runnable)
+    }
+}

pythonnative/native/android/src/main/java/com/pythonnative/runtime/bridge/PNLog.kt

@@ -0,0 +1,33 @@
+package com.pythonnative.runtime.bridge
+
+import android.util.Log
+
+/** Rate-limited logging so a hot failing op cannot flood logcat. */
+object PNLog {
+    const val TAG = "PythonNative"
+
+    private const val BURST = 5
+    private const val EVERY = 100
+    private val counts = HashMap<String, Int>()
+    private val once = HashSet<String>()
+
+    /** Log `message` for `key`, letting the first few through and then every 100th. */
+    fun rateLimited(key: String, message: String, error: Throwable? = null) {
+        val n = (counts[key] ?: 0) + 1
+        counts[key] = n
+        if (n <= BURST || n % EVERY == 0) {
+            val suffix = if (n > BURST) " (x$n)" else ""
+            if (error != null) Log.e(TAG, message + suffix, error) else Log.e(TAG, message + suffix)
+        }
+    }
+
+    /** Log `message` at most once per `key`. */
+    fun once(key: String, message: String) {
+        if (once.add(key)) Log.w(TAG, message)
+    }
+
+    /** Log a swallowed exception at debug level. */
+    fun swallowed(where: String, error: Throwable) {
+        Log.d(TAG, "$where: ${error.javaClass.simpleName}: ${error.message}")
+    }
+}