pyulix 1.2.0b2__py3-none-any.whl

pyulix/__init__.py

@@ -0,0 +1,12 @@
+"""Complete named Python facade for the pinned Oculix Java API.
+
+Java method names, constructors and overload arguments are preserved.
+Use ``method.overload(*java_type_names)`` for ambiguous null/reference calls.
+"""
+from ._bridge import Bridge, BridgeError, RemoteObject, RemoteWrapper, default_bridge
+from ._api import JavaObject, JavaCallback, java_class
+from .java import *
+from .java import __all__ as _java_names
+
+__version__ = '1.2.0b2'
+__all__ = list(_java_names) + ['Bridge', 'BridgeError', 'JavaObject', 'JavaCallback', 'java_class', 'default_bridge']

pyulix/__init__.pyi

@@ -0,0 +1,4 @@
+from .java import *
+from ._bridge import Bridge, BridgeError, default_bridge
+from ._api import JavaObject, JavaCallback, java_class
+__version__: str

pyulix/_api.py

@@ -0,0 +1,225 @@
+"""Java overload binding, fields and typed facades for the generated API."""
+from __future__ import annotations
+
+import inspect
+import gzip
+import json
+import keyword
+from pathlib import Path
+from typing import Any
+
+from ._bridge import RemoteWrapper, RemoteObject, register_wrapper, _WRAPPER_TYPES
+
+_SCHEMA = json.loads(gzip.decompress(Path(__file__).with_name('_api_schema.json.gz').read_bytes()))
+_TYPES = {}
+
+
+def _default_bridge():
+    import pyulix
+    return pyulix.default_bridge()
+
+
+def _identifier(name):
+    return name + '_' if keyword.iskeyword(name) or name in {'self', 'cls'} else name
+
+
+def _bind(member, args, kwargs):
+    parameters = member['parameters']
+    values = list(args)
+    varargs = member['varargs']
+    fixed = len(parameters) - int(varargs)
+    if not varargs and len(values) > len(parameters): raise TypeError('Too many positional arguments')
+    for i, p in enumerate(parameters):
+        name = _identifier(p['name'])
+        if name in kwargs:
+            if i < len(args): raise TypeError('Multiple values for ' + name)
+            if i != len(values): raise TypeError('Missing preceding argument')
+            values.append(kwargs[name])
+        elif i >= len(values) and i < fixed:
+            raise TypeError('Missing argument ' + name)
+    known = {_identifier(p['name']) for p in parameters}
+    if set(kwargs) - known: raise TypeError('Unknown argument: ' + ', '.join(set(kwargs) - known))
+    if varargs:
+        # Both Java's explicit array form and Python's expanded positional form.
+        final = values[-1] if values else None
+        remote = final._remote if isinstance(final, RemoteWrapper) else final
+        explicit_array = (final is None or isinstance(final, (list, tuple))
+                          or isinstance(final, (bytes, bytearray)) and parameters[-1]['type'] == 'byte[]'
+                          or isinstance(remote, RemoteObject) and remote._class.startswith('['))
+        if len(values) == len(parameters) and explicit_array:
+            pass
+        else: values = values[:fixed] + [values[fixed:]]
+    elif len(values) != len(parameters): raise TypeError('Wrong argument count')
+    return values
+
+
+class BoundJavaMethod:
+    def __init__(self, descriptor, instance, owner):
+        self.descriptor, self.instance, self.owner = descriptor, instance, owner
+        self.__name__ = descriptor.name
+        self.__doc__ = descriptor.__doc__
+        self.overloads = tuple(descriptor.members)
+        member = next((m for m in descriptor.members if m['static'] or instance is not None), descriptor.members[0])
+        params = [inspect.Parameter(_identifier(p['name']), inspect.Parameter.VAR_POSITIONAL
+                  if member['varargs'] and i == len(member['parameters']) - 1 else inspect.Parameter.POSITIONAL_OR_KEYWORD)
+                  for i, p in enumerate(member['parameters'])]
+        self.__signature__ = inspect.Signature(params)
+
+    def overload(self, *parameter_types):
+        """Choose an exact Java overload where Python values cannot disambiguate it."""
+        members = [m for m in self.descriptor.members if tuple(p['type'] for p in m['parameters']) == parameter_types]
+        if not members: raise TypeError('No Java overload with types ' + repr(parameter_types))
+        return BoundJavaMethod(JavaMethod(self.descriptor.name, members), self.instance, self.owner)
+
+    def __call__(self, *args, **kwargs):
+        bridge = self.instance._remote._bridge if self.instance is not None else _default_bridge()
+        candidates = []
+        for member in self.descriptor.members:
+            if self.instance is None and not member['static'] and self.__name__ != '<init>': continue
+            try: values = _bind(member, args, kwargs)
+            except TypeError: continue
+            prepared = []
+            for parameter, value in zip(member['parameters'], values):
+                if callable(value) and not isinstance(value, JavaCallback):
+                    interface = parameter['type']
+                    if interface == 'java.lang.Object': interface = 'org.sikuli.script.ObserverCallBack'
+                    value = JavaCallback(interface, value)
+                prepared.append(value)
+            candidates.append((member, prepared))
+        if not candidates:
+            raise TypeError(f'No matching argument names/count for {self.owner.JAVA_CLASS}.{self.__name__}; see .overloads')
+        # Java owns assignability, interface inheritance, unboxing and conversion.
+        # Python only binds argument names/counts; stubs never gate runtime values.
+        if len(candidates) > 1:
+            index = bridge.resolve_overload(self.owner.JAVA_CLASS, self.__name__, candidates)
+        else: index = 0
+        member, prepared = candidates[index]
+        for parameter, value in zip(member['parameters'], prepared):
+            if value is None and parameter.get('non_null'):
+                raise TypeError(f"{self.owner.JAVA_CLASS}.{self.__name__}: {parameter['name']} "
+                                f"must not be None ({parameter['type']})")
+        types = [p['type'] for p in member['parameters']]
+        if self.__name__ == '<init>': return bridge.create(self.owner.JAVA_CLASS, prepared, parameter_types=types)
+        if member['static']:
+            return bridge.call_static(self.owner.JAVA_CLASS, self.__name__, prepared, parameter_types=types)
+        return bridge.call(self.instance._remote._ref, self.__name__, prepared, parameter_types=types)
+
+
+class JavaMethod:
+    """A declared, finite set of Java overloads; no arbitrary method forwarding."""
+    def __init__(self, name, members):
+        self.name, self.members = name, members
+        self.__doc__ = '\n'.join(m['name'] + '(' + ', '.join(p['type'] + ' ' + p['name'] for p in m['parameters']) + ')' for m in members)
+
+    def __get__(self, instance, owner=None):
+        return BoundJavaMethod(self, instance, owner)
+
+
+class JavaField:
+    def __init__(self, field): self.field = field
+    def __get__(self, instance, owner=None):
+        if instance is None and not self.field['static']: return self
+        bridge = instance._remote._bridge if instance is not None else _default_bridge()
+        req = {'class': owner.JAVA_CLASS, 'field': self.field['name']}
+        if instance is not None and not self.field['static']: req = {'ref': instance._remote._ref, 'field': self.field['name']}
+        from ._bridge import _decode
+        return _decode(bridge, bridge._request(req))
+    def __set__(self, instance, value):
+        self.set(type(instance), instance, value)
+    def set(self, owner, instance, value):
+        if self.field['final']: raise AttributeError('Java field is final: ' + self.field['name'])
+        bridge = instance._remote._bridge if instance is not None else _default_bridge()
+        from ._bridge import _encode
+        req = {'class': owner.JAVA_CLASS, 'field': self.field['name'], 'value': _encode(value, bridge)}
+        if instance is not None and not self.field['static']: req['ref'] = instance._remote._ref
+        bridge._request(req)
+
+
+class JavaMeta(type):
+    def overload(cls, *parameter_types):
+        """Select an exact public constructor, including null reference calls."""
+        members = _SCHEMA.get(cls.JAVA_CLASS, {}).get('constructors', [])
+        return BoundJavaMethod(JavaMethod('<init>', members), None, cls).overload(*parameter_types)
+    def __setattr__(cls, name, value):
+        descriptor = next((p.__dict__[name] for p in cls.__mro__ if name in p.__dict__), None)
+        if isinstance(descriptor, JavaField): descriptor.set(cls, None, value)
+        else: super().__setattr__(name, value)
+
+
+class JavaObject(RemoteWrapper, metaclass=JavaMeta):
+    JAVA_CLASS = 'java.lang.Object'
+    def __init__(self, *args, **kwargs):
+        schema = _SCHEMA.get(self.JAVA_CLASS)
+        if schema is None: result = _default_bridge().create(self.JAVA_CLASS, list(args))
+        else:
+            if not schema['constructors']: raise TypeError(self.JAVA_CLASS + ' has no public constructors')
+            result = BoundJavaMethod(JavaMethod('<init>', schema['constructors']), None, type(self))(*args, **kwargs)
+        self._remote = result._remote if isinstance(result, RemoteWrapper) else result
+        self._remote._bridge._cache[self._remote._ref] = self
+    @property
+    def _ref(self): return self._remote._ref
+    @property
+    def _bridge(self): return self._remote._bridge
+    def __getattr__(self, name):
+        if any(_SCHEMA.get(parent.JAVA_CLASS, {}).get('opaque') for parent in type(self).__mro__
+               if hasattr(parent, 'JAVA_CLASS')):
+            raise AttributeError(f'{self._remote._class} is an opaque Java handle; use the public owner API')
+        if self.JAVA_CLASS in _SCHEMA: raise AttributeError(name)
+        return super().__getattr__(name)
+    def __iter__(self):
+        if self._remote._class.startswith('java.util.'):
+            iterator = self if self._remote._kind == 'iterator' or 'Iterator' in self._remote._class else self._call('iterator')
+            while iterator._call('hasNext'): yield iterator._call('next')
+        else: raise TypeError(self.JAVA_CLASS + ' is not an iterable')
+    def __repr__(self): return f'<{type(self).__name__} {self._remote._class}#{self._remote._ref}>'
+
+
+class JavaCallback:
+    """Python implementation of a Java interface or ObserverCallBack.
+
+    handler may be a function (single method) or an object/dict of method handlers.
+    Keep this object alive while Java may invoke it; the bridge retains it until stop.
+    """
+    def __init__(self, interface, handler):
+        self.interface = interface.JAVA_CLASS if hasattr(interface, 'JAVA_CLASS') else interface
+        self.handler = handler
+    def dispatch(self, method, args):
+        if isinstance(self.handler, dict): function = self.handler[method]
+        elif callable(self.handler): function = self.handler
+        else: function = getattr(self.handler, method)
+        return function(*args)
+
+
+def java_class(name, *, parent=None):
+    if name in _TYPES: return _TYPES[name]
+    cls = JavaMeta(name.rsplit('.', 1)[-1].replace('$', '_'), (parent or JavaObject,), {'JAVA_CLASS': name, '__module__': 'pyulix.java'})
+    _TYPES[name] = cls
+    register_wrapper(name, cls)
+    return cls
+
+
+def load_api(namespace):
+    todo = set(_SCHEMA)
+    while todo:
+        ready = sorted(n for n in todo if _SCHEMA[n]['superclass'] not in todo)
+        for name in ready:
+            row = _SCHEMA[name]
+            base = _TYPES.get(row['superclass'], JavaObject)
+            attrs = {'JAVA_CLASS': name, '__module__': 'pyulix.java', '__doc__': 'Java ' + name}
+            groups = {}
+            for m in row['methods']: groups.setdefault(m['name'], []).append(m)
+            for mname, members in groups.items():
+                descriptor = JavaMethod(mname, members)
+                attrs[_identifier(mname)] = descriptor
+                attrs[mname] = descriptor
+            for f in row['fields']:
+                if _identifier(f['name']) not in attrs: attrs[_identifier(f['name'])] = JavaField(f)
+            cls = JavaMeta(row['python_name'], (base,), attrs)
+            _TYPES[name] = cls
+            register_wrapper(name, cls)
+            namespace[row['python_name']] = cls
+        todo -= set(ready)
+    for name, cls in _TYPES.items():
+        if '$' in name and name.rsplit('$', 1)[0] in _TYPES:
+            setattr(_TYPES[name.rsplit('$', 1)[0]], name.rsplit('$', 1)[1], cls)
+    namespace['__all__'] = sorted(row['python_name'] for row in _SCHEMA.values())

