aspectly-bridge 2.1.0__tar.gz

aspectly_bridge-2.1.0/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2022 Zhan Isaakian
+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.

aspectly_bridge-2.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: aspectly-bridge
+Version: 2.1.0
+Summary: Type-safe, bidirectional bridge between native Python (WebKitGTK) and JavaScript via the Aspectly protocol.
+Author-email: Zhan Isaakian <jeanisahkyan@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/JeanIsahakyan/aspectly
+Project-URL: Repository, https://github.com/JeanIsahakyan/aspectly
+Keywords: aspectly,bridge,webkitgtk,webview,javascript,ipc
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: webkitgtk
+Requires-Dist: PyGObject>=3.40; extra == "webkitgtk"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# aspectly-bridge (Python / WebKitGTK)
+
+[![PyPI](https://img.shields.io/pypi/v/aspectly-bridge?style=flat-square&logo=pypi&color=3776AB)](https://pypi.org/project/aspectly-bridge/)
+
+Type-safe, bidirectional bridge between native Python code and JavaScript
+running in a **WebKitGTK** web view (Linux desktop). Speaks the
+[Aspectly](https://github.com/JeanIsahakyan/aspectly) protocol, so the same
+`@aspectly/core` web content runs unchanged across every host.
+
+> WebKitGTK uses the **same** JS mechanism as WKWebView
+> (`window.webkit.messageHandlers.aspectly`), so the embedded web content
+> auto-detects this host through the existing `@aspectly/transports` WebKit
+> transport — no Flutter/Android-style extra transport needed.
+
+## Install
+
+```bash
+pip install aspectly-bridge
+
+# For the WebKitGTK browser bridge (Linux):
+#   system packages: gobject-introspection, gir1.2-webkit2-4.1 (or 4.0)
+pip install "aspectly-bridge[webkitgtk]"
+```
+
+The core (`BridgeHost`) is pure Python with no dependencies. Only the
+`WebKitGTKBrowserBridge` needs PyGObject + WebKit2GTK (Linux).
+
+## Usage
+
+```python
+from aspectly_bridge import BridgeHost
+from aspectly_bridge.webkitgtk import WebKitGTKBrowserBridge
+
+bridge = BridgeHost(WebKitGTKBrowserBridge(web_view))
+
+# Register handlers JS can call (before initialize).
+bridge.register_handler("ping", lambda params: "pong")
+bridge.register_handler("add", lambda params: params["a"] + params["b"])
+
+# Initialize (returns a Future; resolves when the handshake completes).
+bridge.initialize().result()
+
+# Call a JS method (returns a Future).
+result = bridge.send("greet", {"name": "Python"}).result()
+print(result["message"])
+```
+
+`send` and `initialize` return `concurrent.futures.Future`. In a GTK app, the
+result is delivered on the GLib main thread, so use `future.add_done_callback`
+or `GLib.idle_add` rather than blocking `.result()` on the UI thread.
+
+## API
+
+```python
+BridgeHost(browser_bridge, logger=None, timeout_ms=100000)
+
+register_handler(method, handler)     # handler(params) -> result
+unregister_handler(method)
+initialize(handlers=None) -> Future
+send(method, params=None, timeout_ms=None) -> Future
+process_message(message_json)
+
+is_initialized        # bool
+supported_methods     # list[str]  (JS-side methods)
+registered_methods    # list[str]  (Python-side handlers)
+on_initialized        # callable or None
+dispose()
+```
+
+`send` / handlers surface `BridgeException` with `error_type` one of
+`BridgeErrorType.{UNSUPPORTED_METHOD, METHOD_EXECUTION_TIMEOUT, REJECTED, BRIDGE_NOT_AVAILABLE}`.
+
+## Testing
+
+```bash
+cd python
+python -m pytest          # the pure-Python core (no GTK required)
+```
+
+See [`examples/webkitgtk`](../examples/webkitgtk) for a runnable GTK app.
+
+## Other platforms
+
+This is the Python / WebKitGTK host (PyPI `aspectly-bridge`, **2.1.0**). The same
+Aspectly protocol ships for Web (`@aspectly/web`), React Native
+(`@aspectly/react-native`), React Native Web/Expo
+(`@aspectly/react-native-web`), .NET CefSharp/WebView2
+(`Aspectly.Bridge.CefSharp` / `Aspectly.Bridge.WebView2`), iOS/macOS/visionOS
+(`AspectlyBridge`), Android (`io.github.jeanisahakyan:aspectly-bridge`), and Flutter
+(`aspectly_bridge`) — all at version **2.1.0**. See the
+[repository README](../README.md) for the full platform matrix.
+
+## License
+
+MIT

aspectly_bridge-2.1.0/README.md

@@ -0,0 +1,95 @@
+# aspectly-bridge (Python / WebKitGTK)
+
+[![PyPI](https://img.shields.io/pypi/v/aspectly-bridge?style=flat-square&logo=pypi&color=3776AB)](https://pypi.org/project/aspectly-bridge/)
+
+Type-safe, bidirectional bridge between native Python code and JavaScript
+running in a **WebKitGTK** web view (Linux desktop). Speaks the
+[Aspectly](https://github.com/JeanIsahakyan/aspectly) protocol, so the same
+`@aspectly/core` web content runs unchanged across every host.
+
+> WebKitGTK uses the **same** JS mechanism as WKWebView
+> (`window.webkit.messageHandlers.aspectly`), so the embedded web content
+> auto-detects this host through the existing `@aspectly/transports` WebKit
+> transport — no Flutter/Android-style extra transport needed.
+
+## Install
+
+```bash
+pip install aspectly-bridge
+
+# For the WebKitGTK browser bridge (Linux):
+#   system packages: gobject-introspection, gir1.2-webkit2-4.1 (or 4.0)
+pip install "aspectly-bridge[webkitgtk]"
+```
+
+The core (`BridgeHost`) is pure Python with no dependencies. Only the
+`WebKitGTKBrowserBridge` needs PyGObject + WebKit2GTK (Linux).
+
+## Usage
+
+```python
+from aspectly_bridge import BridgeHost
+from aspectly_bridge.webkitgtk import WebKitGTKBrowserBridge
+
+bridge = BridgeHost(WebKitGTKBrowserBridge(web_view))
+
+# Register handlers JS can call (before initialize).
+bridge.register_handler("ping", lambda params: "pong")
+bridge.register_handler("add", lambda params: params["a"] + params["b"])
+
+# Initialize (returns a Future; resolves when the handshake completes).
+bridge.initialize().result()
+
+# Call a JS method (returns a Future).
+result = bridge.send("greet", {"name": "Python"}).result()
+print(result["message"])
+```
+
+`send` and `initialize` return `concurrent.futures.Future`. In a GTK app, the
+result is delivered on the GLib main thread, so use `future.add_done_callback`
+or `GLib.idle_add` rather than blocking `.result()` on the UI thread.
+
+## API
+
+```python
+BridgeHost(browser_bridge, logger=None, timeout_ms=100000)
+
+register_handler(method, handler)     # handler(params) -> result
+unregister_handler(method)
+initialize(handlers=None) -> Future
+send(method, params=None, timeout_ms=None) -> Future
+process_message(message_json)
+
+is_initialized        # bool
+supported_methods     # list[str]  (JS-side methods)
+registered_methods    # list[str]  (Python-side handlers)
+on_initialized        # callable or None
+dispose()
+```
+
+`send` / handlers surface `BridgeException` with `error_type` one of
+`BridgeErrorType.{UNSUPPORTED_METHOD, METHOD_EXECUTION_TIMEOUT, REJECTED, BRIDGE_NOT_AVAILABLE}`.
+
+## Testing
+
+```bash
+cd python
+python -m pytest          # the pure-Python core (no GTK required)
+```
+
+See [`examples/webkitgtk`](../examples/webkitgtk) for a runnable GTK app.
+
+## Other platforms
+
+This is the Python / WebKitGTK host (PyPI `aspectly-bridge`, **2.1.0**). The same
+Aspectly protocol ships for Web (`@aspectly/web`), React Native
+(`@aspectly/react-native`), React Native Web/Expo
+(`@aspectly/react-native-web`), .NET CefSharp/WebView2
+(`Aspectly.Bridge.CefSharp` / `Aspectly.Bridge.WebView2`), iOS/macOS/visionOS
+(`AspectlyBridge`), Android (`io.github.jeanisahakyan:aspectly-bridge`), and Flutter
+(`aspectly_bridge`) — all at version **2.1.0**. See the
+[repository README](../README.md) for the full platform matrix.
+
+## License
+
+MIT

aspectly_bridge-2.1.0/aspectly_bridge/__init__.py

@@ -0,0 +1,22 @@
+"""Aspectly bridge for Python — type-safe, bidirectional communication between
+native Python (WebKitGTK) and JavaScript via the Aspectly protocol."""
+
+from .bridge_host import BridgeHost, DEFAULT_TIMEOUT_MS
+from .browser_bridge import BrowserBridge, BridgeLogger, NullLogger, ConsoleLogger
+from .errors import BridgeException
+from .protocol import BridgeErrorType, BridgeEventType, BridgeResultType
+
+__all__ = [
+    "BridgeHost",
+    "DEFAULT_TIMEOUT_MS",
+    "BrowserBridge",
+    "BridgeLogger",
+    "NullLogger",
+    "ConsoleLogger",
+    "BridgeException",
+    "BridgeErrorType",
+    "BridgeEventType",
+    "BridgeResultType",
+]
+
+__version__ = "2.1.0"

aspectly_bridge-2.1.0/aspectly_bridge/bridge_host.py

@@ -0,0 +1,295 @@
+import json
+import threading
+from concurrent.futures import Future
+
+from .browser_bridge import NullLogger
+from .errors import BridgeException
+from .protocol import BridgeErrorType, BridgeEventType, BridgeResultType
+
+_BRIDGE_EVENT_TYPE = "BridgeEvent"
+DEFAULT_TIMEOUT_MS = 100000
+
+
+class BridgeHost(object):
+    """Manages bidirectional communication between native Python code and
+    JavaScript via the Aspectly protocol. The Python equivalent of the .NET
+    ``BridgeHost``.
+
+    The host is loop-agnostic: ``send`` and ``initialize`` return
+    ``concurrent.futures.Future`` objects, and handlers are plain callables
+    ``handler(params) -> result`` (returning a JSON-encodable value or raising).
+    """
+
+    def __init__(self, browser_bridge, logger=None, timeout_ms=DEFAULT_TIMEOUT_MS):
+        self._browser = browser_bridge
+        self._logger = logger if logger is not None else NullLogger()
+        self._timeout_ms = timeout_ms
+        self._lock = threading.RLock()
+
+        self._initialized = False
+        self._remote_init_received = False
+        self._init_result_received = False
+        self._disposed = False
+        self._request_counter = 0
+        self._init_future = None
+
+        self._supported_methods = []
+        self._handlers = {}
+        self._pending = {}
+
+        self.on_initialized = None
+
+        self._browser.on_message = self.process_message
+        self._logger.info("[BridgeHost] Created and subscribed to messages")
+
+    # region properties
+
+    @property
+    def is_initialized(self):
+        with self._lock:
+            return self._initialized
+
+    @property
+    def supported_methods(self):
+        with self._lock:
+            return list(self._supported_methods)
+
+    @property
+    def registered_methods(self):
+        with self._lock:
+            return list(self._handlers.keys())
+
+    # region handler registration
+
+    def register_handler(self, method, handler):
+        with self._lock:
+            self._handlers[method] = handler
+        self._logger.info("[BridgeHost] Registered handler: %s" % method)
+
+    def unregister_handler(self, method):
+        with self._lock:
+            self._handlers.pop(method, None)
+        self._logger.info("[BridgeHost] Unregistered handler: %s" % method)
+
+    # region incoming
+
+    def process_message(self, message_json):
+        if not message_json:
+            return
+        self._logger.debug("[BridgeHost] Received: %s" % message_json)
+
+        try:
+            wrapper = json.loads(message_json)
+        except (ValueError, TypeError):
+            self._logger.debug("[BridgeHost] JSON parse error")
+            return
+
+        if not isinstance(wrapper, dict) or wrapper.get("type") != _BRIDGE_EVENT_TYPE:
+            return
+        event = wrapper.get("event")
+        if not isinstance(event, dict):
+            return
+        event_type = event.get("type")
+        data = event.get("data")
+
+        if event_type == BridgeEventType.INIT:
+            self._handle_init(data)
+        elif event_type == BridgeEventType.REQUEST:
+            self._handle_request(data)
+        elif event_type == BridgeEventType.RESULT:
+            self._handle_result(data)
+        elif event_type == BridgeEventType.INIT_RESULT:
+            with self._lock:
+                self._init_result_received = True
+            self._logger.info("[BridgeHost] InitResult received from JS")
+            self._try_resolve_init()
+
+    def _handle_init(self, data):
+        if isinstance(data, dict) and isinstance(data.get("methods"), list):
+            with self._lock:
+                self._supported_methods = [str(m) for m in data["methods"]]
+            self._logger.info(
+                "[BridgeHost] JS supports methods: %s" % ", ".join(self._supported_methods)
+            )
+        with self._lock:
+            self._remote_init_received = True
+        # Match the JS protocol: only send InitResult, not our Init.
+        self._send_event(BridgeEventType.INIT_RESULT, True)
+        self._logger.info("[BridgeHost] Sent InitResult")
+        self._try_resolve_init()
+
+    def _try_resolve_init(self):
+        with self._lock:
+            should = (
+                self._init_result_received
+                and self._remote_init_received
+                and not self._initialized
+            )
+            if should:
+                self._initialized = True
+                future = self._init_future
+                self._init_future = None
+            else:
+                future = None
+        if should:
+            if future is not None and not future.done():
+                future.set_result(None)
+            self._logger.info("[BridgeHost] Bridge fully initialized")
+            callback = self.on_initialized
+            if callback is not None:
+                callback()
+
+    def _handle_request(self, data):
+        if not isinstance(data, dict):
+            return
+        method = data.get("method")
+        request_id = data.get("request_id")
+        if method is None or request_id is None:
+            return
+        params = data.get("params", {})
+
+        with self._lock:
+            handler = self._handlers.get(method)
+
+        if handler is None:
+            self._logger.warn("[BridgeHost] Unknown method: %s" % method)
+            result = self._error_result(
+                method, request_id, BridgeErrorType.UNSUPPORTED_METHOD,
+                "Method '%s' is not registered" % method,
+            )
+        else:
+            try:
+                value = handler(params)
+                result = {
+                    "type": BridgeResultType.SUCCESS,
+                    "method": method,
+                    "request_id": request_id,
+                    "data": value,
+                }
+                self._logger.debug("[BridgeHost] Handler '%s' completed successfully" % method)
+            except BridgeException as e:
+                self._logger.error("[BridgeHost] Handler '%s' failed" % method, e)
+                result = self._error_result(method, request_id, BridgeErrorType.REJECTED, e.message)
+            except Exception as e:  # noqa: BLE001
+                self._logger.error("[BridgeHost] Handler '%s' failed" % method, e)
+                result = self._error_result(method, request_id, BridgeErrorType.REJECTED, str(e))
+
+        self._send_event(BridgeEventType.RESULT, result)
+
+    def _handle_result(self, data):
+        if not isinstance(data, dict):
+            return
+        request_id = data.get("request_id")
+        if request_id is None:
+            return
+        with self._lock:
+            future = self._pending.pop(request_id, None)
+        if future is None or future.done():
+            return
+
+        if data.get("type") == BridgeResultType.SUCCESS:
+            future.set_result(data.get("data"))
+        else:
+            error = data.get("error") or {}
+            error_type = error.get("error_type") or BridgeErrorType.REJECTED
+            message = error.get("error_message")
+            future.set_exception(BridgeException(error_type, message))
+
+    # region outgoing
+
+    def _send_event(self, event_type, data):
+        wrapper = {"type": _BRIDGE_EVENT_TYPE, "event": {"type": event_type, "data": data}}
+        json_text = json.dumps(wrapper)
+        # Double-encode to produce a safe JS string literal (matches .NET / Swift).
+        js_literal = json.dumps(json_text)
+        script = "(function(){window.postMessage(%s, '*');return true;})();" % js_literal
+        try:
+            self._browser.execute_script(script)
+            self._logger.debug("[BridgeHost] Sent: %s" % json_text)
+        except Exception as e:  # noqa: BLE001
+            self._logger.error("[BridgeHost] Failed to send event", e)
+
+    def send(self, method, params=None, timeout_ms=None):
+        """Send a request to the JavaScript side. Returns a ``Future`` that
+        resolves with the result or raises ``BridgeException``."""
+        if not self.is_initialized:
+            raise BridgeException(BridgeErrorType.BRIDGE_NOT_AVAILABLE, "Bridge not initialized")
+        with self._lock:
+            supported = method in self._supported_methods
+        if not supported:
+            raise BridgeException(
+                BridgeErrorType.UNSUPPORTED_METHOD,
+                "Method '%s' not supported by JS side" % method,
+            )
+
+        timeout = timeout_ms if timeout_ms is not None else self._timeout_ms
+        with self._lock:
+            self._request_counter += 1
+            request_id = str(self._request_counter)
+            future = Future()
+            self._pending[request_id] = future
+
+        self._send_event(BridgeEventType.REQUEST, {
+            "method": method,
+            "request_id": request_id,
+            "params": params if params is not None else {},
+        })
+        self._logger.debug("[BridgeHost] Sent request: %s (id=%s)" % (method, request_id))
+
+        def on_timeout():
+            with self._lock:
+                pending = self._pending.pop(request_id, None)
+            if pending is not None and not pending.done():
+                pending.set_exception(BridgeException(
+                    BridgeErrorType.METHOD_EXECUTION_TIMEOUT,
+                    "Request '%s' timed out after %dms" % (method, timeout),
+                ))
+
+        timer = threading.Timer(timeout / 1000.0, on_timeout)
+        timer.daemon = True
+        timer.start()
+        future.add_done_callback(lambda _f: timer.cancel())
+        return future
+
+    def initialize(self, handlers=None):
+        """Register handlers and send ``Init``; returns a ``Future`` that
+        resolves when the handshake completes."""
+        if handlers:
+            for method, handler in handlers.items():
+                self.register_handler(method, handler)
+        with self._lock:
+            future = Future()
+            self._init_future = future
+            methods = list(self._handlers.keys())
+        self._send_event(BridgeEventType.INIT, {"methods": methods})
+        self._logger.info("[BridgeHost] Sent Init with methods: %s" % ", ".join(methods))
+        return future
+
+    def dispose(self):
+        with self._lock:
+            if self._disposed:
+                return
+            self._disposed = True
+            pending = list(self._pending.values())
+            self._pending.clear()
+            init_future = self._init_future
+            self._init_future = None
+
+        self._browser.on_message = None
+        self._browser.dispose()
+
+        cancellation = BridgeException(BridgeErrorType.BRIDGE_NOT_AVAILABLE, "Bridge disposed")
+        if init_future is not None and not init_future.done():
+            init_future.set_exception(cancellation)
+        for future in pending:
+            if not future.done():
+                future.set_exception(cancellation)
+        self._logger.info("[BridgeHost] Disposed")
+
+    def _error_result(self, method, request_id, error_type, message):
+        return {
+            "type": BridgeResultType.ERROR,
+            "method": method,
+            "request_id": request_id,
+            "error": {"error_type": error_type, "error_message": message},
+        }

aspectly_bridge-2.1.0/aspectly_bridge/browser_bridge.py

@@ -0,0 +1,81 @@
+from abc import ABC, abstractmethod
+
+
+class BrowserBridge(ABC):
+    """Abstraction for browser message passing.
+
+    Implement this for any web view (WebKitGTK, a mock for testing, etc.).
+    The Python equivalent of .NET's ``IBrowserBridge``.
+
+    ``BridgeHost`` assigns ``on_message`` (a callable taking the message string)
+    when it is constructed.
+    """
+
+    on_message = None
+
+    @property
+    @abstractmethod
+    def is_ready(self):
+        """Whether the browser is ready for communication."""
+
+    @abstractmethod
+    def execute_script(self, script):
+        """Send a message to JavaScript by executing ``script``."""
+
+    @abstractmethod
+    def dispose(self):
+        """Release resources and detach from the underlying web view."""
+
+
+class BridgeLogger(ABC):
+    """Simple logging interface for ``BridgeHost``."""
+
+    @abstractmethod
+    def debug(self, message):
+        ...
+
+    @abstractmethod
+    def info(self, message):
+        ...
+
+    @abstractmethod
+    def warn(self, message):
+        ...
+
+    @abstractmethod
+    def error(self, message, error=None):
+        ...
+
+
+class NullLogger(BridgeLogger):
+    """Discards all log messages."""
+
+    def debug(self, message):
+        pass
+
+    def info(self, message):
+        pass
+
+    def warn(self, message):
+        pass
+
+    def error(self, message, error=None):
+        pass
+
+
+class ConsoleLogger(BridgeLogger):
+    """Prints log messages to stdout."""
+
+    def debug(self, message):
+        print("[DEBUG] %s" % message)
+
+    def info(self, message):
+        print("[INFO] %s" % message)
+
+    def warn(self, message):
+        print("[WARN] %s" % message)
+
+    def error(self, message, error=None):
+        print("[ERROR] %s" % message)
+        if error is not None:
+            print("  Error: %s" % error)

aspectly_bridge-2.1.0/aspectly_bridge/errors.py

@@ -0,0 +1,16 @@
+from .protocol import BridgeErrorType
+
+
+class BridgeException(Exception):
+    """Exception type for bridge protocol errors.
+
+    The Python equivalent of .NET's ``BridgeException`` / Swift's ``BridgeError``.
+    """
+
+    def __init__(self, error_type, message=None):
+        self.error_type = error_type
+        self.message = message if message is not None else error_type
+        super().__init__(self.message)
+
+    def __repr__(self):
+        return "BridgeException(%s): %s" % (self.error_type, self.message)

aspectly_bridge-2.1.0/aspectly_bridge/protocol.py

@@ -0,0 +1,20 @@
+"""Protocol constants for the Aspectly bridge. Values match @aspectly/core."""
+
+
+class BridgeEventType:
+    INIT = "Init"
+    INIT_RESULT = "InitResult"
+    REQUEST = "Request"
+    RESULT = "Result"
+
+
+class BridgeResultType:
+    SUCCESS = "Success"
+    ERROR = "Error"
+
+
+class BridgeErrorType:
+    METHOD_EXECUTION_TIMEOUT = "METHOD_EXECUTION_TIMEOUT"
+    UNSUPPORTED_METHOD = "UNSUPPORTED_METHOD"
+    REJECTED = "REJECTED"
+    BRIDGE_NOT_AVAILABLE = "BRIDGE_NOT_AVAILABLE"

aspectly_bridge-2.1.0/aspectly_bridge/webkitgtk.py

@@ -0,0 +1,76 @@
+"""WebKitGTK browser bridge (Linux). Requires PyGObject + WebKit2GTK.
+
+JS <-> native uses the same mechanism as WKWebView, so the embedded web content
+auto-detects this host via the ``@aspectly/transports`` WebKit transport
+(``window.webkit.messageHandlers.aspectly``) — no extra JS is required.
+"""
+
+from .browser_bridge import BrowserBridge
+
+_GTK_IMPORT_ERROR = None
+try:  # pragma: no cover - exercised only on Linux with GTK installed
+    import gi
+
+    gi.require_version("WebKit2", "4.1")
+    from gi.repository import WebKit2  # noqa: F401
+
+    _HAS_GTK = True
+except Exception as exc:  # noqa: BLE001
+    _HAS_GTK = False
+    _GTK_IMPORT_ERROR = exc
+
+
+class WebKitGTKBrowserBridge(BrowserBridge):
+    """``BrowserBridge`` implementation for a WebKitGTK ``WebKit2.WebView``.
+
+    - JS -> native: ``window.webkit.messageHandlers.<name>.postMessage(message)``
+      delivered via a registered script message handler.
+    - native -> JS: ``web_view.run_javascript("window.postMessage(...)")``.
+
+    All WebView access must happen on the GTK main thread.
+    """
+
+    DEFAULT_HANDLER_NAME = "aspectly"
+
+    def __init__(self, web_view, handler_name=DEFAULT_HANDLER_NAME):
+        if not _HAS_GTK:
+            raise RuntimeError(
+                "WebKitGTKBrowserBridge requires PyGObject + WebKit2GTK (Linux). "
+                "Import failed: %s" % _GTK_IMPORT_ERROR
+            )
+        self._web_view = web_view
+        self._handler_name = handler_name
+        self._disposed = False
+        self.on_message = None
+
+        ucm = web_view.get_user_content_manager()
+        ucm.register_script_message_handler(handler_name)
+        ucm.connect("script-message-received::" + handler_name, self._on_script_message)
+
+    @property
+    def is_ready(self):
+        return not self._disposed
+
+    def _on_script_message(self, user_content_manager, js_message):
+        try:
+            value = js_message.get_js_value().to_string()
+        except Exception:  # noqa: BLE001
+            value = None
+        if value is not None and self.on_message is not None:
+            self.on_message(value)
+
+    def execute_script(self, script):
+        # run_javascript must be called on the GTK main thread.
+        self._web_view.run_javascript(script, None, None, None)
+
+    def dispose(self):
+        if self._disposed:
+            return
+        self._disposed = True
+        self.on_message = None
+        try:
+            self._web_view.get_user_content_manager().unregister_script_message_handler(
+                self._handler_name
+            )
+        except Exception:  # noqa: BLE001
+            pass

aspectly_bridge-2.1.0/aspectly_bridge.egg-info/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: aspectly-bridge
+Version: 2.1.0
+Summary: Type-safe, bidirectional bridge between native Python (WebKitGTK) and JavaScript via the Aspectly protocol.
+Author-email: Zhan Isaakian <jeanisahkyan@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/JeanIsahakyan/aspectly
+Project-URL: Repository, https://github.com/JeanIsahakyan/aspectly
+Keywords: aspectly,bridge,webkitgtk,webview,javascript,ipc
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: webkitgtk
+Requires-Dist: PyGObject>=3.40; extra == "webkitgtk"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# aspectly-bridge (Python / WebKitGTK)
+
+[![PyPI](https://img.shields.io/pypi/v/aspectly-bridge?style=flat-square&logo=pypi&color=3776AB)](https://pypi.org/project/aspectly-bridge/)
+
+Type-safe, bidirectional bridge between native Python code and JavaScript
+running in a **WebKitGTK** web view (Linux desktop). Speaks the
+[Aspectly](https://github.com/JeanIsahakyan/aspectly) protocol, so the same
+`@aspectly/core` web content runs unchanged across every host.
+
+> WebKitGTK uses the **same** JS mechanism as WKWebView
+> (`window.webkit.messageHandlers.aspectly`), so the embedded web content
+> auto-detects this host through the existing `@aspectly/transports` WebKit
+> transport — no Flutter/Android-style extra transport needed.
+
+## Install
+
+```bash
+pip install aspectly-bridge
+
+# For the WebKitGTK browser bridge (Linux):
+#   system packages: gobject-introspection, gir1.2-webkit2-4.1 (or 4.0)
+pip install "aspectly-bridge[webkitgtk]"
+```
+
+The core (`BridgeHost`) is pure Python with no dependencies. Only the
+`WebKitGTKBrowserBridge` needs PyGObject + WebKit2GTK (Linux).
+
+## Usage
+
+```python
+from aspectly_bridge import BridgeHost
+from aspectly_bridge.webkitgtk import WebKitGTKBrowserBridge
+
+bridge = BridgeHost(WebKitGTKBrowserBridge(web_view))
+
+# Register handlers JS can call (before initialize).
+bridge.register_handler("ping", lambda params: "pong")
+bridge.register_handler("add", lambda params: params["a"] + params["b"])
+
+# Initialize (returns a Future; resolves when the handshake completes).
+bridge.initialize().result()
+
+# Call a JS method (returns a Future).
+result = bridge.send("greet", {"name": "Python"}).result()
+print(result["message"])
+```
+
+`send` and `initialize` return `concurrent.futures.Future`. In a GTK app, the
+result is delivered on the GLib main thread, so use `future.add_done_callback`
+or `GLib.idle_add` rather than blocking `.result()` on the UI thread.
+
+## API
+
+```python
+BridgeHost(browser_bridge, logger=None, timeout_ms=100000)
+
+register_handler(method, handler)     # handler(params) -> result
+unregister_handler(method)
+initialize(handlers=None) -> Future
+send(method, params=None, timeout_ms=None) -> Future
+process_message(message_json)
+
+is_initialized        # bool
+supported_methods     # list[str]  (JS-side methods)
+registered_methods    # list[str]  (Python-side handlers)
+on_initialized        # callable or None
+dispose()
+```
+
+`send` / handlers surface `BridgeException` with `error_type` one of
+`BridgeErrorType.{UNSUPPORTED_METHOD, METHOD_EXECUTION_TIMEOUT, REJECTED, BRIDGE_NOT_AVAILABLE}`.
+
+## Testing
+
+```bash
+cd python
+python -m pytest          # the pure-Python core (no GTK required)
+```
+
+See [`examples/webkitgtk`](../examples/webkitgtk) for a runnable GTK app.
+
+## Other platforms
+
+This is the Python / WebKitGTK host (PyPI `aspectly-bridge`, **2.1.0**). The same
+Aspectly protocol ships for Web (`@aspectly/web`), React Native
+(`@aspectly/react-native`), React Native Web/Expo
+(`@aspectly/react-native-web`), .NET CefSharp/WebView2
+(`Aspectly.Bridge.CefSharp` / `Aspectly.Bridge.WebView2`), iOS/macOS/visionOS
+(`AspectlyBridge`), Android (`io.github.jeanisahakyan:aspectly-bridge`), and Flutter
+(`aspectly_bridge`) — all at version **2.1.0**. See the
+[repository README](../README.md) for the full platform matrix.
+
+## License
+
+MIT

aspectly_bridge-2.1.0/aspectly_bridge.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+aspectly_bridge/__init__.py
+aspectly_bridge/bridge_host.py
+aspectly_bridge/browser_bridge.py
+aspectly_bridge/errors.py
+aspectly_bridge/protocol.py
+aspectly_bridge/webkitgtk.py
+aspectly_bridge.egg-info/PKG-INFO
+aspectly_bridge.egg-info/SOURCES.txt
+aspectly_bridge.egg-info/dependency_links.txt
+aspectly_bridge.egg-info/requires.txt
+aspectly_bridge.egg-info/top_level.txt
+tests/test_bridge_host.py

aspectly_bridge-2.1.0/aspectly_bridge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aspectly_bridge-2.1.0/aspectly_bridge.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+pytest>=7.0
+
+[webkitgtk]
+PyGObject>=3.40

aspectly_bridge-2.1.0/aspectly_bridge.egg-info/top_level.txt

@@ -0,0 +1 @@
+aspectly_bridge

aspectly_bridge-2.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aspectly-bridge"
+version = "2.1.0"
+description = "Type-safe, bidirectional bridge between native Python (WebKitGTK) and JavaScript via the Aspectly protocol."
+readme = "README.md"
+requires-python = ">=3.7"
+license = { text = "MIT" }
+authors = [{ name = "Zhan Isaakian", email = "jeanisahkyan@gmail.com" }]
+keywords = ["aspectly", "bridge", "webkitgtk", "webview", "javascript", "ipc"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Operating System :: POSIX :: Linux",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/JeanIsahakyan/aspectly"
+Repository = "https://github.com/JeanIsahakyan/aspectly"
+
+[project.optional-dependencies]
+# Linux only — requires system GObject-Introspection + WebKit2GTK libraries.
+webkitgtk = ["PyGObject>=3.40"]
+dev = ["pytest>=7.0"]
+
+[tool.setuptools.packages.find]
+include = ["aspectly_bridge*"]

aspectly_bridge-2.1.0/setup.cfg

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

aspectly_bridge-2.1.0/tests/test_bridge_host.py

@@ -0,0 +1,238 @@
+import json
+
+import pytest
+
+from aspectly_bridge import (
+    BridgeErrorType,
+    BridgeException,
+    BridgeHost,
+    BrowserBridge,
+)
+
+
+class MockBrowserBridge(BrowserBridge):
+    def __init__(self):
+        self.on_message = None
+        self.sent = []
+        self.disposed = False
+
+    @property
+    def is_ready(self):
+        return True
+
+    def execute_script(self, script):
+        self.sent.append(script)
+
+    def dispose(self):
+        self.disposed = True
+
+
+def msg(event_type, data):
+    return json.dumps({"type": "BridgeEvent", "event": {"type": event_type, "data": data}})
+
+
+def handshake(bridge, js_methods):
+    fut = bridge.initialize()
+    bridge.process_message(msg("Init", {"methods": js_methods}))
+    bridge.process_message(msg("InitResult", True))
+    fut.result(timeout=1)
+
+
+@pytest.fixture
+def setup():
+    mock = MockBrowserBridge()
+    bridge = BridgeHost(mock)
+    yield bridge, mock
+    bridge.dispose()
+
+
+# --- handler registration ---
+
+def test_register_handler_adds(setup):
+    bridge, _ = setup
+    bridge.register_handler("test", lambda p: "result")
+    assert "test" in bridge.registered_methods
+
+
+def test_unregister_handler_removes(setup):
+    bridge, _ = setup
+    bridge.register_handler("test", lambda p: "result")
+    bridge.unregister_handler("test")
+    assert "test" not in bridge.registered_methods
+
+
+def test_same_name_overwrites(setup):
+    bridge, mock = setup
+    bridge.register_handler("test", lambda p: "first")
+    bridge.register_handler("test", lambda p: "second")
+    bridge.process_message(msg("Request", {"method": "test", "request_id": "1", "params": {}}))
+    assert "second" in mock.sent[-1]
+
+
+# --- init handshake ---
+
+def test_init_updates_supported(setup):
+    bridge, _ = setup
+    bridge.process_message(msg("Init", {"methods": ["a", "b"]}))
+    assert "a" in bridge.supported_methods and "b" in bridge.supported_methods
+
+
+def test_handle_init_only_sends_init_result(setup):
+    bridge, mock = setup
+    bridge.register_handler("myMethod", lambda p: "r")
+    bridge.process_message(msg("Init", {"methods": ["jsMethod"]}))
+    assert len(mock.sent) == 1
+    assert "InitResult" in mock.sent[0]
+
+
+def test_initializes_only_when_both(setup):
+    bridge, _ = setup
+    fired = []
+    bridge.on_initialized = lambda: fired.append(True)
+    bridge.process_message(msg("InitResult", True))
+    assert not bridge.is_initialized
+    assert not fired
+    bridge.process_message(msg("Init", {"methods": ["jsMethod"]}))
+    assert bridge.is_initialized
+    assert fired
+
+
+def test_initialize_waits_for_both(setup):
+    bridge, _ = setup
+    handshake(bridge, ["jsMethod"])
+    assert bridge.is_initialized
+    assert "jsMethod" in bridge.supported_methods
+
+
+def test_initialize_with_handlers(setup):
+    bridge, _ = setup
+    fut = bridge.initialize({"m1": lambda p: "r1", "m2": lambda p: "r2"})
+    assert "m1" in bridge.registered_methods and "m2" in bridge.registered_methods
+    bridge.process_message(msg("Init", {"methods": ["jsMethod"]}))
+    bridge.process_message(msg("InitResult", True))
+    fut.result(timeout=1)
+    assert bridge.is_initialized
+
+
+# --- incoming requests ---
+
+def test_request_calls_handler(setup):
+    bridge, _ = setup
+    called = []
+    bridge.register_handler("m", lambda p: called.append(True) or {"ok": True})
+    bridge.process_message(msg("Request", {"method": "m", "request_id": "1", "params": {}}))
+    assert called
+
+
+def test_unknown_method_error(setup):
+    bridge, mock = setup
+    bridge.process_message(msg("Request", {"method": "nope", "request_id": "1", "params": {}}))
+    assert "UNSUPPORTED_METHOD" in mock.sent[-1]
+
+
+def test_handler_returns_data(setup):
+    bridge, mock = setup
+    bridge.register_handler("m", lambda p: {"value": 42})
+    bridge.process_message(msg("Request", {"method": "m", "request_id": "1", "params": {}}))
+    assert "Success" in mock.sent[-1] and "42" in mock.sent[-1]
+
+
+def test_handler_throws_rejected(setup):
+    bridge, mock = setup
+
+    def boom(p):
+        raise RuntimeError("boom")
+
+    bridge.register_handler("m", boom)
+    bridge.process_message(msg("Request", {"method": "m", "request_id": "1", "params": {}}))
+    assert "REJECTED" in mock.sent[-1] and "boom" in mock.sent[-1]
+
+
+def test_typed_params(setup):
+    bridge, mock = setup
+    bridge.register_handler("add", lambda p: p["a"] + p["b"])
+    bridge.process_message(msg("Request", {"method": "add", "request_id": "1", "params": {"a": 10, "b": 20}}))
+    assert "30" in mock.sent[-1]
+
+
+# --- sending requests ---
+
+def test_send_success(setup):
+    bridge, _ = setup
+    handshake(bridge, ["jsMethod"])
+    fut = bridge.send("jsMethod")
+    bridge.process_message(msg("Result", {"type": "Success", "data": "test result", "request_id": "1"}))
+    assert fut.result(timeout=1) == "test result"
+
+
+def test_send_error(setup):
+    bridge, _ = setup
+    handshake(bridge, ["jsMethod"])
+    fut = bridge.send("jsMethod")
+    bridge.process_message(msg("Result", {
+        "type": "Error",
+        "error": {"error_type": "REJECTED", "error_message": "failed"},
+        "request_id": "1",
+    }))
+    with pytest.raises(BridgeException) as exc:
+        fut.result(timeout=1)
+    assert exc.value.error_type == BridgeErrorType.REJECTED
+    assert exc.value.message == "failed"
+
+
+def test_send_timeout(setup):
+    bridge, _ = setup
+    handshake(bridge, ["jsMethod"])
+    fut = bridge.send("jsMethod", None, 50)
+    with pytest.raises(BridgeException) as exc:
+        fut.result(timeout=1)
+    assert exc.value.error_type == BridgeErrorType.METHOD_EXECUTION_TIMEOUT
+
+
+def test_send_before_init(setup):
+    bridge, _ = setup
+    with pytest.raises(BridgeException) as exc:
+        bridge.send("m")
+    assert exc.value.error_type == BridgeErrorType.BRIDGE_NOT_AVAILABLE
+
+
+def test_send_unsupported(setup):
+    bridge, _ = setup
+    handshake(bridge, ["other"])
+    with pytest.raises(BridgeException) as exc:
+        bridge.send("m")
+    assert exc.value.error_type == BridgeErrorType.UNSUPPORTED_METHOD
+
+
+# --- ignored messages ---
+
+def test_empty(setup):
+    bridge, mock = setup
+    bridge.process_message("")
+    assert mock.sent == []
+
+
+def test_invalid_json(setup):
+    bridge, mock = setup
+    bridge.process_message("not json {")
+    assert mock.sent == []
+
+
+def test_non_bridge_event(setup):
+    bridge, mock = setup
+    bridge.process_message('{"type":"Other","data":{}}')
+    assert mock.sent == []
+
+
+# --- dispose ---
+
+def test_dispose_disposes_browser(setup):
+    bridge, mock = setup
+    bridge.dispose()
+    assert mock.disposed
+
+
+def test_dispose_twice(setup):
+    bridge, _ = setup
+    bridge.dispose()
+    bridge.dispose()