Metadata-Version: 2.4
Name: vba_edit
Version: 0.5.1
Summary: Enable seamless MS Office VBA code editing in preferred editor or IDE (facilitating the use of coding assistants and version control workflows)
Author-email: Markus Killer <m.killer@langui.ch>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://langui.ch/current-projects/vba-edit/
Project-URL: Documentation, https://github.com/markuskiller/vba-edit/blob/main/README.md
Project-URL: Source, https://github.com/markuskiller/vba-edit
Project-URL: Changelog, https://github.com/markuskiller/vba-edit/blob/main/CHANGELOG.md
Keywords: vba,excel,word,office,automation,macro,PyPI
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Office/Business :: Office Suites
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSES/LICENSE-xlwings.txt
License-File: AUTHORS.md
License-File: SECURITY.md
Requires-Dist: pywin32>=224; platform_system == "Windows"
Requires-Dist: watchfiles>=1.1.1
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Requires-Dist: rich>=13.0.0
Requires-Dist: ttkbootstrap>=1.10.0
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0.0; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: pyinstaller; extra == "dev"
Requires-Dist: filelock>=3.20.1; extra == "dev"
Provides-Extra: all
Requires-Dist: xlwings>=0.28.0; extra == "all"
Dynamic: license-file

# [vba-edit](https://github.com/markuskiller/vba-edit) 

**Edit VBA code in VS Code, PyCharm, Wing IDE, or any editor you love.** Real-time sync with MS Office apps (support for **Excel**, **Word**, **PowerPoint** & **Access**). Git-friendly. No more VBA editor pain.

