ggblab 0.9.3__py3-none-any.whl

ggblab/__init__.py

@@ -0,0 +1,44 @@
+"""ggblab: Interactive geometric scene construction with Python and GeoGebra.
+
+This package provides a JupyterLab extension that opens a GeoGebra applet
+and enables bidirectional communication between Python and GeoGebra through
+a dual-channel architecture (IPython Comm + Unix socket/TCP WebSocket).
+
+Main Components:
+    - GeoGebra: Primary interface for controlling GeoGebra applets
+    - ggb_comm: Communication layer (IPython Comm + out-of-band socket)
+    - ggb_construction: GeoGebra file (.ggb) loader and saver
+    - ggb_parser: Dependency graph parser for GeoGebra constructions
+
+Example:
+    >>> from ggblab import GeoGebra
+    >>> ggb = await GeoGebra().init()
+    >>> await ggb.command("A=(0,0)")
+    >>> value = await ggb.function("getValue", ["A"])
+"""
+
+try:
+    from ._version import __version__
+except ImportError:
+    # Fallback when using the package in dev mode without installing
+    # in editable mode with pip. It is highly recommended to install
+    # the package from a stable release or in editable mode: https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs
+    import warnings
+    warnings.warn("Importing 'ggblab' outside a proper installation.")
+    __version__ = "dev"
+
+from .parser import ggb_parser
+from .construction import ggb_construction
+from .comm import ggb_comm
+from .ggbapplet import GeoGebra, GeoGebraSyntaxError, GeoGebraSemanticsError
+
+def _jupyter_labextension_paths():
+    """Return the JupyterLab extension paths.
+    
+    Returns:
+        list: Extension metadata for JupyterLab.
+    """
+    return [{
+        "src": "labextension",
+        "dest": "ggblab"
+    }]

ggblab/_version.py

@@ -0,0 +1,4 @@
+# This file is auto-generated by Hatchling. As such, do not:
+#   - modify
+#   - track in version control e.g. be sure to add to .gitignore
+__version__ = VERSION = '0.9.3'

ggblab/comm.py

