Metadata-Version: 2.4
Name: xpycode_master
Version: 0.1.10
Summary: XPyCode Master - Python scripting for Excel with VBA-like interface
Author: XPyCode Team
License-Expression: MIT
Project-URL: Homepage, https://xpycode.com
Project-URL: Repository, https://xpycode.com/repo
Project-URL: Issues, https://xpycode.com/issues
Project-URL: Documentation, https://docs.xpycode.com
Keywords: excel,python,vba,automation,office
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Cython
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: websockets>=12.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: packaging>=21.0
Requires-Dist: python-lsp-server>=1.9.0
Requires-Dist: jedi>=0.18.0
Requires-Dist: pyflakes>=3.0.0
Requires-Dist: cryptography>=3.0
Requires-Dist: pip-system-certs
Requires-Dist: requests-ntlm
Requires-Dist: PySide6>=6.6.0
Requires-Dist: qasync>=0.27.0
Requires-Dist: keyring>=24.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: mkdocs>=1.5.3
Requires-Dist: mkdocs-material>=9.5.0
Requires-Dist: mkdocs-glightbox>=0.3.7
Requires-Dist: mkdocs-print-site-plugin>=2.3.0
Requires-Dist: pymdown-extensions>=10.7
Requires-Dist: orjson>=3.9.15
Requires-Dist: unearth>=0.14.0
Requires-Dist: pywin32>=305; sys_platform == "win32"
Provides-Extra: windows
Provides-Extra: polars
Requires-Dist: polars>=0.20.0; extra == "polars"
Dynamic: license-file

# 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
