xllify 0.8.9__py3-none-any.whl

xllify/XLLIFY_DIST_VERSION

@@ -0,0 +1,2 @@
+0.8.9
+

xllify/__init__.py

@@ -0,0 +1,101 @@
+"""
+xllify - Python SDK for creating Excel XLL add-ins
+
+This package provides a simple way to expose Python functions to Excel
+via xllify using RPC.
+"""
+
+from xllify.rpc_server import XllifyRPCServer, Parameter
+from xllify.rtd_client import RTDClient, TopicUpdate, RTDCommand, CellValue, Matrix, ExcelValue
+
+__version__ = "0.8.7"
+__all__ = [
+    "XllifyRPCServer",
+    "Parameter",
+    "RTDClient",
+    "TopicUpdate",
+    "RTDCommand",
+    "CellValue",
+    "Matrix",
+    "ExcelValue",
+    "get_server",
+    "fn",
+    "start_server",
+    "configure_batching",
+    "configure_spawn_count",
+]
+
+# Create default server instance for convenience
+_default_server = None
+
+# Global spawn count configuration
+_spawn_count: int = 1
+
+
+def get_server() -> XllifyRPCServer:
+    """Get or create the default XllifyRPCServer instance."""
+    global _default_server
+    if _default_server is None:
+        _default_server = XllifyRPCServer()
+    return _default_server
+
+
+# Convenience exports
+fn = lambda *args, **kwargs: get_server().fn(*args, **kwargs)
+fn.__doc__ = """Decorator to register a Python function as an Excel function. Alias for XllifyRPCServer.fn()"""
+
+start_server = lambda: get_server().start()
+start_server.__doc__ = (
+    """Start the default RPC server. This is an alias to XllifyRPCServer.start()"""
+)
+
+
+def configure_batching(
+    enabled: bool = True, batch_size: int = 500, batch_timeout_ms: int = 50
+) -> None:
+    """
+    Configure batching behavior for RTD updates on the default server.
+
+    Call this before starting the server to customize batching settings.
+    Batching improves performance by sending multiple updates together.
+
+    Args:
+        enabled: Enable batching (default: True)
+        batch_size: Maximum number of updates to batch together (default: 500)
+        batch_timeout_ms: Maximum time to wait before flushing batch in milliseconds (default: 50)
+
+    Example:
+        import xllify
+
+        xllify.configure_batching(batch_size=1000, batch_timeout_ms=100)
+
+        @xllify.fn("xllipy.Hello")
+        def hello(name: str) -> str:
+            return f"Hello, {name}!"
+    """
+    get_server().configure_batching(
+        enabled=enabled, batch_size=batch_size, batch_timeout_ms=batch_timeout_ms
+    )
+
+
+def configure_spawn_count(count: int) -> None:
+    """
+    Configure the number of Python processes to spawn for this module.
+
+    This function both sets a runtime global that the RPC server reads and
+    serves as a marker for funcinfo to extract the spawn_count value.
+
+    Args:
+        count: Number of processes to spawn (must be positive)
+
+    Example:
+        import xllify
+
+        xllify.configure_spawn_count(4)
+
+        @xllify.fn("xllipy.Hello")
+        def hello(name: str) -> str:
+            return f"Hello, {name}!"
+    """
+    global _spawn_count
+    _spawn_count = count

xllify/__main__.py

