Metadata-Version: 2.4
Name: visiowings
Version: 1.0.2
Summary: VBA Editor for Microsoft Visio with VS Code integration
Author: twobeass
License-Expression: MIT
Project-URL: Homepage, https://github.com/twobeass/visiowings
Project-URL: Repository, https://github.com/twobeass/visiowings
Project-URL: Issues, https://github.com/twobeass/visiowings/issues
Project-URL: Changelog, https://github.com/twobeass/visiowings/blob/main/CHANGELOG.md
Project-URL: Documentation, https://twobeass.github.io/visiowings/
Keywords: visio,vba,editor,vscode,automation
Classifier: Development Status :: 5 - Production/Stable
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: Operating System :: Microsoft :: Windows
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pywin32>=305; sys_platform == "win32"
Requires-Dist: watchdog>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: hypothesis>=6.100; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: types-pywin32>=306.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Requires-Dist: mkdocs-gen-files>=0.5; extra == "docs"
Requires-Dist: mkdocs-literate-nav>=0.6; extra == "docs"
Requires-Dist: mkdocs-section-index>=0.3; extra == "docs"
Provides-Extra: uat
Requires-Dist: pytest>=7.4; extra == "uat"
Requires-Dist: pytest-timeout>=2.2; extra == "uat"
Requires-Dist: pytest-rerunfailures>=14; extra == "uat"
Requires-Dist: psutil>=5.9; extra == "uat"
Requires-Dist: pywin32>=306; sys_platform == "win32" and extra == "uat"
Dynamic: license-file

# visiowings

VBA Editor for Microsoft Visio with VS Code integration – Edit Visio VBA modules in your favorite editor with live sync, Git support, and modern tooling. Inspired by xlwings.