[![CI](https://github.com/markuskiller/vba-edit/actions/workflows/test.yaml/badge.svg)](https://github.com/markuskiller/vba-edit/actions/workflows/test.yaml)
[![PyPI - Version](https://img.shields.io/pypi/v/vba-edit.svg)](https://pypi.org/project/vba-edit)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/vba-edit.svg)](https://pypi.org/project/vba-edit)
[![Platform](https://img.shields.io/badge/platform-windows-blue.svg)](https://pypi.org/search/?q=vba-edit&o=&c=Operating+System+%3A%3A+Microsoft+%3A%3A+Windows)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/vba-edit)](https://www.pypiplus.com/project/vba-edit/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)

## Installation

### RECOMMENDED: Via [``uvx``](https://docs.astral.sh/uv/guides/tools/) (No Install Required)
```bash
uvx excel-vba edit -f myfile.xlsm
uvx word-vba edit -f myfile.docm
uvx powerpoint-vba edit -f myfile.pptm
uvx access-vba edit -f myfile.accdb
```

> **Note:** The ``uvx`` command runs the tool without installing it permanently — same as: ``uv tool run excel-vba``

### Python Package
```bash
pip install -U vba-edit
```

### Windows Binaries (No Python Required)

Standalone executables available - no Python installation needed!

📦 **Download**: [Latest Release](https://github.com/markuskiller/vba-edit/releases/latest) (scroll all the way down to **Assets** section)

Available binaries:
- `excel-vba.exe` - For Excel workbooks (.xlsm, .xlsb, .xls)
- `word-vba.exe` - For Word documents (.docm)
- `access-vba.exe` - For Access databases (.accdb, .mdb)
- `powerpoint-vba.exe` - For PowerPoint presentations (.pptm)

🔒 **Security**: See [Security Verification Guide](SECURITY_VERIFICATION.md) for SHA256 checksums and attestation validation.

> ⚠️ **Windows SmartScreen & VirusTotal Warnings**: Binaries are currently unsigned. You may see warning messages - this is expected. See [Issue #24](https://github.com/markuskiller/vba-edit/issues/24) and [Security Info](SECURITY.md) for details.

## 30-Second Demo
```bash
# Start editing (uses active Excel/Word document) — no install required!
uvx excel-vba edit    # or: uvx word-vba edit

# Prefer a config file? Open the GUI generator first.
uvx excel-vba config-gen

# That's it! Edit the .bas/.cls files in your editor. Save = Sync.
```

## How It Works
<pre>
                        <--- vba-edit --->

Excel / Word                 COMMANDS              Your favourite
PowerPoint / Access             v                       Editor

+------------------+                            +------------------+
|                  |                            |                  |
|   VBA Project    |   <---   EDIT*   (once ->) |  (e.g. VS CODE)  | 
|                  |                            |                  |     latest
|  (Office VBA-    |          EXPORT      --->  |   .bas           |  <- AI coding-  
|    Editor)       |                            |   .cls           |     assistants
|                  |   <---   IMPORT            |   .frm           |   
|                  |                            |  (.frx binary)   | 
|                  |                            |                  |     optional
|                  |                            |  [.toml]         |  <- support for 
|                  |                            |                  |     references
+------------------+                            +------------------+
                                                         v
                                                +------------------+
                                                |                  |
 * watches & syncs                              |    (e.g. Git)    |
   back to Office                               |  version control |
   VBA-Editor live                              |                  |
   on save [CTRL+S]                             |                  |
                                                +------------------+
</pre>

## Why vba-edit?

- **Use YOUR editor** - VS Code, PyCharm, Wing IDE, Sublime, Vim, etc. whatever you love 
- **AI-ready** - Use Copilot, ChatGPT, or any coding assistant 
- **Team-friendly** - Share code via Git, no COM add-ins needed 
- **Real version control** - Diff, merge, and track changes properly 
- **Well-organized** - Keep your VBA structured, clean, and consistent

## Setup (One-Time)

**Windows Only** | **MS Office**

Enable VBA access in Office:

`File → Options → Trust Center → Trust Center Settings → Macro Settings`

✅ **Trust access to the VBA project object model**

> 💡 Can't find it? Run `uvx excel-vba check` (or `excel-vba check` if installed) to verify settings

### VS Code Settings (Recommended)

To ensure VS Code handles VBA file encoding correctly, add the following to your user settings (`%APPDATA%\Code\User\settings.json`):

```json
"[vba]": {
    "files.encoding": "windows1252"
},
"files.associations": {
    "*.bas": "vba",
    "*.cls": "vba",
    "*.frm": "vba"
}
```

> 💡 **Using VS Code Profiles?** Add these settings to each profile's `settings.json` as well.  
> Change `"windows1252"` to match the `--encoding` value you pass to vba-edit if you use a different code page.


## Common Workflows

> All workflows below work with both `excel-vba <command>` (installed) and `uvx excel-vba <command>` (no install required).

### Start Fresh
```bash
uvx excel-vba edit                # Start with active workbook — no install required!
excel-vba edit                    # If already installed
```

### Create a Config File
```bash
uvx excel-vba config-gen          # Open the config generator GUI
excel-vba export --conf vba-config.toml
```

### Quick Export with Folder View
```bash
excel-vba export --open-folder    # Export and open in File Explorer
excel-vba export --keep-open      # Export but keep document open for inspection
excel-vba export --no-color       # Export without colorized output
```

### Team Project with Git
```bash
excel-vba export --vba-directory ./src/vba
git add . && git commit -m "Updated reports module"
``` 

### Support for RubberduckVBA Style (big thank you to @onderhold!)
```bash
excel-vba edit --rubberduck-folders --in-file-headers
``` 

## Quick Reference

### App-specific tools

| CLI Tool | Description |
|---------|-------------|
| `excel-vba` | For Excel Workbooks (.xlsm, .xlsb, .xls) |
| `word-vba` | For Word documents (.docm) |
| `access-vba` | For Access databases (.accdb, .mdb) |
| `powerpoint-vba` | For PowerPoint presentations (.pptm) |

> 💡 Use with `uvx excel-vba <command>` (no install) or `excel-vba <command>` (if installed). Standalone `.exe` binaries also available — see [Latest Release](https://github.com/markuskiller/vba-edit/releases/latest).

> 💡 **Note**: Additional macro-enabled formats (.xltm, .dotm, .potm) are likely supported but not yet tested in this release.

### Commands

| Command overview | Description |
|---------|-------------|
| `edit` | Edit VBA content in Office document |
| `import` | Import VBA content into Office document |
| `export` | Export VBA content from Office document |
| `check` | Check if 'Trust Access to the Office VBA project object model' is enabled |
| `config-gen` | Open a GUI to create or edit TOML configuration files |
| `references` | Manage VBA library references (list / export / import / validate / add / remove) |

> 💡 Use **`uvx excel-vba <command> --help`** (or `excel-vba <command> --help` if installed) for a detailed option overview.

### Examples of options

> All examples below work with both `excel-vba <command>` (installed) and `uvx excel-vba <command>` (no install required).

| Command | What it does |
|---------|-------------|
| `excel-vba edit` | Start live editing |
| `excel-vba export` | One-time export |
| `excel-vba import` | One-time import |
| `excel-vba config-gen` | Open the config generator GUI |
| `excel-vba export --open-folder --keep-open` | Export and open folder in explorer, keep document open for inspection |
| `excel-vba export --force-overwrite` | Export without confirmation prompts |
| `excel-vba check` | Verify status of *Trust access* to the VBA project object model |
| `excel-vba references list` | List all VBA library references in the active workbook |
| `excel-vba references list --no-default` | List only installed and custom references |
| `excel-vba references export` | Export references to a TOML file for sharing or version control |
| `excel-vba references import -r refs.toml` | Restore references from a TOML file |
| `excel-vba references import -r refs.toml --sync` | Make document match the TOML file exactly (add missing, remove extra) |
| `excel-vba references validate` | Check for broken or missing references |
| `excel-vba references add lib.xlam` | Add a reference by file path |
| `excel-vba references remove MyLib` | Remove a reference by name |
| `excel-vba export --with-references` | Export VBA code and references together |

> 💡 **Complete Option Matrix**: available **[here](https://langui.ch/current-projects/vba-edit/#OptionMatrix)**

## VBA Reference Manager

Manage VBA library references (e.g. Microsoft Scripting Runtime, ActiveX Data Objects) directly from the command line:

```bash
# List all references in the active workbook
excel-vba references list

# List only installed and custom references (hide defaults)
excel-vba references list --no-default

# Export references to a TOML file (default: {document}_refs.toml)
excel-vba references export
excel-vba references export -r shared_refs.toml

# Import references from a TOML file
excel-vba references import -r shared_refs.toml
excel-vba references import -f myfile.xlsm -r shared_refs.toml

# Sync references — make document match the TOML file exactly
# Adds missing and removes extra references (default refs protected)
excel-vba references import -r shared_refs.toml --sync

# Validate references — check for broken or missing ones
excel-vba references validate

# Add or remove individual references
excel-vba references add path/to/library.xlam
excel-vba references remove "My Custom Library"
```

### Automatic reference sync

Use `--with-references` to include references alongside code during export, import, or edit:

```bash
# Export VBA code AND references together
excel-vba export --with-references

# Import code AND restore references in one step
excel-vba import --with-references

# Live edit with automatic reference sync on save
excel-vba edit --with-references
```

### Reference classification & filtering

References are classified into three categories for easy filtering:

| Category | Description | Example |
|----------|-------------|----------|
| `default` | Always present in new documents | VBA, Excel, stdole, Office, Normal |
| `installed` | Registered COM libraries on the system | Scripting Runtime, Adobe Acrobat |
| `custom` | File-path references (no GUID) | Your `.docm`/`.dotm` templates |

Filter flags can be combined: `--no-default`, `--no-installed`, `--no-custom`

**Use cases:**
- Track reference dependencies alongside VBA code in version control
- Replicate the same reference setup across multiple documents
- Onboard team members — just run `references import` to get the right libraries
- Detect broken references before they cause runtime errors

**TOML format** (exportable and hand-editable):
```toml
# GUID-based reference (installed COM library)
[[references]]
name = "Scripting"
guid = "{420B2830-E718-11CF-893D-00A0C9054228}"
major = 1
minor = 0
description = "Microsoft Scripting Runtime"

# Path-based reference (custom template / add-in)
[[references]]
name = "SharedMacros"
path = "\\\\server\\share\\templates\\SharedMacros.dotm"
major = 0
minor = 0
```

> Works with all four Office apps: `excel-vba`, `word-vba`, `powerpoint-vba`, `access-vba`

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Trust access" error | Run `uvx excel-vba check` (or `excel-vba check`) for diagnostics |
| Changes not syncing | Save the file in your editor |
| Forms not working | Add `--in-file-headers` flag |


## Safety Features

**🛡️ Data Loss Prevention**

vba-edit now protects your work with smart safety checks:

- **Overwrite Protection**: Warns before overwriting existing VBA files
- **Header Mode Detection**: Alerts when switching between header storage modes
- **Orphaned File Cleanup**: Automatically removes stale `.header` files on mode change
- **UserForm Validation**: Prevents exports without proper header handling

**Bypass for Automation**: Use `--force-overwrite` flag to skip prompts in CI/CD pipelines:
```bash
excel-vba export --vba-directory ./src --force-overwrite
```

> ⚠️ **CAUTION**: `--force-overwrite` suppresses all safety prompts. Use with caution!


## Features

**🚀 Core**
- Live sync between Office and your editor
- Full Git/version control support
- All Office apps: Excel, Word, Access & PowerPoint

**📁 Organization** 
- RubberduckVBA folder structure support
- Smart file organization with `@Folder` annotations
- TOML config files for team standards

**📚 Reference Management**
- List, export, import, validate, add, and remove VBA library references
- Classify references as default, installed, or custom with composable filters
- Automatic reference sync alongside code with `--with-references`
- Share reference setups via version-controlled TOML files

**🔧 Advanced**
- Unicode & encoding support
- UserForms with layout preservation  
- Class modules with custom attributes


## Roadmap

Development priorities evolve based on user feedback and real-world needs. 

👀 **See active planning**: [GitHub Milestones](https://github.com/markuskiller/vba-edit/milestones)  
💡 **Request features**: [Open an Issue](https://github.com/markuskiller/vba-edit/issues)  
📝 **Current focus**: Stability, documentation, and exploring PowerQuery support


### 💡 Feedback & Contributions

Found a bug? Have a feature idea? Questions about usage? Open an [Issue](https://github.com/markuskiller/vba-edit/issues) - we use labels to organize different types of feedback.

---

## Command Line Tools

> 💡 **Complete CLI Overview**: available **[here](https://langui.ch/current-projects/vba-edit/#CLI)**

### Example of `--in-file-headers --rubberduck-folders`

```vba
VERSION 1.0 CLASS
BEGIN
  MultiUse = -1  'True
END
Attribute VB_Name = "MyClass"
Attribute VB_GlobalNameSpace = False
Attribute VB_Creatable = False
Attribute VB_PredeclaredId = False
Attribute VB_Exposed = False

'@Folder("Business.Domain")
Public Sub DoSomething()
    ' Your code here
End Sub
```

## Colorized Output

Terminal output features color-coded messages terms for better readability:

- ✓ **Success** messages in green
- ✗ **Error** messages in red
- ⚠ **Warning** messages in yellow
- **Technical terms** (VBA, TOML, JSON) highlighted in cyan
- **Code examples** shown in dim gray

**Automatic Behavior:**
- Colors automatically disabled when output is piped or redirected
- Disabled in non-TTY environments (CI/CD pipelines)
- Respects `NO_COLOR` environment variable

**Manual Control:**
```powershell
excel-vba export --no-color              # Disable colors
$env:NO_COLOR=1; excel-vba export        # Via environment variable (PowerShell)
```

> 💡 **Tip**: Use `--no-color` when terminal colors cause issues.

## Configuration Files

Use TOML configuration files to standardize team workflows and avoid repetitive command-line arguments.

You can create them with the built-in GUI instead of writing TOML by hand:

```bash
excel-vba config-gen
word-vba config-gen
powerpoint-vba config-gen
access-vba config-gen
```

The generator provides app-specific file pickers, live TOML preview, and open/save controls for existing or new config files. It is included in the standard install; no extra package is required.

### Basic Configuration

Create a `vba-config.toml` file in your project:

```toml
[general]
file = "MyWorkbook.xlsm"
vba_directory = "src/vba"
verbose = true
rubberduck_folders = true
in_file_headers = true
```

Then use it:
```bash
excel-vba export --conf vba-config.toml
```

The same file can be reused with `edit`, `import`, `export`, and `references` commands whenever the settings apply.

### Available Configuration Keys

**[general] section:**
- `file` - Path to Office document
- `vba_directory` - Directory for VBA files
- `encoding` - Character encoding (e.g., "utf-8", "cp1252")
- `detect_encoding` - Auto-detect file encoding (true/false)
- `verbose` - Enable verbose logging (true/false)
- `logfile` - Path to log file
- `rubberduck_folders` - Use RubberduckVBA @Folder annotations (true/false)
- `save_headers` - Save headers to separate .header files (true/false)
- `in_file_headers` - Embed headers in code files (true/false)
- `save_metadata` - Save module metadata for reliable reimport (true/false)
- `open_folder` - Open export directory after export (true/false)
- `keep_open` - Keep document open after export (true/false)
- `skip_empty` - Skip modules with no meaningful code (true/false)
- `force_overwrite` - Overwrite existing files without prompting (true/false)
- `with_references` - Include VBA references in export/import (true/false)
- `no_color` - Disable colorized terminal output (true/false)

**[references] section:**
- `refs_file` - Path to VBA references file (default: `vba-references.toml`)
- `no_default` - Exclude default references from listing (true/false)
- `no_installed` - Exclude installed COM library references from listing (true/false)
- `no_custom` - Exclude custom file-path references from listing (true/false)

**Other sections (reserved for future use):**
- `[office]` - Office-wide settings
- `[excel]` - Excel-specific settings
- `[word]` - Word-specific settings
- `[access]` - Access-specific settings
- `[powerpoint]` - PowerPoint-specific settings

### Configuration Placeholders

Configuration values support dynamic placeholders for flexible path management.

**Available placeholders**
- `{config.path}` - Directory containing the config file
- `{file.name}` - Document filename without extension
- `{file.fullname}` - Document filename with extension
- `{file.path}` - Directory containing the document
- `{file.vbaproject}` - VBA project name (resolved at runtime)

**Example with placeholders:**

```toml
[general]
file = "C:/Projects/MyApp/MyWorkbook.xlsm"
vba_directory = "{file.path}/{file.name}-vba"
# This resolves to: C:/Projects/MyApp/MyWorkbook-vba
```

**Relative paths example:**

```toml
[general]
file = "../documents/report.xlsm"
vba_directory = "{config.path}/vba-modules"
# vba_directory is relative to config file location
```

### Command-Line Override

Command-line arguments always override config file settings, including boolean flags:

```bash
# Config says vba_directory = "src/vba"
# This overrides it to "build/vba"
excel-vba export --conf vba-config.toml --vba-directory build/vba

# Config says in_file_headers = true
# This overrides it to save-headers mode
excel-vba export --conf vba-config.toml --save-headers
```

> ⚠️ **CAUTION**: **1.** Always **backup your Office files** before using `vba-edit` **2.** Use **version control (git)** to track your VBA code **3.** Run `export` after changing **form layouts** or module properties


### Known Limitations

- UserForms require `--save-headers` or newer `--in-file-headers` option (`edit` process is aborted if this is not the case)
- If separate `*.header` files are modified on their own, the corresponding `*.cls`, `*.bas` or `*.frm` file needs to be saved in order to sync the complete module back into the VBA project model

## Links

- [Homepage](https://langui.ch/current-projects/vba-edit/)
- [Documentation](https://github.com/markuskiller/vba-edit/blob/main/README.md)
- [Source Code](https://github.com/markuskiller/vba-edit)
- [Changelog](https://github.com/markuskiller/vba-edit/blob/main/CHANGELOG.md)
- [Changelog of latest dev version](https://github.com/markuskiller/vba-edit/blob/dev/CHANGELOG.md)
- [Video Tutorial](https://www.youtube.com/watch?v=xoO-Fx0fTpM) (xlwings walkthrough — covers basic edit/export/import concepts; vba-edit has many additional features)

## License

BSD 3-Clause License

## Credits

**vba-edit** builds on an excellent idea first implemented for Excel in [xlwings](https://www.xlwings.org/) (BSD-3).

Special thanks to **@onderhold** for many valuable contributions since v0.4.0.
