honch-micropython 0.3.0__py3-none-any.whl

honch/__init__.py

@@ -0,0 +1,29 @@
+from .client import Honch
+from .errors import (
+    CompressionUnavailableError,
+    HonchError,
+    InvalidArgumentError,
+    NotInitializedError,
+    OfflineError,
+    RateLimitedError,
+    RejectedError,
+    ServerError,
+    StorageError,
+    TransportError,
+)
+
+__version__ = "0.3.0"
+
+__all__ = (
+    "Honch",
+    "HonchError",
+    "InvalidArgumentError",
+    "StorageError",
+    "TransportError",
+    "OfflineError",
+    "RateLimitedError",
+    "ServerError",
+    "RejectedError",
+    "CompressionUnavailableError",
+    "NotInitializedError",
+)

honch/client.py

@@ -0,0 +1,346 @@
+try:
+    import _honch_core
+except ImportError:
+    _honch_core = None
+
+from .config import HonchConfig
+from .errors import (
+    HonchError,
+    InvalidArgumentError,
+    NotInitializedError,
+    OfflineError,
+    RateLimitedError,
+    RejectedError,
+    ServerError,
+    StorageError,
+    TransportError,
+)
+from .validation import (
+    require_distinct_id,
+    require_event_name,
+    require_properties,
+    require_text,
+    require_value,
+)
+
+# Cap how much of the Python stack we format before handing it to the C core.
+# The core's $crash `backtrace` is an ALL-OR-NOTHING field: honch_append_crash_string
+# emits it only when its byte length is within HONCH_FAULT_BACKTRACE_MAX_BYTES and
+# DROPS the whole property otherwise (it does not truncate). So we format
+# CRASH-SITE-FIRST and keep only the leading frames that fit the byte budget,
+# dropping the OUTERMOST frames — the crash site survives, not the entry point.
+_CRASH_BACKTRACE_MAX_FRAMES = 10
+# MUST match HONCH_FAULT_BACKTRACE_MAX_BYTES in core/src/honch_core.c. If the core
+# bound changes, change this too (the core silently drops an over-long backtrace).
+_CRASH_BACKTRACE_MAX_BYTES = 192
+_CRASH_BACKTRACE_SEP = " <- "
+
+
+def _format_crash_backtrace(exc):
+    """Format an exception's traceback compact and crash-site-first, e.g.
+    `sensor.py:42 in read <- app.py:10 in loop <- main.py:88 in <module>`.
+
+    On MicroPython the readable backtrace is the Python traceback (already
+    file/line/function-resolved) — there is no coredump to symbolicate — so this
+    is what gives a MicroPython `$crash` the "where", not just the "what".
+
+    Returns the formatted string, or None if it can't be produced. MUST NOT raise:
+    it runs inside the excepthook, where a failure must never displace delivery of
+    the original exception."""
+    try:
+        import sys
+        import io
+
+        buf = io.StringIO()
+        sys.print_exception(exc, buf)  # MicroPython: prints most-recent-call-LAST
+        frames = []
+        for raw in buf.getvalue().split("\n"):
+            line = raw.strip()
+            # "File "main.py", line 42, in read"
+            if not line.startswith("File ") or ", line " not in line:
+                continue
+            try:
+                fname = line.split('"', 2)[1]
+                rest = line.split(", line ", 1)[1]
+                lineno = rest.split(",", 1)[0].strip()
+                func = rest.split(" in ", 1)[1].strip() if " in " in rest else "?"
+                frames.append("%s:%s in %s" % (fname, lineno, func))
+            except Exception:
+                continue
+        if not frames:
+            return None
+        frames.reverse()  # crash site first
+        # Keep crash-site-first frames whose join stays within the core's byte
+        # budget; drop the outermost frames that don't fit (the core would
+        # otherwise drop the entire property). Measure UTF-8 bytes — that's what
+        # the core counts against HONCH_FAULT_BACKTRACE_MAX_BYTES.
+        kept = ""
+        for frame in frames[:_CRASH_BACKTRACE_MAX_FRAMES]:
+            candidate = frame if not kept else kept + _CRASH_BACKTRACE_SEP + frame
+            if len(candidate.encode("utf-8")) > _CRASH_BACKTRACE_MAX_BYTES:
+                break
+            kept = candidate
+        return kept or None
+    except Exception:
+        return None
+
+
+class Honch:
+    def __init__(self, **kwargs):
+        if _honch_core is None:
+            raise ImportError("Honch MicroPython requires firmware built with the _honch_core user C module")
+
+        if (
+            kwargs.get("platform") is not None
+            or kwargs.get("transport") is not None
+            or kwargs.get("battery_callback") is not None
+            or kwargs.get("auto_properties_callback") is not None
+        ):
+            raise InvalidArgumentError("Python adapter hooks are not supported by the C-core MicroPython port")
+
+        self.config = HonchConfig(**kwargs)
+        self._core = _honch_core.Client(_config_to_dict(self.config))
+        self._connectivity_connected = None
+        self._honch_excepthook = None
+        self._previous_excepthook = None
+
+    def get_device_id(self):
+        return self._call("get_device_id")
+
+    def queue_stats(self):
+        return self._call("queue_stats")
+
+    def track(self, event_name, properties=None):
+        require_event_name(event_name)
+        self._call("track", event_name, require_properties(properties))
+
+    def report_log_error(self, message, *, component=None):
+        """Capture a logged error as a bounded, coalesced $error event.
+
+        Intended to be driven automatically (e.g. from a logging.Handler), not
+        sprinkled through application code.
+        """
+        require_text(message, "error message")
+        self._call("report_log_error", component, message)
+
+    def install_error_hook(self):
+        try:
+            import sys
+        except ImportError:
+            return False
+        # Installing twice would stack our wrapper on top of itself and report
+        # every exception once per layer, so a repeat call is a no-op.
+        if self._honch_excepthook is not None:
+            return True
+        previous_hook = getattr(sys, "excepthook", None)
+        if previous_hook is None:
+            return False
+
+        def honch_excepthook(exc_type, exc, tb):
+            try:
+                self._report_crash(exc_type, exc)
+            except Exception:
+                # An excepthook must never raise: a reporting failure must not
+                # replace delivery of the original exception to the next hook.
+                pass
+            finally:
+                previous_hook(exc_type, exc, tb)
+
+        self._previous_excepthook = previous_hook
+        self._honch_excepthook = honch_excepthook
+        sys.excepthook = honch_excepthook
+        return True
+
+    def _report_crash(self, exc_type, exc):
+        """Build and queue a $crash from an exception, including the Python
+        traceback. Shared by install_error_hook() and run()."""
+        report = {
+            "message": str(exc) or repr(exc),
+            "type": getattr(exc_type, "__name__", "Exception"),
+        }
+        backtrace = _format_crash_backtrace(exc)
+        if backtrace:
+            report["backtrace"] = backtrace
+        self._call("report_crash", report)
+
+    def run(self, fn, *args, **kwargs):
+        """Run your entry point with automatic crash capture, then re-raise.
+
+        Any uncaught exception from `fn` is reported as a $crash (with the Python
+        traceback), flushed so a fatal crash is delivered before the program exits,
+        and then re-raised so behavior is unchanged. Returns `fn`'s result on
+        success.
+
+        Unlike install_error_hook(), this works on EVERY MicroPython build: it uses
+        a plain try/except, not sys.excepthook (which stock firmware often omits).
+        It captures exceptions that propagate out of `fn` — wrap your top-level
+        entry point / main loop with it.
+        """
+        try:
+            return fn(*args, **kwargs)
+        except Exception as exc:
+            try:
+                self._report_crash(type(exc), exc)
+                self.flush()
+            except Exception:
+                # Reporting/flush failure must never mask the original exception.
+                pass
+            raise
+
+    def uninstall_error_hook(self):
+        try:
+            import sys
+        except ImportError:
+            return False
+        if self._honch_excepthook is None:
+            return False
+        # Only restore if our hook is still the active one; if something was
+        # installed on top of us we cannot safely splice ourselves out.
+        if getattr(sys, "excepthook", None) is self._honch_excepthook:
+            sys.excepthook = self._previous_excepthook
+        self._honch_excepthook = None
+        self._previous_excepthook = None
+        return True
+
+    def identify(self, distinct_id, traits=None):
+        require_distinct_id(distinct_id)
+        self._call("identify", distinct_id, require_properties(traits))
+
+    def set_property(self, key, value=None):
+        require_text(key, "property key")
+        self._call("set_property", key, require_value(value))
+
+    def session_start(self, session_name=None):
+        if session_name is not None:
+            session_name = str(session_name)
+        self._call("session_start", session_name)
+
+    def session_end(self):
+        self._call("session_end")
+
+    def connectivity_changed(self, connected):
+        if connected is not True and connected is not False:
+            raise InvalidArgumentError("connected must be a boolean")
+        if self._connectivity_connected == connected:
+            return
+        self._call("connectivity_changed", connected)
+        self._connectivity_connected = connected
+
+    def connected(self):
+        self.connectivity_changed(True)
+
+    def disconnected(self):
+        self.connectivity_changed(False)
+
+    def flush(self):
+        # The C core is never given the Python connectivity *poll* callback (only
+        # connectivity_changed events are forwarded), so it cannot gate on it
+        # itself. Uphold the cross-port flush contract here: flushing while the
+        # callback reports offline raises OfflineError before core is consulted.
+        if not self._connectivity_available():
+            raise OfflineError("offline")
+        self._call("flush")
+
+    def tick(self):
+        if not self._connectivity_available():
+            return
+        self._call("tick")
+
+    def reset(self):
+        self._call("reset")
+        self._connectivity_connected = None
+
+    def shutdown(self):
+        self._call("shutdown")
+
+    def _call(self, name, *args):
+        try:
+            return getattr(self._core, name)(*args)
+        except Exception as exc:
+            _raise_mapped(exc)
+
+    def _connectivity_available(self):
+        callback = self.config.connectivity_callback
+        if callback is None:
+            return True
+        return bool(callback())
+
+
+def _config_to_dict(config):
+    return {
+        "api_key": config.api_key,
+        "endpoint_url": config.endpoint_url,
+        "device_id": config.device_id,
+        "device_model": config.device_model,
+        "firmware_version": config.firmware_version,
+        "environment": config.environment,
+        "event_buffer": config.event_buffer,
+        "batch_size": config.batch_size,
+        "max_queued_events": config.max_queued_events,
+        "max_event_bytes": config.max_event_bytes,
+        "transport_timeout_ms": config.transport_timeout_ms,
+        "flush_interval_seconds": config.flush_interval_seconds,
+        "flush_min_interval_ms": config.flush_min_interval_ms,
+        "flush_event_threshold": config.flush_event_threshold,
+        "flush_retry_initial_ms": config.flush_retry_initial_ms,
+        "flush_retry_max_ms": config.flush_retry_max_ms,
+        "battery_low_threshold": config.battery_low_threshold,
+    }
+
+
+def _raise_mapped(exc):
+    status = getattr(exc, "status", None)
+    if _honch_core is None:
+        raise exc
+
+    if status is None:
+        message = str(exc)
+        status = _STATUS_BY_MESSAGE.get(message)
+        if status is None:
+            # Unknown/unmapped status string (wording drift, or a status with no
+            # table entry): wrap as HonchError so callers can always catch it,
+            # rather than leaking a bare RuntimeError from the C module.
+            raise HonchError(str(exc))
+
+    if status == getattr(_honch_core, "ERROR_INVALID_ARGUMENT", None):
+        raise InvalidArgumentError(str(exc))
+    if status == getattr(_honch_core, "ERROR_IO", None):
+        raise StorageError(str(exc))
+    if status == getattr(_honch_core, "ERROR_RATE_LIMITED", None):
+        raise RateLimitedError(str(exc))
+    if status == getattr(_honch_core, "ERROR_OFFLINE", None):
+        raise OfflineError(str(exc))
+    if status == getattr(_honch_core, "ERROR_SERVER", None):
+        raise ServerError(str(exc))
+    if status == getattr(_honch_core, "ERROR_REJECTED", None):
+        raise RejectedError(str(exc))
+    if status == getattr(_honch_core, "ERROR_NOT_INITIALIZED", None):
+        raise NotInitializedError(str(exc))
+    if status == getattr(_honch_core, "ERROR_TRANSPORT", None) or status == getattr(_honch_core, "ERROR_TIMEOUT", None):
+        raise TransportError(str(exc))
+    if status == getattr(_honch_core, "ERROR_QUEUE_FULL", None):
+        raise StorageError(str(exc))
+    if status == getattr(_honch_core, "ERROR_BUSY", None):
+        raise HonchError(str(exc))
+    if status == getattr(_honch_core, "ERROR_NOT_SUPPORTED", None):
+        raise HonchError(str(exc))
+    raise HonchError(str(exc))
+
+
+_STATUS_BY_MESSAGE = {
+    "invalid argument": getattr(_honch_core, "ERROR_INVALID_ARGUMENT", None),
+    "io error": getattr(_honch_core, "ERROR_IO", None),
+    "transport error": getattr(_honch_core, "ERROR_TRANSPORT", None),
+    "rate limited": getattr(_honch_core, "ERROR_RATE_LIMITED", None),
+    "server error": getattr(_honch_core, "ERROR_SERVER", None),
+    "rejected": getattr(_honch_core, "ERROR_REJECTED", None),
+    "not initialized": getattr(_honch_core, "ERROR_NOT_INITIALIZED", None),
+    "queue full": getattr(_honch_core, "ERROR_QUEUE_FULL", None),
+    "timeout": getattr(_honch_core, "ERROR_TIMEOUT", None),
+    "busy": getattr(_honch_core, "ERROR_BUSY", None),
+    "not supported": getattr(_honch_core, "ERROR_NOT_SUPPORTED", None),
+    "offline": getattr(_honch_core, "ERROR_OFFLINE", None),
+    "out of memory": getattr(_honch_core, "ERROR_OUT_OF_MEMORY", None),
+    "already initialized": getattr(_honch_core, "ERROR_ALREADY_INITIALIZED", None),
+    "internal error": getattr(_honch_core, "ERROR_INTERNAL", None),
+} if _honch_core is not None else {}