[![CI](https://github.com/twobeass/visiowings/actions/workflows/ci.yml/badge.svg)](https://github.com/twobeass/visiowings/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/visiowings.svg)](https://pypi.org/project/visiowings/)
[![Python](https://img.shields.io/pypi/pyversions/visiowings.svg)](https://pypi.org/project/visiowings/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/twobeass/visiowings/badge)](https://securityscorecards.dev/viewer/?uri=github.com/twobeass/visiowings)
[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blue)](https://twobeass.github.io/visiowings/)

---

## Table of Contents
- [Features](#features)
- [Why visiowings?](#why-visiowings)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage & Commands](#usage--commands)
- [Advanced Features](#advanced-features)
- [Integration](#integration)
- [Reference](#reference)
- [Troubleshooting](#troubleshooting)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License & Acknowledgments](#license--acknowledgments)

---

## Features
- **Live sync:** Edit in VS Code, changes update Visio instantly
- **Bidirectional sync:** (optional) Changes in Visio update VS Code
- **Multi-document support:** Sync several open files at once
- **Git version control:** See live diffs in VS Code
- **Automatic change detection:** Smart, hash-based, and loop-proof
- **Module deletion sync:** Remove modules in Visio when deleted in VS Code
- **Modern VS Code features:** Line numbers, dark mode, search, shortcuts
- **Safe import/export:** Robust comparison and header management prevents unwanted overwrites and import failures

## Why visiowings?
Visio VBA Editor lacks modern tooling. visiowings brings:
- Full-featured editor experience
- Fast, bidirectional sync
- Real Git integration
- No more manual copy-paste or limited VBA interface
- Safe cross-platform editing and importing of modules

---

## Installation
### Prerequisites
- Windows (required for COM automation)
- Python 3.10+
- Microsoft Visio (with VBA support)

### Install with pipx (recommended)
[`pipx`](https://pipx.pypa.io/) installs visiowings into an isolated
environment and puts the `visiowings` command on your PATH:

```bash
pipx install visiowings
```

To upgrade later: `pipx upgrade visiowings`.

### Install with pip
```bash
pip install visiowings
```

### Standalone Windows EXE (no Python required)
Download `visiowings.exe` from the
[latest GitHub Release](https://github.com/twobeass/visiowings/releases/latest)
and place it somewhere on your PATH.

### Install from source
```bash
git clone https://github.com/twobeass/visiowings.git
cd visiowings
pip install -e ".[dev]"
pre-commit install
```

---

## Quick Start
### Single Document
1. Enable VBA access in Visio: Options → Trust Center → Macro Settings → ☑ "Trust access to the VBA project object model"
2. Open your Visio file (e.g. `yourdoc.vsdm`)
3. Start editing:
   ```bash
   visiowings edit --file yourdoc.vsdm --bidirectional
   ```
4. Edit `.bas`, `.cls`, `.frm` files in VS Code, save to sync

### Multiple Documents
1. Open all relevant Visio documents (drawings, stencils, templates)
2. Run:
   ```bash
   visiowings edit --file your_main_document.vsdx --bidirectional --force
   ```
3. Edit VBA files in VS Code; changes sync to matching Visio file

---

## Usage & Commands

### Edit Mode
```bash
# VS Code → Visio only
visiowings edit --file yourdoc.vsdm

# Bidirectional sync
visiowings edit --file yourdoc.vsdm --bidirectional

# Overwrite document modules
visiowings edit --file yourdoc.vsdm --force

# Enable module deletion & debug mode
visiowings edit --file yourdoc.vsdm --sync-delete-modules --debug

# Custom output directory
visiowings edit --file yourdoc.vsdm --output ./vba_modules

# Enable Rubberduck folder structure integration
visiowings edit --file yourdoc.vsdm --rubberduck
```

### Export & Import
```bash
# Export VBA modules (one-time)
visiowings export --file yourdoc.vsdm --output ./vba_modules --rd

# Force export of .frx files
visiowings export --file yourdoc.vsdm --export-frx

# Import VBA modules
visiowings import --file yourdoc.vsdm --input ./vba_modules --force --rd
```

### Rubberduck Integration (New!)
Use Rubberduck-compatible folder annotations (`@Folder("Folder.Sub")`) to organize your VBA project structure automatically.

- **Export:** Reads `@Folder` annotations from VBA modules and exports files into the corresponding directory structure.
- **Import:** Detects file location in the directory structure and automatically injects or updates `@Folder` annotations in the imported code.
- **Sync:** Works seamlessly with `edit` mode to maintain structure while you work.

### Safe Export & Import (NEW)
- **Export:** Uses normalization and header-stripping to prevent accidental differences and overwriting. On conflict, user is prompted to overwrite, skip, or choose interactively.
- **Import:** Before importing, headers are repaired and encoding normalized. Comments and Option Explicit are preserved. Document modules are handled safely (force option required).

### Command Reference
| Option                 | Description                                                              |
|------------------------|--------------------------------------------------------------------------|
| `--file`, `-f`         | Visio file path (`.vsdm`, `.vsdx`, `.vssm`, `.vssx`, `.vstm`, `.vstx`)    |
| `--output`, `-o`       | Export directory (default: current directory)                            |
| `--input`, `-i`        | Import directory (for import command)                                    |
| `--force`              | Overwrite Document modules (ThisDocument.cls) AND auto-resolve all conflict prompts as "overwrite" |
| `--non-interactive`, `-y` | Never prompt on stdin; skip conflicts (or overwrite if combined with `--force`) — for CI |
| `--ephemeral`          | (`import` only) Clear the document's dirty flag after import so closing Visio does *not* write back to .vsdm |
| `--bidirectional`      | Enable bidirectional sync (Visio ↔ VS Code)                              |
| `--sync-delete-modules`| Automatically delete Visio modules when matching files are deleted        |
| `--rubberduck`, `--rd` | Enable Rubberduck @Folder annotation support for directory structure      |
| `--export-frx`         | Force export of .frx files even if .frm code has not changed              |
| `--debug`              | Verbose debug logging                                                    |

---

## Advanced Features
- **Multi-document support:** Each Visio file with VBA is exported/imported to a dedicated folder
- **Rubberduck Integration:** Map `@Folder("Parent.Child")` annotations to real directory structures automatically
- **Module deletion sync:** When enabled, `.bas`, `.cls`, `.frm` deletes in VS Code remove corresponding modules in Visio
- **Smart change detection:** Only syncs when content changes; polling interval is optimized
- **Intelligent Form Export:** .frx files are now only exported if the corresponding .frm code changes to prevent Git churn. Use `--export-frx` to force export.
- **Bidirectional sync:** Changes in VS Code or Visio keep both in sync with the selected polling interval (default: 4 seconds)
- **NEW: Safe Import/Export:** Content checks, normalization, encoding handling, and interactive user options ensure maximum safety

---

## Integration
### VS Code Setup

For your *user* VBA workspace, associate `.bas`, `.cls`, `.frm`:

```json
{
  "files.associations": {
    "*.bas": "vba",
    "*.cls": "vba",
    "*.frm": "vba"
  },
  "editor.tabSize": 4,
  "editor.insertSpaces": true
}
```

Recommended extensions: VBA syntax highlighting (`@ext:vba`), GitLens.

> If you're hacking on visiowings itself, the repo already ships
> `.vscode/settings.json` and `.vscode/extensions.json` with Ruff,
> mypy, and pytest pre-wired. See
> [Development environment](https://twobeass.github.io/visiowings/contributing/development-environment/).

### Git Integration
- Initialize git:
  ```bash
  git init
  git add *.bas *.cls
  git commit -m "Initial VBA modules"
  ```
- Use VS Code’s Git tools for diffs and versioning

---

## Reference
### Supported File Types
- `.bas` - Standard VBA modules
- `.cls` - Class modules (incl. Document modules)
- `.frm` - User forms

### Example Project Structure
```text
my_project/
├── drawing.vsdx
├── mystencil.vssm
└── vba_modules/
    ├── drawing/
    │   └── Module1.bas
    └── mystencil/
        ├── ThisDocument.cls
        └── StencilHelpers.bas
```

---

## Troubleshooting

### Trust Center
Visio → Options → Trust Center → Macro Settings → ☑ "Trust access to the VBA project object model"

### Visio document not open
- Always open the document in Visio before starting visiowings

### No syncing/constant exporting
- Ensure file watcher is running and files are saved
- Document must be open in Visio
- Use `--debug` to diagnose issues

### Unicode/Encoding
- Use UTF-8 in VS Code
- **NEW:** All import/export routines auto-convert and normalize encoding for safe editing

### Document module updates
- Use `--force` to update ThisDocument.cls modules
- **NEW:** Document modules are handled with extra safety and user confirmation

---

## Roadmap

The 1.0 release stabilises the CLI surface (`edit`, `export`, `import`)
and the file-format support; no breaking changes are planned before 2.0.
Future enhancements being considered:

- [ ] Python ↔ Visio integration (`RunPython`, similar to xlwings)
- [ ] Configurable polling interval
- [ ] GUI version
- [ ] Auto-backup before import
- [ ] Diff viewer
- [ ] `.visiowingsignore` file support
- [ ] More advanced sync/import examples in the docs

---

## Contributing

Help and PRs welcome! Quick start:

```bash
git clone https://github.com/twobeass/visiowings.git
cd visiowings
just install        # or: pip install -e ".[dev,docs]" && pre-commit install
just lint && just test
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow and
[Development environment](https://twobeass.github.io/visiowings/contributing/development-environment/)
for the tooling reference (`just`, `nox`, pre-commit, shared editor
config).

### Security & supply chain

- Releases ship a **CycloneDX SBOM** + **license report**, both signed
  with **Sigstore** (keyless OIDC). Verify any release artefact with
  `sigstore verify github` — see
  [Releasing → Verifying a release](https://twobeass.github.io/visiowings/contributing/releasing/#verifying-a-release).
- Wheels and sdists are published to PyPI via **Trusted Publishing**
  (no long-lived API tokens).
- Supply-chain posture is tracked weekly via
  [**OpenSSF Scorecard**](https://securityscorecards.dev/viewer/?uri=github.com/twobeass/visiowings).
- Vulnerabilities? See [SECURITY.md](SECURITY.md).

---

## License & Acknowledgments
MIT License – see [LICENSE](LICENSE)

- Inspired by [xlwings](https://www.xlwings.org/) by Felix Zumstein
- Built with [pywin32](https://github.com/mhammond/pywin32) & [watchdog](https://github.com/gorakhargosh/watchdog)

---

**twobeass** – [GitHub](https://github.com/twobeass)

⭐ Star the project, if helpful!