@@ -0,0 +1,243 @@
+import uuid
+import json
+# import ast
+import queue
+
+# import time
+import asyncio
+import threading
+
+import tempfile
+from websockets.asyncio.server import unix_serve, serve
+import os
+
+from IPython import get_ipython
+
+from .errors import GeoGebraAppletError
+
+
+class ggb_comm:
+    """Dual-channel communication layer for kernel↔widget messaging.
+    
+    Implements a combination of IPython Comm (primary) and out-of-band socket
+    (Unix domain socket on POSIX, TCP WebSocket on Windows) to enable message
+    delivery during cell execution when IPython Comm is blocked.
+    
+    IPython Comm cannot receive messages while a notebook cell is executing,
+    which breaks interactive workflows. The out-of-band socket solves this by
+    providing a secondary channel for GeoGebra responses.
+    
+    Architecture:
+        - IPython Comm: Command dispatch, event notifications, heartbeat
+        - Out-of-band socket: Response delivery during cell execution
+    
+    Comm target is fixed at 'ggblab-comm' because multiplexing via multiple
+    targets would not solve the IPython Comm receive limitation.
+    
+    Attributes:
+        target_comm: IPython Comm object
+        target_name (str): Comm target name ('ggblab-comm')
+        server_handle: WebSocket server handle
+        server_thread: Background thread running the socket server
+        clients (set): Currently connected WebSocket clients
+        socketPath (str): Unix domain socket path (POSIX)
+        wsPort (int): TCP port number (Windows)
+        recv_logs (dict): Response storage keyed by message ID
+        recv_events (queue.Queue): Event queue for frontend notifications
+    
+    See:
+        docs/architecture.md for detailed communication architecture.
+    """
+    # [Frontent to kernel callback - JupyterLab - Jupyter Community Forum]
+    # (https://discourse.jupyter.org/t/frontent-to-kernel-callback/1666)
+    recv_msgs = {}
+    recv_logs = {}
+    recv_events = queue.Queue()
+    logs = []
+    thread = None
+    mid = None
+
+    def __init__(self):
+        self.target_comm = None
+        self.target_name = 'ggblab-comm'
+        self.server_handle = None
+        self.server_thread = None
+        self.clients = set()
+        self.socketPath = None
+        self.wsPort = 0
+
+    # oob websocket (unix_domain socket in posix)
+    def start(self):
+        """Start the out-of-band socket server in a background thread.
+        
+        Creates a Unix domain socket (POSIX) or TCP WebSocket server (Windows)
+        and runs it in a daemon thread. The server listens for GeoGebra responses.
+        """
+        self.server_thread = threading.Thread(target=lambda: asyncio.run(self.server()), daemon=True)
+        self.server_thread.start()
+
+    def stop(self):
+        """Stop the out-of-band socket server."""
+        self.server_handle.close()
+
+    async def server(self):
+        if os.name in [ 'posix' ]:
+            _fd, self.socketPath = tempfile.mkstemp(prefix="/tmp/ggb_")
+            os.close(_fd)
+            os.remove(self.socketPath)
+            async with unix_serve(self.client_handle, path=self.socketPath) as self.server_handle:
+                await asyncio.Future()
+        else:
+           async with serve(self.client_handle, "localhost", 0) as self.server_handle:
+               self.wsPort = self.server_handle.sockets[0].getsockname()[1]
+               self.logs.append(f"WebSocket server started at ws://localhost:{self.wsPort}")
+               await asyncio.Future() 
+
+    async def client_handle(self, client_id):
+        self.clients.add(client_id)
+        self.logs.append(f"Client {client_id} registered.")
+
+        try:
+            async for msg in client_id:
+              # _data = ast.literal_eval(msg)
+                _data = json.loads(msg)
+                _id = _data.get('id')
+              # self.logs.append(f"Received message from client: {_id}")
+                
+                # Route event-type messages to recv_events queue
+                # Messages with 'id' are command responses; messages without 'id' are events.
+                # This enables:
+                # - Real-time error capture during cell execution
+                # - Dynamic scope learning from Applet error events
+                # - Cross-domain error pattern analysis
+                
+                if _id:
+                    # Response message: store in recv_logs for send_recv() to retrieve
+                    self.recv_logs[_id] = _data['payload']
+                else:
+                    # Event message: queue for event processing
+                    # Error handling is deferred to send_recv() for proper exception propagation
+                    self.recv_events.put(_data)
+        except Exception as e:
+            pass
+          # self.logs.append(f"Connection closed: {e}")
+        finally:
+            self.clients.remove(client_id)
+          # self.logs.append(f"Client disconnected: {client_id}")
+
+    # comm
+    def register_target(self):
+        get_ipython().kernel.comm_manager.register_target(
+            self.target_name,
+            self.register_target_cb)
+
+    def register_target_cb(self, comm, msg):
+        self.target_comm = comm
+
+        @comm.on_msg
+        def _recv(msg):
+            self.handle_recv(msg)
+
+        @comm.on_close
+        def _close():
+            self.target_comm = None
+
+    def unregister_target_cb(self, comm, msg):
+        self.target_comm.close()
+        self.target_comm = None
+
+    def handle_recv(self, msg):
+        # Note: All event-type messages are now routed to recv_events via the
+        # out-of-band socket (client_handle). This method is reserved for command
+        # responses (messages with id) sent via IPython Comm.
+        # 
+        # IPython Comm cannot receive messages during cell execution, so real-time
+        # error event processing happens on the out-of-band socket instead.
+        if isinstance(msg['content']['data'], str):
+            _data = json.loads(msg['content']['data'])
+        else:
+            _data = msg['content']['data']
+        
+        # All messages here are assumed to be responses with 'id'
+        # (event messages are handled via client_handle in the out-of-band socket)
+
+    def send(self, msg):
+        return self.target_comm.send(msg)
+
+    async def send_recv(self, msg):
+        """Send a message via IPython Comm and wait for response via out-of-band socket.
+        
+        This method:
+        1. Generates a unique message ID (UUID)
+        2. Sends the message via IPython Comm to the frontend
+        3. Waits for the response to arrive via the out-of-band socket
+        4. Raises GeoGebraAppletError if error events are received
+        5. Returns the response payload
+        
+        The 3-second timeout is sufficient for interactive operations.
+        For long-running operations, decompose into smaller steps.
+        
+        Args:
+            msg (dict or str): Message to send (will be JSON-serialized).
+        
+        Returns:
+            dict: Response payload from GeoGebra.
+            
+        Raises:
+            asyncio.TimeoutError: If no response arrives within 3 seconds.
+            GeoGebraAppletError: If the applet produces error events.
+            
+        Example:
+            >>> response = await comm.send_recv({
+            ...     "type": "command",
+            ...     "payload": "A=(0,0)"
+            ... })
+        """
+        try:
+            if isinstance(msg, str):
+                _data = json.loads(msg)
+            else:
+                _data = msg
+
+            _id = str(uuid.uuid4())
+            self.mid = _id
+            msg['id'] = _id
+            self.send(json.dumps(_data))
+            
+            # Wait for response with 3-second timeout
+            async def wait_for_response():
+                while not (_id in self.recv_logs):
+                    await asyncio.sleep(0.01)
+            
+            await asyncio.wait_for(wait_for_response(), timeout=3.0)
+            
+            value = self.recv_logs.pop(_id, None)
+            
+            # If response value is empty, check for error events
+            if value is None:
+                # Wait a bit for error events to arrive
+                await asyncio.sleep(0.5)
+                
+                # Check for error events in recv_events
+                error_messages = []
+                while True:
+                    try:
+                        event = self.recv_events.get_nowait()
+                        if event.get('type') == 'Error':
+                            error_messages.append(event.get('payload', 'Unknown error'))
+                    except queue.Empty:
+                        break
+                
+                # If errors were collected, raise GeoGebraAppletError
+                if error_messages:
+                    combined_message = '\n'.join(error_messages)
+                    raise GeoGebraAppletError(
+                        error_message=combined_message,
+                        error_type='AppletError'
+                    )
+            
+            return value
+        except (asyncio.TimeoutError, TimeoutError):
+            # On timeout, raise the error
+            print(f"TimeoutError in send_recv {msg}")
+            raise

