xpycode-master 0.1.7
XPyCode Master - Python scripting for Excel with VBA-like interface
Requires Python: >=3.9
Keywords: excel, python, vba, automation, office

# XPyCode

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT + Commons Clause](https://img.shields.io/badge/License-MIT%20%2B%20Commons%20Clause-yellow.svg)](LICENSE)
[![Platform: Windows](https://img.shields.io/badge/platform-Windows-lightgrey.svg)]()
[![Platform: Linux/macOS (experimental)](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20(experimental)-orange.svg)]()

**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 an Alpha version, almost Beta. 

🚨 Don't use for production or in sensitive environement 🚨

## Help Keep the Project Alive

⭐ Add a star in [GitHub](https://xpycode.com/stars) to promote the project 

💵 [Donate](https://xpycode.com/donate) (for instance 3€ per month)

💬 Join the XPyCode Slack community to ask questions, share feedback, and connect with other users:
   👉 [Invite link](https://xpycode.com/slack_invite)
   👉 [Workspace](https://xpycode.com/slack)

## 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

```bash
pip install xpycode_master
```

### Quick Start

1. Install XPyCode:
   ```bash
   pip install xpycode_master
   ```

2. Start the XPyCode Master server:
   ```bash
   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:
   ```python
   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:

```bash
# 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](https://docs.xpycode.com/user-guide/service-management/) for details.

## Upgrading

Check for and install updates:

```bash
# 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.

```bash
python -m xpycode_master
```

### Local Mode

The add-in UI is served from a local HTTPS server on your machine. Requires self-signed certificates.

```bash
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

```python
# 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](https://xpycode.com/LICENSE) file for full details.

## Author

**BGE Advisory**

## Feedbacks

Contributions are welcome! Please feel free to submit issues.

## Support

- **Issues**: [GitHub Issues](https://xpycode.com/issues)
- **Documentation**: [Docs](https://docs.xpycode.com/)

## Acknowledgments

- [Monaco Editor](https://microsoft.github.io/monaco-editor/) - Code editor component
- [Office.js](https://docs.microsoft.com/en-us/office/dev/add-ins/) - Excel Add-in API
- [FastAPI](https://fastapi.tiangolo.com/) - Modern Python web framework
- [PySide6](https://doc.qt.io/qtforpython/) - Qt bindings for Python