honch/config.py

@@ -0,0 +1,74 @@
+from .errors import InvalidArgumentError
+
+
+SDK_VERSION = "0.3.0"
+SDK_PLATFORM = "micropython"
+DEFAULT_ENDPOINT_URL = "https://i.honch.io"
+
+DEFAULT_BATCH_SIZE = 20
+MAX_BATCH_SIZE = 50
+DEFAULT_MAX_QUEUED_EVENTS = 1000
+DEFAULT_MAX_EVENT_BYTES = 8192
+DEFAULT_TRANSPORT_TIMEOUT_MS = 8000
+MAX_TRANSPORT_TIMEOUT_MS = 10000
+DEFAULT_FLUSH_INTERVAL_SECONDS = 120
+DEFAULT_FLUSH_MIN_INTERVAL_MS = 15000
+FLUSH_MIN_INTERVAL_DISABLED_MS = 0xFFFFFFFF
+DEFAULT_FLUSH_EVENT_THRESHOLD = 20
+DEFAULT_FLUSH_RETRY_INITIAL_MS = 1000
+DEFAULT_FLUSH_RETRY_MAX_MS = 300000
+DEFAULT_BATTERY_LOW_THRESHOLD = 15
+
+
+def is_blank(value):
+    return value is None or str(value).strip() == ""
+
+
+class HonchConfig:
+    def __init__(self, **kwargs):
+        required = ("api_key", "device_id", "device_model", "firmware_version", "event_buffer")
+        for key in required:
+            if is_blank(kwargs.get(key)):
+                raise InvalidArgumentError("missing required config: " + key)
+
+        self.api_key = str(kwargs["api_key"])
+        endpoint_url = kwargs.get("endpoint_url")
+        self.endpoint_url = DEFAULT_ENDPOINT_URL if is_blank(endpoint_url) else str(endpoint_url)
+        self.device_id = kwargs.get("device_id")
+        self.device_model = str(kwargs["device_model"])
+        self.firmware_version = str(kwargs["firmware_version"])
+        self.environment = str(kwargs.get("environment") or "production")
+        self.event_buffer = kwargs["event_buffer"]
+        self.batch_size = int(kwargs.get("batch_size") or DEFAULT_BATCH_SIZE)
+        if self.batch_size > MAX_BATCH_SIZE:
+            self.batch_size = MAX_BATCH_SIZE
+        if self.batch_size <= 0:
+            self.batch_size = DEFAULT_BATCH_SIZE
+
+        max_queued_events = kwargs.get("max_queued_events")
+        self.max_queued_events = DEFAULT_MAX_QUEUED_EVENTS if max_queued_events is None else int(max_queued_events)
+        if self.max_queued_events <= 0:
+            raise InvalidArgumentError("max_queued_events must be positive")
+
+        max_event_bytes = kwargs.get("max_event_bytes")
+        self.max_event_bytes = DEFAULT_MAX_EVENT_BYTES if max_event_bytes is None else int(max_event_bytes)
+        if self.max_event_bytes <= 0:
+            raise InvalidArgumentError("max_event_bytes must be positive")
+
+        timeout = kwargs.get("transport_timeout_ms")
+        self.transport_timeout_ms = DEFAULT_TRANSPORT_TIMEOUT_MS if timeout is None else int(timeout)
+        if self.transport_timeout_ms <= 0:
+            raise InvalidArgumentError("transport_timeout_ms must be positive")
+        if self.transport_timeout_ms > MAX_TRANSPORT_TIMEOUT_MS:
+            self.transport_timeout_ms = MAX_TRANSPORT_TIMEOUT_MS
+        self.flush_interval_seconds = int(kwargs.get("flush_interval_seconds") or DEFAULT_FLUSH_INTERVAL_SECONDS)
+        self.flush_min_interval_ms = int(kwargs.get("flush_min_interval_ms") or DEFAULT_FLUSH_MIN_INTERVAL_MS)
+        self.flush_event_threshold = int(kwargs.get("flush_event_threshold") or DEFAULT_FLUSH_EVENT_THRESHOLD)
+        self.flush_retry_initial_ms = int(kwargs.get("flush_retry_initial_ms") or DEFAULT_FLUSH_RETRY_INITIAL_MS)
+        self.flush_retry_max_ms = int(kwargs.get("flush_retry_max_ms") or DEFAULT_FLUSH_RETRY_MAX_MS)
+        if self.flush_retry_max_ms < self.flush_retry_initial_ms:
+            self.flush_retry_max_ms = self.flush_retry_initial_ms
+        self.battery_callback = kwargs.get("battery_callback")
+        self.battery_low_threshold = int(kwargs.get("battery_low_threshold") or DEFAULT_BATTERY_LOW_THRESHOLD)
+        self.auto_properties_callback = kwargs.get("auto_properties_callback")
+        self.connectivity_callback = kwargs.get("connectivity_callback")