@@ -0,0 +1,343 @@
+"""
+CLI entry point for running xllify Python scripts
+
+Usage:
+    python -m xllify my_functions.py
+    python -m xllify my_functions.py --process-name myapp
+"""
+
+import sys
+import argparse
+import importlib.util
+import os
+import time
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Configure logging based on environment variable
+if os.getenv("XLLIFY_PY_DEBUG"):
+    logging.basicConfig(level=logging.DEBUG, format="%(levelname)s: %(message)s")
+else:
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+
+
+def load_module_from_file(file_path: str, module_name: str = "xllify_user_module"):
+    """Load a Python module from a file path"""
+    spec = importlib.util.spec_from_file_location(module_name, file_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Could not load module from {file_path}")
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def run_server_with_reload(file_path: str, server_name: str, xll_name: str):
+    """
+    Run the server with auto-reload on file changes.
+    Only reloads the user module, not the entire server/sockets.
+
+    Args:
+        file_path: Path to the Python script to watch
+        server_name: Name of the server variable (or None for default)
+        xll_name: XLL name for metadata path (or None for default)
+    """
+    from xllify import XllifyRPCServer, get_server
+    import threading
+
+    script_path = Path(file_path)
+    last_mtime = script_path.stat().st_mtime
+
+    from xllify import __version__
+
+    print(
+        r"""
+     _ _ _  __
+ __ | | (_)/ _|_   _
+ \ \/ / | | |_| | | |
+  >  <| | |  _| |_| |
+ /_/\_\_|_|_|  \__, |
+               |___/
+    """
+    )
+    print(f"  v{__version__}\n")
+
+    logger.info(f"Auto-reload enabled. Watching: {file_path}")
+    logger.info("Press Ctrl+C to stop.")
+
+    def load_and_setup_server():
+        """Load/reload the user module and setup the server"""
+        if "xllify_user_module" in sys.modules:
+            del sys.modules["xllify_user_module"]
+
+        import xllify
+
+        xllify._default_server = None
+
+        # Load the module
+        try:
+            module = load_module_from_file(file_path)
+        except Exception as e:
+            logger.error(f"Error loading module: {e}")
+            return None
+
+        server = None
+        if server_name:
+            if not hasattr(module, server_name):
+                logger.error(f"Module does not have attribute '{server_name}'")
+                return None
+
+            server = getattr(module, server_name)
+            if not isinstance(server, XllifyRPCServer):
+                logger.error(f"'{server_name}' is not an XllifyRPCServer instance")
+                return None
+        else:
+            if hasattr(module, "server") and isinstance(module.server, XllifyRPCServer):
+                server = module.server
+            else:
+                server = get_server()
+
+        # Override xll_name based on arguments
+        if xll_name:
+            server.xll_name = xll_name
+
+        if not server.functions:
+            logger.warning("No functions registered. Use @xllify.fn() decorator.")
+            return None
+
+        return server
+
+    # Initial load
+    server = load_and_setup_server()
+    if server is None:
+        logger.error("Failed to start server.")
+        sys.exit(1)
+
+    logger.info(f"xllify external function RPC server from: {file_path}")
+
+    server.running = True
+    watcher_active = True
+
+    # Start file watcher thread
+    def watch_file():
+        nonlocal last_mtime
+        logger.info(f"File watcher active. Monitoring: {file_path}")
+        while watcher_active and server.running:
+            time.sleep(1)
+            try:
+                current_mtime = script_path.stat().st_mtime
+                if current_mtime != last_mtime:
+                    logger.info(f"RELOAD: Detected change in {file_path}")
+                    last_mtime = current_mtime
+
+                    # Reload the module
+                    new_server = load_and_setup_server()
+                    if new_server is not None:
+                        server.functions.clear()
+                        server.functions.update(new_server.functions)
+                        server._write_function_metadata()
+
+                        # Clear RTD cache to force Excel to refresh
+                        try:
+                            server.rtd_client.evict_all()
+                            logger.info("RELOAD: RTD cache cleared")
+                        except Exception as e:
+                            logger.warning(f"RELOAD: Failed to clear RTD cache: {e}")
+
+                        logger.info(f"RELOAD: Success! Functions: {list(server.functions.keys())}")
+                    else:
+                        logger.error("RELOAD: Failed! Keeping previous version.")
+
+            except FileNotFoundError:
+                logger.warning(f"File was deleted: {file_path}")
+            except Exception as e:
+                logger.error(f"Error watching file: {e}")
+                logger.debug("Traceback:", exc_info=True)
+
+    watcher_thread = threading.Thread(target=watch_file, daemon=True)
+    watcher_thread.start()
+
+    # Start the server (will block)
+    try:
+        server.start()
+    except KeyboardInterrupt:
+        logger.info("\nShutdown complete")
+        watcher_active = False
+        sys.exit(0)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Run xllify Python RPC server",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python -m xllify my_functions.py
+  python -m xllify my_functions.py --process-name myapp
+  python -m xllify my_functions:server
+  python -m xllify --clear-cache
+        """,
+    )
+
+    parser.add_argument(
+        "module",
+        nargs="?",
+        help="Python file to run (e.g., my_functions.py or my_functions:server)",
+    )
+
+    parser.add_argument(
+        "--clear-cache",
+        action="store_true",
+        help="Clear RTD cache (send EVICTALL command to default endpoint)",
+    )
+
+    parser.add_argument(
+        "--endpoint",
+        default=None,
+        help="Custom RTD endpoint for --clear-cache (default: tcp://127.0.0.1:55555)",
+    )
+
+    parser.add_argument(
+        "--reload",
+        action="store_true",
+        help="Enable auto-reload: restart server when script file changes",
+    )
+
+    parser.add_argument(
+        "--xll-name",
+        default="xllify_addin",
+        help="XLL name for metadata path (default: xllify_addin, creates AppData/Local/xllify/{xll-name}/xrpc/)",
+    )
+
+    args = parser.parse_args()
+
+    # Handle --clear-cache
+    if args.clear_cache:
+        from xllify import RTDClient
+
+        endpoint = args.endpoint if args.endpoint else "tcp://127.0.0.1:55555"
+        logger.info(f"Clearing RTD cache at {endpoint}...")
+        try:
+            client = RTDClient()
+            if client.evict_all():
+                logger.info("✓ Cache cleared successfully")
+                sys.exit(0)
+            else:
+                logger.error("✗ Failed to clear cache (RTD server may not be running)")
+                sys.exit(1)
+        except Exception as e:
+            logger.error(f"✗ Error: {e}")
+            sys.exit(1)
+
+    if not args.module:
+        logger.error("module argument is required")
+        parser.print_help()
+        sys.exit(1)
+
+    if ":" in args.module:
+        file_path, server_name = args.module.split(":", 1)
+    else:
+        file_path = args.module
+        server_name = None
+
+    if not Path(file_path).exists():
+        logger.error(f"File not found: {file_path}")
+        sys.exit(1)
+
+    if args.reload:
+        run_server_with_reload(file_path, server_name, args.xll_name)
+        return
+
+    
+    try:
+        module = load_module_from_file(file_path)
+    except Exception as e:
+        logger.error(f"Error loading modules: {e}")
+        sys.exit(1)
+
+    from xllify import XllifyRPCServer, get_server
+
+    server = None
+
+    if server_name:
+        if not hasattr(module, server_name):
+            logger.error(f"Module does not have attribute '{server_name}'")
+            sys.exit(1)
+
+        server = getattr(module, server_name)
+        if not isinstance(server, XllifyRPCServer):
+            logger.error(f"'{server_name}' is not an XllifyRPCServer instance")
+            sys.exit(1)
+    else:
+        # Check if module has a 'server' variable
+        if hasattr(module, "server") and isinstance(module.server, XllifyRPCServer):
+            server = module.server
+        else:
+            server = get_server()
+
+    # Override xll_name based on arguments
+    if args.xll_name:
+        server.xll_name = args.xll_name
+
+    if not server.functions:
+        logger.warning("No functions registered. Use @xllify.fn() decorator.")
+        logger.warning("Example:\n  @xllify.fn('MyFunc')\n  def my_func():\n      return 'Hello'")
+        sys.exit(1)
+
+    from xllify import __version__
+
+    print(
+        r"""
+     _ _ _  __
+ __ | | (_)/ _|_   _
+ \ \/ / | | |_| | | |
+  >  <| | |  _| |_| |
+ /_/\_\_|_|_|  \__, |
+               |___/
+    """
+    )
+    print(f"  v{__version__}\n")
+
+    logger.info(f"xllify external function RPC server from: {file_path}")
+    try:
+        server.start()
+    except KeyboardInterrupt:
+        logger.info("\nShutdown complete")
+        sys.exit(0)
+
+
+def clear_cache_main():
+    """Entry point for xllify-clear-cache command"""
+    from xllify import RTDClient
+
+    parser = argparse.ArgumentParser(
+        description="Clear xllify cache", formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+
+    parser.add_argument(
+        "--endpoint", default=None, help="Custom endpoint (default: tcp://127.0.0.1:55555)"
+    )
+
+    args = parser.parse_args()
+
+    endpoint = args.endpoint if args.endpoint else "tcp://127.0.0.1:55555"
+    logger.info(f"Clearing cache at {endpoint}...")
+
+    try:
+        client = RTDClient()
+        if client.evict_all():
+            logger.info("Cache cleared successfully")
+            sys.exit(0)
+        else:
+            logger.error("Failed to clear cache (server may not be running)")
+            sys.exit(1)
+    except Exception as e:
+        logger.error(f"Error: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

xllify/diagnostics.py

@@ -0,0 +1,78 @@
+"""
+Diagnostic tools for xllify RTD connection issues
+"""
+
+import socket
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def check_port_open(host: str, port: int, timeout: float = 1.0) -> bool:
+    """
+    Check if a TCP port is open and accepting connections
+
+    Args:
+        host: Hostname or IP address
+        port: Port number
+        timeout: Connection timeout in seconds
+
+    Returns:
+        True if port is open and accepting connections
+    """
+    try:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(timeout)
+        result = sock.connect_ex((host, port))
+        sock.close()
+        return result == 0
+    except Exception as e:
+        logger.debug(f"Port check failed for {host}:{port} - {e}")
+        return False
+
+
+def diagnose_rtd_connection():
+    """
+    Run diagnostics on RTD server connection
+    Checks if the ZeroMQ endpoints are available
+    """
+    print("=== xllify RTD Connection Diagnostics ===\n")
+
+    # Check ROUTER endpoint (tcp://127.0.0.1:55555)
+    router_host = "127.0.0.1"
+    router_port = 55555
+
+    print(f"Checking ROUTER endpoint: {router_host}:{router_port}")
+    if check_port_open(router_host, router_port):
+        print("  ✓ Port is OPEN - RTD server is likely running")
+    else:
+        print("  ✗ Port is CLOSED - RTD server may not be started")
+        print("\n  Possible causes:")
+        print("  1. Excel is not running")
+        print("  2. Excel RTD server (AsyncRTD.dll) is not loaded")
+        print("  3. Excel has not made any RTD calls yet (ServerStart not called)")
+        print("  4. Firewall is blocking the connection")
+        print("\n  To fix:")
+        print(
+            '  - Open Excel and create an RTD formula: =RTD("xllify.asyncrtd", "", "__XLLIFY_KEEPALIVE__")'
+        )
+        print("  - Make sure the xllify XLL add-in is loaded")
+
+    print()
+
+    # Check PUB endpoint (tcp://127.0.0.1:55556)
+    pub_host = "127.0.0.1"
+    pub_port = 55556
+
+    print(f"Checking PUB endpoint: {pub_host}:{pub_port}")
+    if check_port_open(pub_host, pub_port):
+        print("  ✓ Port is OPEN - RTD cache notifications available")
+    else:
+        print("  ✗ Port is CLOSED - Same issue as ROUTER endpoint")
+
+    print("\n=== End Diagnostics ===")
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    diagnose_rtd_connection()