Every Device call carries one of two badges, by whether it waits for the box to answer or fires and forgets.

There is no status return in Python: a failed call raises. The base type is MediusError (an Exception subclass); each status code (a Status IntEnum) maps to its own subclass. Catch MediusError for all of them.

class MediusError(Exception):
    status:    Status   # the failure code
    message:   str      # the box's last error text, may be ""
    proto_ver: int      # offending byte for BadProtoVerError, else 0

str(err)   # "ERR_NOT_FOUND: no medius port found"  (or only the name)

The last six are subscription refusals, raised before a frame reaches the box.

from medius import Device, MediusError, DisconnectedError

try:
    with Device.find() as dev:
        dev.move_rel(10, 0)
        print(dev.query_health())
except DisconnectedError:
    print("the link dropped mid-session")
except MediusError as e:
    print(e.status, "-", e.message)   # e.g. Status.ERR_NOT_FOUND - no medius port found

A Device owns a native handle. Open one, optionally clone() it, and release it three ways. Connection sharing is on Connection and Lifecycle.

Device.find() ──┐
                ├──▶  one USB-serial link  (stays up while ANY handle is open)
dev.clone() ────┘

  each handle is freed on its own; the link closes with the last one

# preferred: the context manager closes on exit
with Device.find() as dev:
    dev.move_rel(5, 5)

# or hand a clone to a worker thread and close each when done
dev = Device.find()
worker = dev.clone()
worker.close()
dev.close()

The inject, move, lock, and catch calls take a target object, not a bare value. Build it with a classmethod, then pass it in.

from medius import (Device, Usage, Motion, LockTarget, CatchFilter, TrafficClass,
                    Button, Action, Direction)

with Device.find() as dev:
    dev.inject(Usage.button(Button.LEFT), Action.PRESS)        # generic inject
    dev.move_axis(Motion.cursor(10, -4))                       # generic move (Ride / Keep by default)
    dev.lock(LockTarget.button(Button.LEFT), Direction.BOTH)

    stream = dev.catch_events([                                # generic subscribe
        CatchFilter.watch_axes(),
        CatchFilter.traffic(TrafficClass.VENDOR_INTERRUPT, 0x83).with_capture(16),
    ])