oculix-operix 1.1.0__tar.gz

oculix_operix-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oculix-org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oculix_operix-1.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: oculix-operix
+Version: 1.1.0
+Summary: Visual automation for the real world — Python wrapper for OculiX
+Author-email: Julien Mer <julien.mer38@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ajayrakde/Operix
+Project-URL: Repository, https://github.com/ajayrakde/Operix
+Keywords: visual-testing,automation,ocr,sikuli,gui-testing
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# oculix (Python)
+
+Python wrapper for [OculiX](https://github.com/oculix-org/Oculix) — visual automation for the real world.
+
+## Install
+
+```bash
+pip install oculix-operix
+```
+
+Requirements: Python 3.8+, Java 11+ on `PATH` (Eclipse Temurin or Azul Zulu).
+
+The OculiX engine (~200 MB fat JAR) is downloaded on first use into `~/.oculix/lib/`.
+
+## Quickstart
+
+```python
+from oculix import Screen, App, VNCScreen
+
+screen = Screen()
+screen.click("login.png")
+screen.type("admin")
+screen.click("submit.png")
+screen.wait("dashboard.png", 10)
+
+# Open a desktop app
+calc = App.open("calc")
+screen.click("button_7.png")
+
+# Drive a remote VNC display
+vnc = VNCScreen.start("10.0.0.42", 5900, "", 1920, 1080)
+vnc.click("logo.png")
+vnc.stop()
+```
+
+## With pytest
+
+```python
+import pytest
+from oculix import Screen, App
+
+@pytest.fixture
+def calc():
+    a = App.open("calculator")
+    yield a
+    a.close()
+
+def test_addition(calc):
+    s = Screen()
+    s.click("button_7.png")
+    s.click("button_plus.png")
+    s.click("button_3.png")
+    s.click("button_equals.png")
+    assert s.exists("result_10.png")
+```
+
+## License
+
+MIT
+
+## Java API parity
+
+This fork exposes the complete pinned Oculix 4.0.0 public method surface: 211
+public types with named Python methods, constructor/field access and every Java
+overload's arguments. `from oculix import Screen, OCR, Pattern` stays unchanged.
+Every class is also available through `oculix.java`; nested classes keep names
+such as `OCR.Options` and `OCR.PSM`.
+
+```python
+from oculix import Screen, Pattern, Match, OCR, Location, JavaCallback, ObserverCallBack
+
+screen = Screen()
+match = screen.find(Pattern("button.png").similar(0.8))
+assert isinstance(match, Match)
+match.click()
+screen.type("hello", 0)
+
+options = OCR.Options().language("eng").psm(OCR.PSM.SINGLE_LINE)
+text = OCR.readText("button.png", options)
+
+# Ambiguous Java overloads can be selected explicitly.
+options.psm.overload("org.sikuli.script.OCR$PSM")("SINGLE_LINE")
+```
+
+`exists()` returns `Match` or `None`, matching Java; truth checks continue to work.
+Java interface callbacks accept `JavaCallback(interface_name, handler)` and
+observer methods accept a Python function directly. Arrays/collections become
+Python sequences; maps become dictionaries; Java iterators support iteration.
+
+This distribution uses the matching 1.1.0 JVM bridge from `ajayrakde/Operix`.
+Do not mix it with the older upstream bridge. It occupies the same `oculix` import
+namespace as upstream, so install only one of the two distributions in a virtual
+environment. See [implementation and validation](https://github.com/ajayrakde/Operix/blob/python/java-api-parity/docs/python-api-parity.md).

oculix_operix-1.1.0/README.md

@@ -0,0 +1,93 @@
+# oculix (Python)
+
+Python wrapper for [OculiX](https://github.com/oculix-org/Oculix) — visual automation for the real world.
+
+## Install
+
+```bash
+pip install oculix-operix
+```
+
+Requirements: Python 3.8+, Java 11+ on `PATH` (Eclipse Temurin or Azul Zulu).
+
+The OculiX engine (~200 MB fat JAR) is downloaded on first use into `~/.oculix/lib/`.
+
+## Quickstart
+
+```python
+from oculix import Screen, App, VNCScreen
+
+screen = Screen()
+screen.click("login.png")
+screen.type("admin")
+screen.click("submit.png")
+screen.wait("dashboard.png", 10)
+
+# Open a desktop app
+calc = App.open("calc")
+screen.click("button_7.png")
+
+# Drive a remote VNC display
+vnc = VNCScreen.start("10.0.0.42", 5900, "", 1920, 1080)
+vnc.click("logo.png")
+vnc.stop()
+```
+
+## With pytest
+
+```python
+import pytest
+from oculix import Screen, App
+
+@pytest.fixture
+def calc():
+    a = App.open("calculator")
+    yield a
+    a.close()
+
+def test_addition(calc):
+    s = Screen()
+    s.click("button_7.png")
+    s.click("button_plus.png")
+    s.click("button_3.png")
+    s.click("button_equals.png")
+    assert s.exists("result_10.png")
+```
+
+## License
+
+MIT
+
+## Java API parity
+
+This fork exposes the complete pinned Oculix 4.0.0 public method surface: 211
+public types with named Python methods, constructor/field access and every Java
+overload's arguments. `from oculix import Screen, OCR, Pattern` stays unchanged.
+Every class is also available through `oculix.java`; nested classes keep names
+such as `OCR.Options` and `OCR.PSM`.
+
+```python
+from oculix import Screen, Pattern, Match, OCR, Location, JavaCallback, ObserverCallBack
+
+screen = Screen()
+match = screen.find(Pattern("button.png").similar(0.8))
+assert isinstance(match, Match)
+match.click()
+screen.type("hello", 0)
+
+options = OCR.Options().language("eng").psm(OCR.PSM.SINGLE_LINE)
+text = OCR.readText("button.png", options)
+
+# Ambiguous Java overloads can be selected explicitly.
+options.psm.overload("org.sikuli.script.OCR$PSM")("SINGLE_LINE")
+```
+
+`exists()` returns `Match` or `None`, matching Java; truth checks continue to work.
+Java interface callbacks accept `JavaCallback(interface_name, handler)` and
+observer methods accept a Python function directly. Arrays/collections become
+Python sequences; maps become dictionaries; Java iterators support iteration.
+
+This distribution uses the matching 1.1.0 JVM bridge from `ajayrakde/Operix`.
+Do not mix it with the older upstream bridge. It occupies the same `oculix` import
+namespace as upstream, so install only one of the two distributions in a virtual
+environment. See [implementation and validation](https://github.com/ajayrakde/Operix/blob/python/java-api-parity/docs/python-api-parity.md).

oculix_operix-1.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oculix-operix"
+version = "1.1.0"
+description = "Visual automation for the real world — Python wrapper for OculiX"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [{name = "Julien Mer", email = "julien.mer38@gmail.com"}]
+keywords = ["visual-testing", "automation", "ocr", "sikuli", "gui-testing"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/ajayrakde/Operix"
+Repository = "https://github.com/ajayrakde/Operix"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.package-data]
+oculix = ["_api_schema.json.gz", "py.typed", "**/*.pyi"]

oculix_operix-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

oculix_operix-1.1.0/src/oculix/__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.1.0'
+__all__ = list(_java_names) + ['Bridge', 'BridgeError', 'JavaObject', 'JavaCallback', 'java_class', 'default_bridge']

oculix_operix-1.1.0/src/oculix/__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

oculix_operix-1.1.0/src/oculix/_api.py

@@ -0,0 +1,269 @@
+"""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 oculix
+    return oculix.default_bridge()
+
+
+def _identifier(name):
+    return name + '_' if keyword.iskeyword(name) or name in {'self', 'cls'} else name
+
+
+def _is_java_type(actual, formal):
+    if actual == formal or formal == 'java.lang.Object': return True
+    seen = set()
+    pending = [actual]
+    while pending:
+        name = pending.pop()
+        if name == formal: return True
+        if name in seen: continue
+        seen.add(name)
+        row = _SCHEMA.get(name, {})
+        pending.extend(row.get('interfaces', []))
+        if row.get('superclass'): pending.append(row['superclass'])
+    return False
+
+
+def _score(value, formal):
+    if value is None:
+        return -1 if formal in {'boolean','byte','short','int','long','float','double','char'} else 0
+    if isinstance(value, RemoteWrapper): value = value._remote
+    if isinstance(value, RemoteObject):
+        if value._class == formal: return 12
+        if _is_java_type(value._class, formal): return 8 if formal != 'java.lang.Object' else 1
+        # External Java inheritance is verified by the JVM resolver.
+        return 2 if value._class not in _SCHEMA else -1
+    if isinstance(value, JavaCallback): return 8 if formal in {value.interface, 'java.lang.Object'} else -1
+    if callable(value): return 5 if formal == 'java.lang.Object' or _SCHEMA.get(formal, {}).get('interface') else -1
+    if formal == 'java.lang.Object': return 1
+    if type(value) is bool: return 12 if formal in {'boolean','java.lang.Boolean'} else -1
+    if type(value) is int:
+        if formal in {'int','java.lang.Integer'}: return 12 if -(2**31) <= value < 2**31 else -1
+        if formal in {'long','java.lang.Long'}: return 10 if -(2**63) <= value < 2**63 else -1
+        if formal in {'short','java.lang.Short'}: return 8 if -(2**15) <= value < 2**15 else -1
+        if formal in {'byte','java.lang.Byte'}: return 7 if -128 <= value <= 127 else -1
+        return 5 if formal in {'double','float','java.lang.Double','java.lang.Float'} else -1
+    if isinstance(value, float):
+        return 12 if formal in {'double','java.lang.Double'} else 8 if formal in {'float','java.lang.Float'} else -1
+    if isinstance(value, str):
+        if formal == 'java.lang.String': return 12
+        if formal == 'java.lang.CharSequence': return 10
+        if formal in {'char','java.lang.Character'}: return 8 if len(value) == 1 else -1
+        return 5 if _SCHEMA.get(formal, {}).get('enum') else -1
+    if isinstance(value, (bytes, bytearray)) and formal == 'byte[]': return 12
+    if isinstance(value, (list, tuple, bytes, bytearray)):
+        if formal.endswith('[]'):
+            scores = [_score(v, formal[:-2]) for v in value]
+            return -1 if any(v < 0 for v in scores) else 8
+        return 6 if formal in {'java.util.List','java.util.Collection','java.lang.Iterable','java.util.Set'} else -1
+    if isinstance(value, dict): return 8 if formal == 'java.util.Map' else -1
+    return -1
+
+
+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.
+        if len(values) == len(parameters) and isinstance(values[-1], (list, tuple)):
+            pass
+        else: values = values[:fixed] + [values[fixed:]]
+    elif len(values) != len(parameters): raise TypeError('Wrong argument count')
+    scores = [_score(v, p['type']) for v, p in zip(values, parameters)]
+    if any(s < 0 for s in scores): raise TypeError('Argument types do not match')
+    return values, sum(scores) - int(varargs)
+
+
+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):
+        candidates = []
+        for m in self.descriptor.members:
+            if self.instance is None and not m['static'] and self.__name__ != '<init>': continue
+            try: values, score = _bind(m, args, kwargs)
+            except TypeError: continue
+            candidates.append((score, m, values))
+        if not candidates:
+            raise TypeError(f'No matching overload for {self.owner.JAVA_CLASS}.{self.__name__}; see .overloads')
+        best_score = max(c[0] for c in candidates)
+        best = [c for c in candidates if c[0] == best_score]
+        # Drop less specific reference overloads for null/reference arguments.
+        if len(best) > 1:
+            specific = [c for c in best if all(c is other or all(
+                a['type'] == b['type'] or _is_java_type(a['type'], b['type'])
+                for a, b in zip(c[1]['parameters'], other[1]['parameters'])) for other in best)]
+            if len(specific) == 1: best = specific
+        signatures = {tuple(p['type'] for p in c[1]['parameters']) for c in best}
+        if len(signatures) > 1:
+            raise TypeError(f'Ambiguous Java overload for {self.__name__}: {sorted(signatures)}; use .overload(*types)')
+        _, member, values = best[0]
+        bridge = self.instance._remote._bridge if self.instance is not None else _default_bridge()
+        prepared = []
+        for p, v in zip(member['parameters'], values):
+            if callable(v) and not isinstance(v, JavaCallback):
+                interface = p['type']
+                if interface == 'java.lang.Object': interface = 'org.sikuli.script.ObserverCallBack'
+                v = JavaCallback(interface, v)
+            prepared.append(v)
+        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'])
+        if _score(value, self.field['type']) < 0: raise TypeError('Value does not match Java field type ' + self.field['type'])
+        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 __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 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):
+    if name in _TYPES: return _TYPES[name]
+    cls = JavaMeta(name.rsplit('.', 1)[-1].replace('$', '_'), (JavaObject,), {'JAVA_CLASS': name, '__module__': 'oculix.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__': 'oculix.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())