ggblab/construction.py

@@ -0,0 +1,179 @@
+import base64
+import zipfile
+import json
+import xml.etree.ElementTree as ET
+import io
+import os
+
+from .schema import ggb_schema
+
+class ggb_construction:
+    """GeoGebra construction file (.ggb) loader and saver.
+    
+    Handles multiple file formats:
+    - .ggb files (base64-encoded ZIP archives)
+    - Plain ZIP archives
+    - JSON format
+    - Plain XML (geogebra.xml)
+    
+    The loader automatically detects file type from magic bytes and extracts
+    the construction XML. The geogebra_xml is automatically stripped to the
+    <construction> element and scientific notation is normalized.
+    
+    Attributes:
+        ggb_schema: XML schema for validation
+        source_file (str): Path to the loaded file
+        base64_buffer (bytes): Base64-encoded .ggb archive (if applicable)
+        geogebra_xml (str): Extracted construction XML
+    
+    Example:
+        >>> construction = ggb_construction()
+        >>> construction.load('myfile.ggb')
+        >>> construction.save('output.ggb')
+    """
+    def __init__(self):
+        self.ggb_schema = ggb_schema().schema
+    
+    def load(self, file):
+        """Load a GeoGebra construction from file.
+        
+        Supports multiple formats:
+        - Base64-encoded .ggb (starts with 'UEsD')
+        - ZIP archive (starts with 'PK')
+        - JSON format (starts with '{' or '[')
+        - Plain XML
+        
+        The construction XML is automatically extracted and normalized:
+        - Stripped to <construction> element only
+        - Scientific notation fixed (e-1 → E-1)
+        
+        Args:
+            file (str): Path to the .ggb, .zip, .json, or .xml file.
+        
+        Returns:
+            ggb_construction: Self reference for method chaining.
+            
+        Raises:
+            FileNotFoundError: If the file does not exist.
+            RuntimeError: If file loading fails.
+            
+        Example:
+            >>> c = ggb_construction().load('circle.ggb')
+            >>> print(c.geogebra_xml[:100])
+        """
+        self.source_file = file
+
+        self.base64_buffer = None
+        self.geogebra_xml = None
+
+        try:
+            with open(self.source_file, 'rb') as f:
+                def unzip(buff):
+                    with zipfile.ZipFile(io.BytesIO(base64.b64decode(buff)), 'r') as zf:
+                        # for fileinfo in zf.infolist():
+                        #     print(fileinfo)
+                        with zf.open('geogebra.xml', 'r') as zff:
+                            try:
+                                s = zff.read()
+                            except:
+                                pass
+                    return s
+
+                match tuple(f.read(4).decode()):
+                    case ('U', 'E', 's', 'D'):
+                        # base64 encoded zip
+                        f.close()
+                        with open(self.source_file, 'rb') as f2:
+                            self.base64_buffer = f2.read()  # base64.b64decode(f2.read())
+                            self.geogebra_xml = unzip(self.base64_buffer)
+                    case ('P', 'K', _, _):
+                        # zip
+                        f.close()
+                        with open(self.source_file, 'rb') as f2:
+                            # b64encode for sending GeoGebra Applet
+                            self.base64_buffer = base64.b64encode(f2.read())
+                            self.geogebra_xml = unzip(self.base64_buffer)
+                    case ('{', _, _, _) | ('[', _, _, _):
+                        # json
+                        f.close()
+                        with open(self.source_file, 'r', encoding='utf-8') as f2:
+                            self.base64_buffer = json.load(f2)
+                            for f in self.base64_buffer['archive']:
+                                if f['fileName'] == 'geogebra.xml':
+                                    self.geogebra_xml = f['fileContent']
+                    case _:
+                        # xml?
+                        with open(self.source_file, 'r', encoding='utf-8') as f2:
+                            self.geogebra_xml = f2.read()
+            # return self.initialize_dataframe(file)
+        except FileNotFoundError:
+            raise FileNotFoundError(f"File not found: {self.source_file}")
+        except Exception as e:
+            raise RuntimeError(f"Failed to load the file: {e}")
+
+        # strip to construction element and fix scientific notation
+        self.geogebra_xml = (ET.tostring(ET.fromstring(self.geogebra_xml)
+                                        .find('./construction'), encoding='unicode')
+                            .replace('e-1', 'E-1'))
+
+        return self
+    
+    def save(self, overwrite=False, file=None):
+        """Save the construction to a file.
+        
+        Saving behavior:
+        - If base64_buffer is set: writes decoded archive (.ggb format)
+        - If base64_buffer is None: writes plain XML (geogebra_xml)
+        - Target extension does not enforce format (e.g., saving to .ggb with
+          no base64_buffer will write plain XML bytes)
+        
+        Args:
+            overwrite (bool): If True, overwrite source_file. Defaults to False.
+            file (str, optional): Target file path. If None, auto-generates
+                next available filename (name_1.ggb, name_2.ggb, ...).
+        
+        Returns:
+            ggb_construction: Self reference for method chaining.
+            
+        Example:
+            >>> c = ggb_construction().load('circle.ggb')
+            >>> c.save()  # Saves to circle_1.ggb
+            >>> c.save(overwrite=True)  # Overwrites circle.ggb
+            >>> c.save(file='output.ggb')  # Saves to output.ggb
+        
+        Note:
+            getBase64() from the applet may not include non-XML artifacts
+            (thumbnails, etc.) from the original archive. Saving after API
+            changes produces a leaner .ggb file.
+        """
+
+        def get_next_revised_filename(filename):
+            """
+            Generates the next available non-existing filename by appending 
+            '_1', '_2', etc. before the file extension.
+            """
+            if not os.path.exists(filename):
+                return filename
+
+            root, ext = os.path.splitext(filename)
+            i = 1
+            new_filename = f"{root}_{i}{ext}"
+            
+            while os.path.exists(new_filename):
+                i += 1
+                new_filename = f"{root}_{i}{ext}"
+                
+            return new_filename
+
+        if file is None:
+            if overwrite:
+                file = self.source_file
+            else:
+                file = get_next_revised_filename(self.source_file)
+
+        with open(file, 'wb') as f:
+            if self.base64_buffer is not None:
+                f.write(base64.b64decode(self.base64_buffer))
+            else:
+                f.write(self.geogebra_xml.encode('utf-8'))
+        return self

