uclog 4__py3-none-win_amd64.whl

uclog/__init__.py

@@ -0,0 +1,35 @@
+# © 2026 Unit Circle Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+"""ucLog for scripts: connect to a device through the ucLog hub, send and receive on any port,
+and decode logs.
+
+    import uclog
+
+    with uclog.connect(logdata="build/zephyr/zephyr.elf") as dev:
+        print(dev.device_info)
+        dev.send(61, b"version s\\r")
+        print(dev.recv(61, timeout=1.0))
+        for rec in dev.logs(timeout=5.0):
+            print(rec)
+
+All device I/O goes through the native hub (`uclog-hub`); a hub is started when none is running
+and stopped when the script exits.
+"""
+
+from . import aio, cbor, proto
+from .connection import Connection, connect
+from .errors import (ApprovalTimeoutError, ConnectionClosedError, DeviceNotRespondingError,
+                     HubBusyError, HubStartError, MultipleHubsError, NoHubError, UclogError)
+from .hub import DeviceInfo, HubInfo, list_devices, list_hubs, start_hub, stop_hub
+from .logdata import DecodeError, LogData, LogDataError, LogRecord
+from .resolver import Resolver
+
+__version__ = '4'
+
+__all__ = [
+  'connect', 'Connection', 'list_hubs', 'list_devices', 'start_hub', 'stop_hub', 'HubInfo',
+  'DeviceInfo', 'LogData', 'LogRecord', 'Resolver', 'DecodeError', 'LogDataError', 'UclogError',
+  'NoHubError', 'MultipleHubsError', 'HubBusyError', 'ApprovalTimeoutError',
+  'DeviceNotRespondingError', 'HubStartError', 'ConnectionClosedError', 'aio', 'cbor', 'proto',
+]

uclog/aio.py

@@ -0,0 +1,102 @@
+# © 2026 Unit Circle Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+"""asyncio API: the same calls as the sync one, awaited.
+
+    async with await uclog.aio.connect(logdata="build/zephyr/zephyr.elf") as dev:
+        await dev.send(61, b"version s\\r")
+        print(await dev.recv(61, timeout=1.0))
+        async for rec in dev.logs(timeout=5.0):
+            print(rec)
+
+The connection's I/O runs on its own threads (see `uclog.Connection`); waits run in the
+default executor so the event loop is never blocked.
+"""
+
+import asyncio
+import functools
+from typing import AsyncIterator, Optional
+
+from . import connection
+from .logdata import LogRecord
+
+__all__ = ['connect', 'Connection']
+
+
+async def _run(fn, *args, **kw):
+  loop = asyncio.get_running_loop()
+  return await loop.run_in_executor(None, functools.partial(fn, *args, **kw))
+
+
+class Connection:
+  """Async wrapper of `uclog.Connection`. `sync` is the wrapped connection."""
+
+  def __init__(self, sync: connection.Connection):
+    self.sync = sync
+
+  async def __aenter__(self):
+    return self
+
+  async def __aexit__(self, *exc):
+    await self.close()
+    return False
+
+  @property
+  def alive(self) -> bool:
+    return self.sync.alive
+
+  @property
+  def closed(self) -> bool:
+    return self.sync.closed
+
+  @property
+  def dropped(self):
+    return self.sync.dropped
+
+  @property
+  def notes(self):
+    return self.sync.notes
+
+  async def device_info(self, timeout: Optional[float] = None) -> Optional[dict]:
+    """The port-62 map. Without `timeout`, waits as long as the sync `device_info` property."""
+    return await _run(self.sync.wait_device_info,
+                      self.sync._info_timeout() if timeout is None else timeout)
+
+  async def send(self, port: int, data) -> None:
+    self.sync.send(port, data)
+
+  async def send_frame(self, payload: bytes) -> None:
+    self.sync.send_frame(payload)
+
+  async def recv(self, port: int, timeout: Optional[float] = None) -> Optional[bytes]:
+    return await _run(self.sync.recv, port, timeout)
+
+  async def console(self, timeout: Optional[float] = None):
+    return await _run(self.sync.console, timeout)
+
+  async def command(self, obj: dict, timeout: float = 2.0):
+    return await _run(self.sync.command, obj, timeout)
+
+  async def logs(self, timeout: Optional[float] = None, duration: Optional[float] = None) -> AsyncIterator[LogRecord]:
+    it = self.sync.logs(timeout, duration)
+    while True:
+      r = await _run(next, it, None)
+      if r is None:
+        return
+      yield r
+
+  async def frames(self, timeout: Optional[float] = None, duration: Optional[float] = None) -> AsyncIterator[bytes]:
+    it = self.sync.frames(timeout, duration)
+    while True:
+      r = await _run(next, it, None)
+      if r is None:
+        return
+      yield r
+
+  async def close(self) -> None:
+    await _run(self.sync.close)
+
+
+async def connect(*args, **kw) -> Connection:
+  """Same arguments as `uclog.connect()`."""
+  return Connection(await _run(connection.connect, *args, **kw))

uclog/cbor.py

@@ -0,0 +1,160 @@
+# © 2026 Unit Circle Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Minimal CBOR (RFC 8949): enough for every payload in the ucLog protocol.
+
+From spec/reference/ucref.py. Standard library only, so the package has no dependencies.
+"""
+
+import struct
+
+__all__ = ['dumps', 'loads', 'CborError']
+
+
+class CborError(ValueError):
+  pass
+
+
+def _head(major, n):
+  if n < 24:
+    return bytes(((major << 5) | n,))
+  for ai, fmt in ((24, '>B'), (25, '>H'), (26, '>I'), (27, '>Q')):
+    if n < (1 << (8 * struct.calcsize(fmt))):
+      return bytes(((major << 5) | ai,)) + struct.pack(fmt, n)
+  raise ValueError('integer too large for CBOR')
+
+
+def dumps(v) -> bytes:
+  """Encode: shortest heads, map keys in insertion order, floats as float64."""
+  if v is None:
+    return b'\xf6'
+  if v is True:
+    return b'\xf5'
+  if v is False:
+    return b'\xf4'
+  if isinstance(v, int):
+    return _head(0, v) if v >= 0 else _head(1, -1 - v)
+  if isinstance(v, float):
+    return b'\xfb' + struct.pack('>d', v)
+  if isinstance(v, (bytes, bytearray, memoryview)):
+    return _head(2, len(v)) + bytes(v)
+  if isinstance(v, str):
+    b = v.encode('utf-8')
+    return _head(3, len(b)) + b
+  if isinstance(v, (list, tuple)):
+    return _head(4, len(v)) + b''.join(dumps(x) for x in v)
+  if isinstance(v, dict):
+    return _head(5, len(v)) + b''.join(dumps(k) + dumps(x) for k, x in v.items())
+  raise TypeError(f'cannot encode {type(v).__name__} as CBOR')
+
+
+MAX_DEPTH = 64  # nesting limit for arrays, maps and tags
+
+
+def loads(data: bytes):
+  """Decode one item. Array map keys become tuples; tags are ignored. Any malformed input
+  raises CborError (and nothing else)."""
+  try:
+    d = memoryview(bytes(data))
+  except TypeError as e:
+    raise CborError(f'not bytes: {e}') from None
+  v, i = _item(d, 0, 0)
+  if i != len(d):
+    raise CborError(f'{len(d) - i} trailing bytes')
+  return v
+
+
+def _freeze(k):
+  if isinstance(k, list):
+    return tuple(_freeze(x) for x in k)
+  return k
+
+
+def _key(k):
+  k = _freeze(k)
+  try:
+    hash(k)
+  except TypeError:
+    raise CborError(f'unsupported map key type {type(k).__name__}') from None
+  return k
+
+
+def _byte(d, i):
+  if i >= len(d):
+    raise CborError('truncated')
+  return d[i]
+
+
+def _item(d, i, depth):
+  if depth > MAX_DEPTH:
+    raise CborError(f'nested more than {MAX_DEPTH} deep')
+  ib = _byte(d, i)
+  major, ai = ib >> 5, ib & 31
+  i += 1
+  if major == 7:
+    if ai == 20:
+      return False, i
+    if ai == 21:
+      return True, i
+    if ai in (22, 23):
+      return None, i
+    size = {25: 2, 26: 4, 27: 8}.get(ai)
+    if size is None:
+      raise CborError(f'unsupported simple value {ai}')
+    if i + size > len(d):
+      raise CborError('truncated')
+    return struct.unpack({2: '>e', 4: '>f', 8: '>d'}[size], d[i:i + size])[0], i + size
+  if ai < 24:
+    n = ai
+  elif ai in (24, 25, 26, 27):
+    size = 1 << (ai - 24)
+    if i + size > len(d):
+      raise CborError('truncated')
+    n = int.from_bytes(d[i:i + size], 'big')
+    i += size
+  elif ai == 31 and major in (2, 3, 4, 5):
+    n = None  # indefinite length
+  else:
+    raise CborError(f'bad additional info {ai}')
+  if major == 0:
+    return n, i
+  if major == 1:
+    return -1 - n, i
+  if major in (2, 3):
+    if n is None:
+      # Chunks are definite-length strings of the same major type (RFC 8949 §3.2.3).
+      parts = []
+      while _byte(d, i) != 0xFF:
+        if d[i] >> 5 != major or d[i] & 31 == 31:
+          raise CborError('bad chunk in an indefinite-length string')
+        p, i = _item(d, i, depth + 1)
+        parts.append(p)
+      i += 1
+      return (b''.join(parts) if major == 2 else ''.join(parts)), i
+    if i + n > len(d):
+      raise CborError('truncated')
+    raw = bytes(d[i:i + n])
+    try:
+      return (raw if major == 2 else raw.decode('utf-8')), i + n
+    except UnicodeDecodeError as e:
+      raise CborError(f'invalid UTF-8 in text: {e}') from None
+  if major == 4:
+    out = []
+    while (n is None and _byte(d, i) != 0xFF) or (n is not None and len(out) < n):
+      x, i = _item(d, i, depth + 1)
+      out.append(x)
+    if n is None:
+      i += 1
+    return out, i
+  if major == 5:
+    out = {}
+    count = 0
+    while (n is None and _byte(d, i) != 0xFF) or (n is not None and count < n):
+      k, i = _item(d, i, depth + 1)
+      x, i = _item(d, i, depth + 1)
+      out[_key(k)] = x
+      count += 1
+    if n is None:
+      i += 1
+    return out, i
+  return _item(d, i, depth + 1)  # major 6: tag, ignored