honch/errors.py

@@ -0,0 +1,38 @@
+class HonchError(Exception):
+    pass
+
+
+class InvalidArgumentError(HonchError):
+    pass
+
+
+class StorageError(HonchError):
+    pass
+
+
+class TransportError(HonchError):
+    pass
+
+
+class OfflineError(TransportError):
+    pass
+
+
+class RateLimitedError(TransportError):
+    pass
+
+
+class ServerError(TransportError):
+    pass
+
+
+class RejectedError(HonchError):
+    pass
+
+
+class CompressionUnavailableError(HonchError):
+    pass
+
+
+class NotInitializedError(HonchError):
+    pass

honch/validation.py

@@ -0,0 +1,51 @@
+from .errors import InvalidArgumentError
+
+
+MAX_EVENT_NAME = 128
+MAX_DISTINCT_ID = 256
+
+
+def require_text(value, label, max_len=None):
+    # Single source of truth for the layer's "non-blank string, optional max
+    # length" rule. Core is still the final gate (and counts UTF-8 bytes, not
+    # code points), so these checks exist for early, well-attributed errors.
+    if not isinstance(value, str) or value.strip() == "" or (max_len is not None and len(value) > max_len):
+        raise InvalidArgumentError("invalid " + label)
+
+
+def require_event_name(event):
+    require_text(event, "event name", MAX_EVENT_NAME)
+
+
+def require_distinct_id(distinct_id):
+    require_text(distinct_id, "distinct_id", MAX_DISTINCT_ID)
+
+
+def require_properties(properties):
+    if properties is None:
+        return {}
+    if not isinstance(properties, dict):
+        raise InvalidArgumentError("properties must be a dict")
+    _validate_typed_value(properties)
+    return dict(properties)
+
+
+def require_value(value):
+    _validate_typed_value(value)
+    return value
+
+
+def _validate_typed_value(value):
+    if value is None or isinstance(value, (bool, int, float, str, bytes)):
+        return
+    if isinstance(value, (list, tuple)):
+        for item in value:
+            _validate_typed_value(item)
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise InvalidArgumentError("property keys must be strings")
+            _validate_typed_value(item)
+        return
+    raise InvalidArgumentError("unsupported property value")