pyulix/_api.pyi

@@ -0,0 +1,20 @@
+"""Typing facade: known Java classes expose their generated declarations only."""
+from typing import Any, ClassVar
+from ._bridge import Bridge
+
+class JavaObject:
+    JAVA_CLASS: ClassVar[str]
+    _ref: str
+    _bridge: Bridge
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
+    def _call(self, method: str, *args: Any) -> Any: ...
+    @classmethod
+    def _wrap(cls, value: Any) -> Any: ...
+
+class JavaCallback:
+    interface: str
+    handler: Any
+    def __init__(self, interface: Any, handler: Any) -> None: ...
+    def dispatch(self, method: str, args: Any) -> Any: ...
+
+def java_class(name: str, *, parent: Any = None) -> Any: ...

pyulix/_bridge.py

@@ -0,0 +1,367 @@
+"""JSON-RPC client to the OculiX JVM bridge over stdin/stdout.
+
+The bridge is a fat JAR (~160 MB) containing oculixapi + Apertix OpenCV +
+our minimal RPC server. It's downloaded once from GitHub Releases on first
+use and cached under ``~/.pyulix/lib/``.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import shutil
+import subprocess
+import threading
+import queue
+import collections
+import urllib.request
+import weakref
+from pathlib import Path
+from typing import Any, Optional, Type
+
+# --- bridge JAR distribution -------------------------------------------------
+
+BRIDGE_VERSION = "1.2.0b2"
+BRIDGE_JAR_NAME = f"operix-jvm-bridge-{BRIDGE_VERSION}.jar"
+BRIDGE_JAR_URL = (
+    "https://github.com/ajayrakde/Operix/releases/download/"
+    f"jvm-bridge-{BRIDGE_VERSION}/{BRIDGE_JAR_NAME}"
+)
+JAR_DIR = Path(os.path.expanduser("~/.pyulix/lib"))
+
+
+def _ensure_jar() -> Path:
+    jar_path = JAR_DIR / BRIDGE_JAR_NAME
+    if jar_path.exists():
+        return jar_path
+    JAR_DIR.mkdir(parents=True, exist_ok=True)
+    print(f"[Pyulix] Downloading {BRIDGE_JAR_NAME} (~160 MB)…")
+    # Download atomically: interrupted installs must not leave a cached broken JAR.
+    import tempfile
+    temp = None
+    try:
+        with tempfile.NamedTemporaryFile(dir=JAR_DIR, suffix=".part", delete=False) as stream:
+            temp = Path(stream.name)
+        urllib.request.urlretrieve(BRIDGE_JAR_URL, temp)
+        import zipfile
+        with zipfile.ZipFile(temp) as archive:
+            if "org/operix/rpc/Server.class" not in archive.namelist():
+                raise RuntimeError("Downloaded JAR does not contain the Operix bridge")
+        os.replace(temp, jar_path)
+    finally:
+        if temp is not None and temp.exists(): temp.unlink()
+    print(f"[Pyulix] Saved to {jar_path}")
+    return jar_path
+
+
+# --- JSON-RPC client ---------------------------------------------------------
+
+class BridgeError(RuntimeError):
+    """Raised when the JVM side returned an error for a request."""
+
+
+class Bridge:
+    """Owns the JVM child process and serialises RPC requests over stdio."""
+
+    def __init__(self, jar_path: Optional[Path] = None, java_bin: str = "java"):
+        if shutil.which(java_bin) is None:
+            raise RuntimeError(
+                f"{java_bin!r} not found on PATH. Install Java 17+ "
+                "(https://adoptium.net) and retry."
+            )
+        self._jar = jar_path or _ensure_jar()
+        self._java = java_bin
+        self._proc: Optional[subprocess.Popen] = None
+        self._lock = threading.Lock()
+        self._next_id = 0
+        self._pending = {}
+        self._callbacks = {}
+        self._stderr_tail = collections.deque(maxlen=100)
+        self._callback_errors = collections.deque(maxlen=100)
+        # Python-side identity dedup: same Java ref always yields the same
+        # Python object so __del__ doesn't kill a ref that's still in use.
+        self._cache: "weakref.WeakValueDictionary[str, Any]" = (
+            weakref.WeakValueDictionary())
+
+    def start(self) -> None:
+        if self._proc is not None:
+            return
+        self._proc = subprocess.Popen(
+            # Force the JVM to speak UTF-8 on stdio. On Windows the JVM defaults
+            # System.out to the console code page (cp1252), so any accented OCR
+            # text (é -> 0xe9) is invalid UTF-8 and crashes the reader below.
+            # -Dstdout/stderr.encoding (Java 18+) pin the console streams; the
+            # file.encoding flag covers older JVMs.
+            [self._java,
+             "-Dfile.encoding=UTF-8",
+             "-Dstdout.encoding=UTF-8",
+             "-Dstderr.encoding=UTF-8",
+             "-jar", str(self._jar)],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            bufsize=1,           # line buffered
+            text=True,
+            encoding="utf-8",
+            errors="replace",    # belt-and-suspenders: never crash on a stray byte
+        )
+        threading.Thread(target=self._read_responses, daemon=True, name="pyulix-rpc").start()
+        threading.Thread(target=self._read_stderr, daemon=True, name="pyulix-stderr").start()
+        atexit.register(self.stop)
+
+    def stop(self) -> None:
+        if self._proc is None:
+            return
+        try:
+            self._proc.stdin.close()
+        except Exception:
+            pass
+        try:
+            self._proc.terminate()
+            self._proc.wait(timeout=5)
+        except Exception:
+            self._proc.kill()
+        self._proc = None
+        self._callbacks.clear()
+
+    def _read_stderr(self):
+        proc = self._proc
+        for line in proc.stderr:
+            self._stderr_tail.append(line.rstrip())
+
+    def _read_responses(self):
+        proc = self._proc
+        try:
+            for line in proc.stdout:
+                response = json.loads(line)
+                if "callback" in response:
+                    threading.Thread(target=self._handle_callback, args=(response,), daemon=True).start()
+                    continue
+                with self._lock:
+                    pending = self._pending.pop(response.get("id"), None)
+                if pending is not None: pending.put(response)
+        except Exception as error:
+            self._stderr_tail.append(str(error))
+        finally:
+            with self._lock:
+                pending = list(self._pending.values())
+                self._pending.clear()
+            for waiter in pending:
+                waiter.put({"error": "JVM bridge died. stderr: " + "\n".join(self._stderr_tail)})
+
+    def _write(self, payload):
+        self._proc.stdin.write(json.dumps(payload, ensure_ascii=False) + "\n")
+        self._proc.stdin.flush()
+
+    def _handle_callback(self, message):
+        reply = {"callback_result": message["callback_id"]}
+        try:
+            callback = self._callbacks[message["callback"]]
+            result = callback.dispatch(message["method"], _decode(self, message["args"]))
+            reply["result"] = _encode(result, self)
+        except Exception as error:
+            reply["error"] = type(error).__name__ + ": " + str(error)
+            self._callback_errors.append(error)
+        try:
+            with self._lock: self._write(reply)
+        except Exception:
+            pass
+
+    def _encode_callback(self, callback):
+        key = "p" + str(id(callback))
+        self._callbacks[key] = callback
+        return {"__callback": key, "interface": callback.interface}
+
+    @property
+    def callback_errors(self):
+        return tuple(self._callback_errors)
+
+    def _request(self, payload: dict) -> Any:
+        with self._lock:
+            if self._proc is None: self.start()
+            self._next_id += 1
+            payload["id"] = self._next_id
+            pending = queue.Queue(maxsize=1)
+            self._pending[payload["id"]] = pending
+            try: self._write(payload)
+            except Exception:
+                self._pending.pop(payload["id"], None)
+                raise
+        # The reader and callback handlers remain live during this wait, so
+        # background observation and callbacks making nested Java calls work.
+        response = pending.get()
+        if "error" in response: raise BridgeError(response["error"])
+        return response["result"]
+
+    # --- public RPC operations ----------------------------------------------
+
+    def create(self, classname: str, args: list, parameter_types=None) -> Any:
+        payload = {"class": classname, "args": _encode_args(args, self)}
+        if parameter_types is not None: payload["parameter_types"] = parameter_types
+        result = self._request(payload)
+        return _decode(self, result)
+
+    def call(self, ref: str, method: str, args: list, parameter_types=None) -> Any:
+        payload = {"ref": ref, "method": method, "args": _encode_args(args, self)}
+        if parameter_types is not None: payload["parameter_types"] = parameter_types
+        result = self._request(payload)
+        return _decode(self, result)
+
+    def call_static(self, classname: str, method: str, args: list, parameter_types=None) -> Any:
+        payload = {"class": classname, "method": method,
+                   "static": True, "args": _encode_args(args, self)}
+        if parameter_types is not None: payload["parameter_types"] = parameter_types
+        result = self._request(payload)
+        return _decode(self, result)
+
+    def resolve_overload(self, classname, method, candidates):
+        return self._request({'class': classname, 'resolve': method, 'candidates': [
+            {'parameter_types': [p['type'] for p in member['parameters']],
+             'args': _encode_args(values, self)} for member, values in candidates]})
+
+    def release(self, ref: str) -> None:
+        # A dead bridge must not restart just to release a stale object.
+        if self._proc is None: return
+        try:
+            self._request({"ref": ref, "release": True})
+        except Exception:
+            pass
+
+
+# --- value codec -------------------------------------------------------------
+
+_WRAPPER_TYPES = {}
+
+
+def register_wrapper(java_class: str, wrapper: Type["RemoteWrapper"]) -> None:
+    """Register the Python result type for an exact Java runtime class."""
+    _WRAPPER_TYPES[java_class] = wrapper
+
+
+class RemoteWrapper:
+    """Typed facade whose RemoteObject owns the Java reference lifetime."""
+
+    def _call(self, method: str, *args) -> Any:
+        return self._remote._call(method, *args)
+
+    def __getattr__(self, name: str):
+        if name.startswith("_"):
+            raise AttributeError(name)
+        # Keep existing Java methods callable while explicit signatures are added.
+        return getattr(self._remote, name)
+
+    @classmethod
+    def _wrap(cls, remote):
+        if isinstance(remote, cls):
+            return remote
+        if not isinstance(remote, RemoteObject):
+            raise TypeError("Expected a Java object reference")
+        instance = cls.__new__(cls)
+        instance._remote = remote
+        return instance
+
+
+class RemoteObject:
+    """Opaque handle to a Java object held by the JVM bridge."""
+
+    __slots__ = ("_bridge", "_ref", "_class", "_kind", "__weakref__")
+
+    def __init__(self, bridge: Bridge, ref: str, java_class: str):
+        self._bridge = bridge
+        self._ref = ref
+        self._class = java_class
+        self._kind = None
+
+    def _call(self, method: str, *args) -> Any:
+        return self._bridge.call(self._ref, method, list(args))
+
+    def __getattr__(self, name: str):
+        # Dynamic method proxy: any Java method of the remote object becomes
+        # callable directly (loc.getX(), rect.getWidth(), img.getSize()...).
+        # Only reached for attributes NOT found through __slots__, so the
+        # internal fields never collide. Dunder/underscore names are refused
+        # so pickling, copying and introspection keep their normal semantics.
+        if name.startswith("_"):
+            raise AttributeError(name)
+
+        def _proxy(*args) -> Any:
+            return self._bridge.call(self._ref, name, list(args))
+
+        _proxy.__name__ = name
+        _proxy.__qualname__ = f"RemoteObject.{name}"
+        return _proxy
+
+    def __repr__(self) -> str:
+        return f"<RemoteObject {self._class}#{self._ref}>"
+
+    def __del__(self):
+        # Best-effort GC. May fail during interpreter shutdown.
+        try:
+            self._bridge.release(self._ref)
+        except Exception:
+            pass
+
+
+def _encode_args(args: list, bridge: Optional[Bridge] = None) -> list:
+    return [_encode(a, bridge) for a in args]
+
+
+def _encode(v: Any, bridge: Optional[Bridge] = None) -> Any:
+    if isinstance(v, RemoteWrapper):
+        v = v._remote
+    if isinstance(v, RemoteObject):
+        if bridge is not None and v._bridge is not bridge:
+            raise ValueError("Cannot pass a Java object to a different JVM bridge")
+        return {"__ref": v._ref}
+    from ._api import JavaCallback
+    if isinstance(v, JavaCallback):
+        if bridge is None: raise ValueError("A callback requires a bridge")
+        return bridge._encode_callback(v)
+    if isinstance(v, (bytes, bytearray)):
+        return [(n if n < 128 else n - 256) for n in v]
+    if isinstance(v, (list, tuple)):
+        return [_encode(item, bridge) for item in v]
+    if isinstance(v, dict):
+        if any(not isinstance(key, str) for key in v) or any(key.startswith('__') for key in v):
+            return {'__map': [[_encode(key, bridge), _encode(item, bridge)] for key, item in v.items()]}
+        return {key: _encode(item, bridge) for key, item in v.items()}
+    return v
+
+
+def _decode(bridge: Bridge, v: Any) -> Any:
+    if isinstance(v, dict) and "__map" in v:
+        return {_decode(bridge, k): _decode(bridge, value) for k, value in v["__map"]}
+    if isinstance(v, dict) and "__ref" in v:
+        ref = v["__ref"]
+        cached = bridge._cache.get(ref)
+        if cached is not None:
+            return cached
+        remote = RemoteObject(bridge, ref, v.get("__class", "?"))
+        remote._kind = v.get("__kind")
+        wrapper = _WRAPPER_TYPES.get(remote._class)
+        if wrapper is None:
+            from ._api import java_class
+            parent = next((_WRAPPER_TYPES[name] for name in v.get('__types', [])
+                           if name in _WRAPPER_TYPES and name != 'java.lang.Object'), None)
+            wrapper = java_class(remote._class, parent=parent)
+        obj = wrapper._wrap(remote)
+        bridge._cache[ref] = obj
+        return obj
+    if isinstance(v, list):
+        return [_decode(bridge, item) for item in v]
+    if isinstance(v, dict):
+        return {key: _decode(bridge, item) for key, item in v.items()}
+    return v
+
+
+# --- module-wide singleton ---------------------------------------------------
+
+_default_bridge: Optional[Bridge] = None
+
+
+def default_bridge() -> Bridge:
+    global _default_bridge
+    if _default_bridge is None:
+        _default_bridge = Bridge()
+    return _default_bridge

pyulix/java/__init__.py

@@ -0,0 +1,4 @@
+"""Generated named Oculix API, with exact overload metadata."""
+from pyulix._api import load_api
+
+load_api(globals())