WilliamSmithEdward/pyOpenVBA

v1.0.0 Feature

This release adds 3 notable features for engineering teams evaluating rollout.

Published 12d Developer Productivity

View tool

✓ No known CVEs patched

Read the diff → Tool health → What is this tool? →

✓ No known CVEs patched in this version

Topics

compound-file deterministic excel file-format macro-extraction ms-cfb

+13 more

ms-ovba office-automation openxml pure-python python roundtrip vba vba-macros xlam xls xlsb xlsm zero-dependencies

Summary

AI summary

Updates Highlights, Quality, and Out of scope across a mixed release.

Changes in this release

Type	Severity	Summary	CVE
Feature
Feature	Medium	Adds full round‑trip support for VBA projects across .xlsm, .xlsb, .xlam, and legacy .xls files. Adds full round‑trip support for VBA projects across .xlsm, .xlsb, .xlam, and legacy .xls files. Source: llm_adapter@2026-05-27 Confidence: high	—
Feature	Medium	Adds topology operations to add, rename, and delete VBA modules with consistent updates across all related streams. Adds topology operations to add, rename, and delete VBA modules with consistent updates across all related streams. Source: llm_adapter@2026-05-27 Confidence: high	—
Feature	Medium	Adds safety gates that refuse mutation of password‑protected projects unless allow_protected=True is passed. Adds safety gates that refuse mutation of password‑protected projects unless allow_protected=True is passed. Source: llm_adapter@2026-05-27 Confidence: high	—
Feature	Medium	Adds option to drop invalidated digital signatures on mutation, warnable via allow_invalidate_signature=True. Adds option to drop invalidated digital signatures on mutation, warnable via allow_invalidate_signature=True. Source: llm_adapter@2026-05-27 Confidence: high	—
Feature	Medium	Implements _VBA_PROJECT cache invalidation per MS‑OVBA 2.3.4.1 on every mutating save. Implements _VBA_PROJECT cache invalidation per MS‑OVBA 2.3.4.1 on every mutating save. Source: llm_adapter@2026-05-27 Confidence: high	—
Feature	Medium	Strips __SRP_* entries on save so Office regenerates a clean performance cache. Strips __SRP_* entries on save so Office regenerates a clean performance cache. Source: llm_adapter@2026-05-27 Confidence: high	—
Feature	Medium	Adds disk workflow helpers `pull` and `push` for round‑tripping module sources to/from .bas/.cls/.frm files. Adds disk workflow helpers `pull` and `push` for round‑tripping module sources to/from .bas/.cls/.frm files. Source: llm_adapter@2026-05-27 Confidence: high	—
Feature	Low	Introduces zero runtime dependencies and requires Python 3.10+. Introduces zero runtime dependencies and requires Python 3.10+. Source: llm_adapter@2026-05-27 Confidence: high	—
Feature	Low	Achieves strict Pyright clean (0 errors) on src/ and tests/ directories. Achieves strict Pyright clean (0 errors) on src/ and tests/ directories. Source: llm_adapter@2026-05-27 Confidence: high	—
Feature	Low	Provides extensive documentation including an MS‑OVBA implementation guide, architecture overview, and roadmap status. Provides extensive documentation including an MS‑OVBA implementation guide, architecture overview, and roadmap status. Source: llm_adapter@2026-05-27 Confidence: high	—

Full changelog

First stable release of pyOpenVBA — a pure-Python, zero-dependency
reader/writer for VBA macros embedded in Microsoft Office files.

Highlights

Full round-trip of VBA project source across .xlsm, .xlsb,
.xlam, and legacy .xls, verified to reopen in Excel without any
repair dialog.
Topology operations: add, rename, and delete modules with
consistent updates across dir, PROJECT, PROJECTwm, and the
underlying CFB streams.
Safety gates:
- Refuses to mutate password-protected projects unless
  allow_protected=True is passed.
- Drops invalidated digital signatures on mutation with a warning,
  silenceable via allow_invalidate_signature=True.
_VBA_PROJECT cache invalidation per MS-OVBA 2.3.4.1 on every
mutating save (header preserved, performance cache zeroed).
__SRP_* stripping on save so Office regenerates a clean
performance cache.
Disk workflow: pull / push helpers for round-tripping
module sources to and from a directory of .bas / .cls / .frm
files.
Zero runtime dependencies, supports Python 3.10+.
Strict Pyright clean (0 errors) on both src/ and tests/.

Quality

244 passing tests, 2 documented skips, 0 xfails.
Persistent fuzz corpus (~50 seeds across CFB, OVBA decompression,
dir, PROJECT, and PROJECTwm parsers).
Manual Excel verification matrix (9/9) covering no-op, source edit,
add, rename, delete, xlsm + xlsb, and protected mutation.

Documentation

docs/ms-ovba-implementation-guide_v2.md
— language-agnostic, distilled guide for implementing MS-OVBA in any
language; supersedes v1.
docs/architecture.md — internal layering
and module map.
docs/roadmap.md — all 26 implementation gates
closed (24 PASS, 2 explicitly out of scope).

Out of scope (by design)

UserForm layout editing (designer sub-storage preserved
verbatim; code-behind edits are fully supported).
VBA project password decryption / re-encryption.
Re-signing digitally signed projects.

Install

Clone and install in editable mode:

git clone https://github.com/WilliamSmithEdward/pyOpenVBA
pip install -e ./pyOpenVBA

PyPI wheel coming in a follow-up release.

Acknowledgements

Built against [MS-OVBA] v20260519 and [MS-CFB] v3, with live
verification on Excel for Microsoft 365 (May 2026).

View diff on GitHub

Weekly OSS security release digest.

The CVE patches and breaking changes that affected production tools this week. One email, every Sunday.

No spam, unsubscribe anytime.

Share this release

Share on X Share on Bluesky

Track WilliamSmithEdward/pyOpenVBA

Get notified when new releases ship.

About WilliamSmithEdward/pyOpenVBA

All releases →

Related context

Related tools

Earlier breaking changes

v3.0.0 Renamed the `AccessFile` class to `AccessReader`.
v3.0.0 Renamed `pyopenvba.access` module to `pyopenvba.access_read`.
v1.1.1 `add_module(kind=other)` now requires an explicit attribute header; automatic synthesis is disabled.