honch_micropython-0.3.0.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: honch-micropython
+Version: 0.3.0
+Summary: Honch analytics SDK for MicroPython
+Author-email: Honch <support@honch.io>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/honch-io/SDK
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Honch MicroPython SDK
+
+Stable MicroPython wrapper for the canonical Honch C core. The Python package keeps a small `honch.Honch` API while behavior comes from the same shared sources used by the ESP-IDF and POSIX ports.
+
+## Status
+
+Stable `0.3.0`. The SDK is not standalone pure Python; firmware must be built with the `_honch_core` user C module.
+
+This port targets MicroPython. CircuitPython is not covered by the current user C module build flow.
+
+## Build Into MicroPython
+
+From a MicroPython checkout, build a port with the Honch user module:
+
+```bash
+make -C ports/unix \
+  USER_C_MODULES=/path/to/SDK/ports/micropython/usermod/honch/micropython.cmake
+```
+
+For board firmware, pass the same user module path and freeze the wrapper:
+
+```bash
+make BOARD=MYBOARD \
+  USER_C_MODULES=/path/to/SDK/ports/micropython/usermod/honch/micropython.cmake \
+  FROZEN_MANIFEST=/path/to/SDK/ports/micropython/manifest.py
+```
+
+The Honch user C module does not set firmware-global MicroPython options such
+as `MICROPY_C_HEAP_SIZE`. Keep heap sizing in the board or host firmware
+configuration. If your board needs additional C heap for Honch and other native
+modules, opt into that value in the board config rather than in the user module.
+
+`mip` can install wrapper files from package metadata, but those files require firmware that already contains `_honch_core`.
+Do not install the `honch/` wrapper into `/lib` when it is already frozen into
+the firmware. Keeping both copies wastes the board filesystem and can make
+MicroPython import an older `/lib/honch` package instead of the frozen SDK.
+
+## Basic Usage
+
+```python
+import honch
+
+client = honch.Honch(
+    api_key="project-key",
+    endpoint_url="https://i.honch.io",
+    device_id="device-serial-001",
+    device_model="ActionCam X1",
+    firmware_version="1.2.3",
+    event_buffer=bytearray(8192),
+)
+
+client.identify("user-123", {"plan": "beta"})
+client.session_start("recording")
+client.track("recording_started", {"mode": "hdr"})
+client.session_end()
+client.flush()
+client.shutdown()
+```
+
+## Configuration
+
+Required:
+
+- `api_key`
+- `device_id`
+- `device_model`
+- `firmware_version`
+- `event_buffer`
+
+Optional:
+- `endpoint_url` (default `https://i.honch.io`)
+- `environment`
+- `batch_size`
+- `max_queued_events`
+- `max_event_bytes`
+- `transport_timeout_ms` (finite positive milliseconds, clamped to 10000)
+- `flush_interval_seconds`
+- `flush_min_interval_ms` (default `15000`; use `0xFFFFFFFF` to disable for benchmarks)
+- `flush_event_threshold`
+- `flush_retry_initial_ms`
+- `flush_retry_max_ms`
+- `battery_low_threshold`
+- `connectivity_callback` (return false while offline; ticks are skipped and `flush()` raises `OfflineError`)
+
+Python `platform=`, `transport=`, `battery_callback=`, and `auto_properties_callback=` hooks are not supported by the C-core-derived port. Board behavior belongs in the user module adapters.
+
+client init does synchronous work on the caller's thread. It validates config,
+initializes the C core against the caller-provided event buffer, derives initial
+state from the supplied device/config values, and queues `$device_boot` before
+returning. It does not perform network I/O; delivery remains cooperative through
+`tick()` or explicit `flush()` calls.
+
+Crash reporting is automatic. `client.install_error_hook()` installs a
+best-effort `sys.excepthook` wrapper (on runtimes that expose that hook) that
+emits a one-time `$crash` event for an uncaught exception (`source="exception"`,
+with the exception type in `exception_cause`); the original exception is always
+delivered to the previous hook. `client.report_log_error(message,
+component=...)` emits a bounded, coalesced `$error` event and is intended to be
+driven automatically (e.g. from a `logging.Handler`), not sprinkled through
+application code. The port does not install panic hooks or board-specific
+reset-reason adapters; board reset telemetry belongs in the user module adapter.
+
+client.tick() and client.flush() may block for up to the configured transport
+timeout because urequests.post holds the MicroPython interpreter while the HTTP
+request is in progress. Do not call tick() from a latency-sensitive control
+loop, timing-critical sensor loop, UI refresh path, or watchdog-sensitive
+section. Do not call tick() or flush() from ISR-adjacent callbacks or
+high-priority tasks. Schedule it from a low-priority part of the program where a
+stalled interpreter is acceptable for the configured timeout. Explicit timeout
+values above the hard maximum of 10000 ms are clamped.
+Each scheduled tick posts at most one wire chunk, so large queued uploads may
+need several pump iterations to finish.
+
+Do not call `tick()` while WLAN is disconnected or the radio is intentionally
+off. If your loop cannot guarantee that, pass `connectivity_callback`; it should
+be fast and read host-owned connectivity state.
+
+## Public API
+
+```python
+client.track(event_name, properties=None)
+client.report_log_error(message, component=None)
+client.install_error_hook()
+client.uninstall_error_hook()
+client.identify(distinct_id, traits=None)
+client.set_property(key, value=None)
+client.session_start(session_name=None)
+client.session_end()
+client.connectivity_changed(connected)
+client.connected()
+client.disconnected()
+client.tick()
+client.flush()
+client.reset()
+client.shutdown()
+client.get_device_id()
+client.queue_stats()
+```
+
+After `identify()`, future events use the new distinct ID. The `$identify`
+event also includes the previous identity as `$anon_distinct_id`, usually the
+device ID, so earlier anonymous events can merge into the identified person.
+
+Call `client.tick()` periodically from the device main loop for scheduled flush work. Use `client.flush()` when you want an immediate drain attempt.
+
+Properties support typed event values, including strings, integers, floats,
+booleans, lists, dictionaries, null, and `bytes`. Capture may reject bytes
+unless the project enables binary properties. SDK-owned auto property keys
+supplied by users are rejected before compact wire-v2 packetization.
+
+## Storage And Transport
+
+The default user C module stores queued events in the caller-provided
+`event_buffer`. Events, `identify()` state, and firmware-version state are
+volatile by default and are lost across reset or power loss. `device_id` is required
+because this port does not persist SDK identity. Pass a caller-provided stable
+device_id from board provisioning, NVS, a filesystem file, or another
+product-owned durable source.
+
+That RAM queue is bounded and compact. Consuming a non-tail event uses an O(n)
+memmove per consumed event to keep the caller-provided buffer contiguous; this
+is acceptable at default sizes, but larger buffers and queue limits should be
+measured on the target board.
+
+Flush sends compact chunk frames to `POST <endpoint_url>/capture` with `Content-Type: application/vnd.honch.chunk`, `X-Honch-Project-Key`, and `X-Honch-Stream-Id`.
+
+## Security
+
+Use HTTPS in production. Verify the board has network, time, and trust setup needed for certificate validation. Keep project keys out of source control, logs, and event properties.
+
+## Tests
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=ports/micropython python3 -m unittest discover \
+  -s ports/micropython/tests -t . -v
+```
+
+Full runtime validation requires building MicroPython with `_honch_core` and running the wrapper on that interpreter or firmware.

honch_micropython-0.3.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+honch/__init__.py,sha256=XBof-C15jmlkF9kWuTDOyHipOql8KpXMCfXokaSkDEk,549
+honch/client.py,sha256=UfgvuLWeq20f3agj9uWuarMWRHce3GnFLIk8rtzcgrE,13752
+honch/config.py,sha256=wqXCZVJZ0sNIwSdSQb3mFmCkFtfmj5BGGdIAQ3zAHhk,3685
+honch/errors.py,sha256=bH8QYhdys5tnsxtiqxlCHQxHBob-xS3Qa2e3hqMR3Bg,473
+honch/validation.py,sha256=Qd1Exu1uxvW81_5p3yJH3sbId6ekXepoInYHyhqBC5w,1604
+honch_micropython-0.3.0.dist-info/METADATA,sha256=mGJZoM7GgCQISq7cFaj6ovZ3hbJ0DaeAjd7HPCKMpck,7648
+honch_micropython-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+honch_micropython-0.3.0.dist-info/top_level.txt,sha256=9OAH0ocYw6Xseoknyp2rWuUnT2D18WBWsrUgH9nIqCc,6
+honch_micropython-0.3.0.dist-info/RECORD,,

honch_micropython-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

honch_micropython-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+honch