ggblab/errors.py

@@ -0,0 +1,142 @@
+"""Custom exception hierarchy for ggblab.
+
+Exceptions are organized into two main branches:
+- Command validation errors: Caught before execution (syntax, semantics)
+- Applet errors: From GeoGebra responses during execution
+
+Exception Hierarchy:
+
+    GeoGebraError
+    ├── GeoGebraCommandError
+    │   ├── GeoGebraSyntaxError
+    │   │   Raised: Command string cannot be tokenized or has syntax errors
+    │   │
+    │   └── GeoGebraSemanticsError
+    │       Raised: Referenced objects don't exist in applet
+    │
+    └── GeoGebraAppletError
+        Raised: GeoGebra applet produces an error event (runtime errors)
+
+Usage Examples:
+
+    # Catch all GeoGebra errors
+    try:
+        await ggb.command("Circle(A, B)")
+    except GeoGebraError as e:
+        print(f"GeoGebra error: {e}")
+
+    # Catch only command validation errors
+    except GeoGebraCommandError as e:
+        print(f"Command validation failed: {e}")
+
+    # Catch specific validation errors
+    except GeoGebraSyntaxError as e:
+        print(f"Syntax error: {e.command}")
+    except GeoGebraSemanticsError as e:
+        print(f"Missing objects: {e.missing_objects}")
+
+    # Catch applet runtime errors
+    except GeoGebraAppletError as e:
+        print(f"Applet error: {e.error_message}")
+"""
+
+
+class GeoGebraError(Exception):
+    """Base exception for all GeoGebra-related errors.
+    
+    This is the root exception for all ggblab exceptions, allowing users to catch
+    any GeoGebra-related error with a single except clause.
+    """
+    pass
+
+
+class GeoGebraCommandError(GeoGebraError):
+    """Base exception for command validation errors.
+    
+    Raised when a command fails pre-flight validation (syntax or semantics).
+    This intermediate class groups command-related errors together, allowing users
+    to catch validation failures separately from applet errors.
+    """
+    pass
+
+
+class GeoGebraSyntaxError(GeoGebraCommandError):
+    """Exception raised for syntax errors in GeoGebra commands.
+    
+    Raised when a command string cannot be properly tokenized or
+    contains invalid syntax that prevents parsing.
+    
+    Attributes:
+        command (str): The command that caused the error
+        message (str): Explanation of the error
+    """
+    def __init__(self, command, message):
+        self.command = command
+        self.message = message
+        super().__init__(f"Syntax error in command '{command}': {message}")
+
+
+class GeoGebraSemanticsError(GeoGebraCommandError):
+    """Exception raised for semantic errors in GeoGebra commands.
+    
+    Raised when a command references objects that don't exist in the applet,
+    or violates other semantic constraints.
+    
+    Current capabilities:
+        - Object existence checking: Verifies referenced objects are present
+          in the applet via getAllObjectNames()
+    
+    Future capabilities (when metadata becomes available):
+        - Type checking: Validate argument types match command signatures
+        - Scope/visibility checking: Ensure objects are in appropriate scope
+        - Overload resolution: Handle commands with multiple signatures
+    
+    Limitations:
+        Complete command validation is not performed because GeoGebra does not
+        maintain a public, versioned, machine-readable command schema. The official
+        GitHub repository is outdated and does not reflect the live API.
+        
+        Strategy: Validation is passive—we check what we can (object existence),
+        then rely on GeoGebra to accept or reject the command. This is more robust
+        than maintaining a potentially incorrect static schema.
+    
+    Attributes:
+        command (str): The command that caused the error
+        message (str): Explanation of the error
+        missing_objects (list, optional): List of referenced but non-existent objects
+    """
+    def __init__(self, command, message, missing_objects=None):
+        self.command = command
+        self.message = message
+        self.missing_objects = missing_objects or []
+        super().__init__(f"Semantics error in command '{command}': {message}")
+
+
+class GeoGebraAppletError(GeoGebraError):
+    """Exception raised for errors from the GeoGebra applet.
+    
+    Raised when the GeoGebra applet produces an error event in response to
+    a command or API call. These errors originate from GeoGebra itself rather
+    than pre-flight validation.
+    
+    Attributes:
+        error_message (str): Error message from GeoGebra applet
+        command (str, optional): The command that triggered the applet error
+        error_type (str, optional): Error classification (e.g., 'AppletError')
+    
+    Example:
+        >>> raise GeoGebraAppletError(
+        ...     error_message="Unbalanced brackets",
+        ...     error_type="AppletError"
+        ... )
+    """
+    def __init__(self, error_message, command=None, error_type=None):
+        self.error_message = error_message
+        self.command = command
+        self.error_type = error_type
+        msg = f"GeoGebra applet error: {error_message}"
+        if command:
+            msg += f" (in command '{command}')"
+        if error_type:
+            msg += f" [{error_type}]"
+        super().__init__(msg)