xpycode-master 0.2.0

XPyCode Master - Python scripting for Excel with VBA-like interface

XPyCode

XPyCode is an Excel-Python integration platform that enables you to write, execute, and manage Python code directly within Microsoft Excel workbooks. It provides a seamless bridge between Excel and Python, featuring a full-featured IDE, custom function publishing, package management, and real-time debugging.

Project status

⚠️ This version is at early stage. It is a Beta version.

🚨 Don't use for production or in sensitive environement 🚨

Help Keep the Project Alive

⭐ Add a star in GitHub to promote the project

💵 Donate (for instance 3€ per month)

💬 Join the XPyCode Slack community to ask questions, share feedback, and connect with other users: 👉 Invite link 👉 Workspace

Features

• 🐍 Python Execution in Excel - Run Python code with full access to Excel objects
• 📝 Integrated IDE - Monaco-based code editor with IntelliSense, syntax highlighting, and debugging
• 📦 Package Manager - Install and manage Python packages per workbook with dependency resolution
• 🔧 Custom Functions (UDFs) - Publish Python functions as Excel formulas
• 🎯 Event Handling - React to Excel events (worksheet changes, selections, etc.) with Python
• 🔍 Object Management - Save and re-use objects in python kernel
• 🐛 Debugger - Set breakpoints, step through code, and inspect variables
• 🎨 Theming - Customizable dark/light themes for the IDE

Requirements

• Operating System: Windows 10/11 (64-bit) / Other platforms are enabled but not tested
• Python: 3.9 or higher
• Microsoft Excel: 2016 or later (with Office.js Add-in support)

Installation

pip install xpycode_master

Quick Start

1. Install XPyCode:

   pip install xpycode_master
   

2. Start the XPyCode Master server:

   python -m xpycode_master
   

3. The Excel Add-in will be automatically registered.

   Open Excel and look for the XPyCode in Add-Ins -> More Add-Ins -> Shared Folder

4. Launch in Excel:

   [Open Console] --> [<> Editor ]
   

5. In XPyCode Editor

   • Add a python module: Right click on the workbook -> New Module
   • Start coding, using xpycode module:

   def updateExcelFromPython():
      import xpycode
      ws=xpycode.worksheets.getActiveWorksheet()
      rA1=ws.getRange("A1")
      rA1.values="Hello"
      rA1.format.fill.color="yellow"
   

Running as a Service

XPyCode can run as a system service for automatic startup:

# Install and start as a service
python -m xpycode_master service install

# Check status
python -m xpycode_master service status

# Stop service
python -m xpycode_master service stop

Supported on Windows, Linux (systemd), and macOS (launchd). See Service Management for details.

Upgrading

Check for and install updates:

# Check if an update is available
python -m xpycode_master --upgrade --check

# Upgrade interactively
python -m xpycode_master --upgrade

# Upgrade without confirmation
python -m xpycode_master --upgrade --yes

If XPyCode is running as a service, the upgrade process will automatically stop and restart the service.

Addin Hosting Modes

XPyCode supports two modes for running the Excel add-in:

External Mode (Default)

The add-in UI is served from https://addin.xpycode.com. This is the default mode and requires no certificate management.

python -m xpycode_master

Local Mode

The add-in UI is served from a local HTTPS server on your machine. Requires self-signed certificates.

python -m xpycode_master --use-local-addin

!!! warning "Mode Switch Cache Clearing" When switching between local and external modes, XPyCode will automatically clear the Office add-in cache. This affects all Office add-ins, not just XPyCode. You may need to restart Excel after switching modes.

Usage

Running Python Code

1. Open a workbook in Excel
2. Click "Open Console" in the XPyCode ribbon
3. Open Editor with "<>" button
4. Right click on the workbook name and add a python module
5. Write Python code in the editor
6. Press F5 or click "Run" to execute

Publishing Custom Functions

# In your module, define a function
def add_numbers(a: float, b: float) -> float:
    """Add two numbers together."""
    return a + b

Then use the Function Publisher in the IDE to expose it as an Excel formula: =ADD_NUMBERS(A1, B1)

Package Management

1. Open the Package Manager panel in the IDE
2. Search for a package (e.g., "pandas")
3. Select version and optional extras
4. Click "Install/Update" to install for the current workbook

Configuration

Configure themes, pypi urls, console preferences, ... in File/Settings menu

Excel Sample

You will find an Excel workbook sample in xpycode_master\excel_sample.

Dependencies

Core Dependencies

• fastapi >= 0.100.0 - Web framework for the Business Layer API
• uvicorn >= 0.22.0 - ASGI server for FastAPI
• websockets >= 12.0 - WebSocket client/server implementation
• aiohttp >= 3.8.0 - Async HTTP client for package index queries
• packaging >= 21.0 - Version parsing and specifier handling
• PySide6 >= 6.5.0 - Qt bindings for the IDE GUI (includes WebEngine for Monaco Editor embedding)
• jedi >= 0.19.0 - Python autocompletion and static analysis
• orjson >= 3.9.15 - Fast JSON serialization (recommended)
• keyring >= 24.0.0 - Secure credential storage for AI providers
• unearth >= 0.14.0 - Enhanced package discovery

Architecture

XPyCode consists of several interconnected components:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Excel Add-in  │◄───►│  Business Layer │◄───►│   Python IDE    │
│   (Office.js)   │     │    (FastAPI)    │     │   (PySide6)     │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │  Python Kernel  │
                        │  (per workbook) │
                        └─────────────────┘

• Excel Add-in: Office.js-based add-in providing the Excel interface
• Business Layer: FastAPI server acting as message broker between components
• Python Kernel: Per-workbook Python execution environment
• Python IDE: PySide6-based development environment with Monaco Editor

License

This project is licensed under the MIT License with Commons Clause.

You are free to use, modify, and distribute this software for any purpose. However, you may not sell the software or include it as a substantial part of a commercial product or service.

See the LICENSE file for full details.

Author

BGE Advisory

Feedbacks

Contributions are welcome! Please feel free to submit issues.

Support

• Issues: GitHub Issues
• Documentation: Docs

Acknowledgments

• Monaco Editor - Code editor component
• Office.js - Excel Add-in API
• FastAPI - Modern Python web framework
• PySide6 - Qt bindings for Python