pyOpenVBA 3.0.1__tar.gz → 3.2.0__tar.gz

{pyopenvba-3.0.1 → pyopenvba-3.2.0}/.gitignore

@@ -55,3 +55,7 @@ demo/_isolate.py
 # tests/live_access_test/_corpus_generate.ps1)
 tests/live_access_test/re_corpus/
 
+
+# Stray local test logs and Access lock files
+_pytest.log
+*.laccdb

{pyopenvba-3.0.1 → pyopenvba-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyOpenVBA
-Version: 3.0.1
+Version: 3.2.0
 Summary: Read and write VBA macros inside Excel, Word, and PowerPoint files in pure Python, no dependencies.
 Project-URL: Homepage, https://github.com/WilliamSmithEdward/pyOpenVBA
 Project-URL: Repository, https://github.com/WilliamSmithEdward/pyOpenVBA
@@ -54,8 +54,6 @@ Supports:
 * Word (`.docm`, `.dotm`, `.doc`)
 * Access (`.accdb`) - **read-only**
 
-<a href="https://github.com/sponsors/WilliamSmithEdward"><img src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?style=for-the-badge" alt="Sponsor WilliamSmithEdward"></a>
-
 ---
 
 ## Why use this?
@@ -257,6 +255,12 @@ with ExcelFile("workbook.xlsm") as wb:
     wb.save("out.xlsm")
 ```
 
+Class sources are accepted in any form: a bare body (the header is
+synthesized), a `.cls` file exported straight from the VBE (the
+`VERSION ... CLASS` preamble is stripped and the required
+`Attribute VB_Base` line is added automatically), or a full
+stream-form source.
+
 ---
 
 ## Edit your macros as files on disk (recommended workflow)
@@ -441,17 +445,21 @@ See [docs/roadmap.md](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/
 
 ```
 src/pyopenvba/
-  __init__.py     public API (ExcelFile, WordFile, PowerPointFile,
+  __init__.py     public API (ExcelFile, WordFile, PowerPointFile, AccessReader,
                               pull/push, pull_word/push_word, pull_ppt/push_ppt,
-                              VBAModuleKind, synthesize_class_header, exceptions)
-  excel.py        ExcelFile facade (ZIP / CFB dispatch, pull/push helpers)
-  word.py         WordFile facade
-  powerpoint.py   PowerPointFile facade
+                              pull_access, VBAModuleKind, synthesize_class_header,
+                              exceptions)
+  _host.py        VBAHostFile: shared open/edit/pull/push/save pipeline
+  excel.py        ExcelFile (thin VBAHostFile subclass + create_new template)
+  word.py         WordFile (thin VBAHostFile subclass + create_new template)
+  powerpoint.py   PowerPointFile (thin VBAHostFile subclass + create_new template)
+  access_read.py  AccessReader (read-only ACE/Jet page + LVAL reader)
   vba.py          VBA project parser + MS-OVBA codec
+  vba_pcode.py    VBA7 p-code disassembler
   cfb.py          MS-CFB (Compound File Binary) parser/writer
   exceptions.py   custom exception hierarchy
   _templates/     baked-in empty .xlsm/.xlsb/.docm/.pptm bytes for create_new()
-  __main__.py     `python -m pyopenvba {pull,push,ls}` CLI
+  __main__.py     `python -m pyopenvba {pull,push,ls,disasm,access-*}` CLI
 ```
 
 For deeper documentation:
@@ -477,6 +485,15 @@ pyright src tests
 pytest -p no:randomly
 ```
 
+On a Windows machine with desktop Excel installed you can additionally run
+the live compile-and-run gate (skipped by default and in CI). It builds a
+workbook with pyOpenVBA, runs its macro in real Excel under a popup-aware
+harness, and fails on any VBE dialog:
+
+```powershell
+$env:RUN_LIVE_EXCEL = "1"; pytest tests/test_live_excel_gate.py
+```
+
 CI runs the test matrix on Python 3.10 / 3.11 / 3.12 / 3.13 across
 Linux, plus 3.12 on Windows and macOS, on every push and pull request.
 Releases are published to PyPI automatically when a `v*.*.*` tag is
@@ -487,3 +504,14 @@ pushed.
 ## License
 
 [MIT](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/LICENSE.md).
+
+---
+
+## Support Open Source
+
+pyOpenVBA is open-source software. If it saves you time or helps your team keep
+VBA workbooks maintainable, support helps keep the project moving.
+
+- [GitHub Sponsors](https://github.com/sponsors/WilliamSmithEdward)
+- [PayPal](https://www.paypal.com/donate/?business=ML855BRLNR838&no_recurring=0&item_name=VBA+has+always+treated+me+well.+It+was+how+I+first+grew+professional+as+a+programmer%2C+I%27m+happy+to+show+it+some+love+%E2%9D%A4%EF%B8%8F&currency_code=USD)
+- [Cash App](https://cash.app/$williamesmithjcil)

{pyopenvba-3.0.1 → pyopenvba-3.2.0}/README.md

@@ -18,8 +18,6 @@ Supports:
 * Word (`.docm`, `.dotm`, `.doc`)
 * Access (`.accdb`) - **read-only**
 
-<a href="https://github.com/sponsors/WilliamSmithEdward"><img src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?style=for-the-badge" alt="Sponsor WilliamSmithEdward"></a>
-
 ---
 
 ## Why use this?
@@ -221,6 +219,12 @@ with ExcelFile("workbook.xlsm") as wb:
     wb.save("out.xlsm")
 ```
 
+Class sources are accepted in any form: a bare body (the header is
+synthesized), a `.cls` file exported straight from the VBE (the
+`VERSION ... CLASS` preamble is stripped and the required
+`Attribute VB_Base` line is added automatically), or a full
+stream-form source.
+
 ---
 
 ## Edit your macros as files on disk (recommended workflow)
@@ -405,17 +409,21 @@ See [docs/roadmap.md](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/
 
 ```
 src/pyopenvba/
-  __init__.py     public API (ExcelFile, WordFile, PowerPointFile,
+  __init__.py     public API (ExcelFile, WordFile, PowerPointFile, AccessReader,
                               pull/push, pull_word/push_word, pull_ppt/push_ppt,
-                              VBAModuleKind, synthesize_class_header, exceptions)
-  excel.py        ExcelFile facade (ZIP / CFB dispatch, pull/push helpers)
-  word.py         WordFile facade
-  powerpoint.py   PowerPointFile facade
+                              pull_access, VBAModuleKind, synthesize_class_header,
+                              exceptions)
+  _host.py        VBAHostFile: shared open/edit/pull/push/save pipeline
+  excel.py        ExcelFile (thin VBAHostFile subclass + create_new template)
+  word.py         WordFile (thin VBAHostFile subclass + create_new template)
+  powerpoint.py   PowerPointFile (thin VBAHostFile subclass + create_new template)
+  access_read.py  AccessReader (read-only ACE/Jet page + LVAL reader)
   vba.py          VBA project parser + MS-OVBA codec
+  vba_pcode.py    VBA7 p-code disassembler
   cfb.py          MS-CFB (Compound File Binary) parser/writer
   exceptions.py   custom exception hierarchy
   _templates/     baked-in empty .xlsm/.xlsb/.docm/.pptm bytes for create_new()
-  __main__.py     `python -m pyopenvba {pull,push,ls}` CLI
+  __main__.py     `python -m pyopenvba {pull,push,ls,disasm,access-*}` CLI
 ```
 
 For deeper documentation:
@@ -441,6 +449,15 @@ pyright src tests
 pytest -p no:randomly
 ```
 
+On a Windows machine with desktop Excel installed you can additionally run
+the live compile-and-run gate (skipped by default and in CI). It builds a
+workbook with pyOpenVBA, runs its macro in real Excel under a popup-aware
+harness, and fails on any VBE dialog:
+
+```powershell
+$env:RUN_LIVE_EXCEL = "1"; pytest tests/test_live_excel_gate.py
+```
+
 CI runs the test matrix on Python 3.10 / 3.11 / 3.12 / 3.13 across
 Linux, plus 3.12 on Windows and macOS, on every push and pull request.
 Releases are published to PyPI automatically when a `v*.*.*` tag is
@@ -451,3 +468,14 @@ pushed.
 ## License
 
 [MIT](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/LICENSE.md).
+
+---
+
+## Support Open Source
+
+pyOpenVBA is open-source software. If it saves you time or helps your team keep
+VBA workbooks maintainable, support helps keep the project moving.
+
+- [GitHub Sponsors](https://github.com/sponsors/WilliamSmithEdward)
+- [PayPal](https://www.paypal.com/donate/?business=ML855BRLNR838&no_recurring=0&item_name=VBA+has+always+treated+me+well.+It+was+how+I+first+grew+professional+as+a+programmer%2C+I%27m+happy+to+show+it+some+love+%E2%9D%A4%EF%B8%8F&currency_code=USD)
+- [Cash App](https://cash.app/$williamesmithjcil)

{pyopenvba-3.0.1 → pyopenvba-3.2.0}/docs/architecture.md

@@ -18,20 +18,17 @@ knows about the layer below it but not the layer above.
 
 ```
 +--------------------------------------------------------+
-| excel.py        ExcelFile facade                       |
-|   - ZIP / raw-CFB dispatch by extension                |
-|   - save() pipeline (safety gates, structural rewrites)|
-|   - pull / push disk workflow                          |
+| excel.py / word.py / powerpoint.py   host facades      |
+|   - thin subclasses of _host.VBAHostFile               |
+|   - per-host constants: container extensions,          |
+|     vbaProject.bin entry path, message wording         |
+|   - create_new() from a baked-in template              |
 +--------------------------------------------------------+
-| word.py         WordFile facade                        |
+| _host.py        VBAHostFile shared implementation      |
 |   - ZIP / raw-CFB dispatch by extension                |
-|   - identical save() pipeline as ExcelFile             |
-|   - pull / push disk workflow                          |
-+--------------------------------------------------------+
-| powerpoint.py   PowerPointFile facade                  |
-|   - ZIP / raw-CFB dispatch by extension                |
-|   - identical save() pipeline as ExcelFile             |
+|   - save() pipeline (safety gates, structural rewrites)|
 |   - pull / push disk workflow                          |
+|   - class-source normalization at set_module / push    |
 +--------------------------------------------------------+
 | access_read.py  AccessReader facade  (READ-ONLY)         |
 |   - ACE / Jet 4 page reader (.accdb, .mdb)             |
@@ -87,8 +84,9 @@ Other files:
 - `cfb.py` is **completely VBA-agnostic** and could be lifted into a
   separate library. It knows nothing about MS-OVBA.
 - `vba.py` operates on a `CFB` instance but never opens files on disk.
-- `excel.py` is the only module that touches the filesystem, ZIP
-  containers, or workbook paths.
+- `_host.py` is the only module that touches the filesystem, ZIP
+  containers, or host file paths; the three facades only supply
+  constants and `create_new()` templates.
 - Cross-layer leaks are a code smell. Adding a `pathlib.Path` import to
   `vba.py` or `cfb.py` is a red flag.
 
@@ -407,9 +405,7 @@ files in the same commit:
 | New layer / module                           | This file (sections 1 and 2), README architecture box |
 | New roadmap gate or status change            | `docs/roadmap.md`                                 |
 | New mutation safety gate                     | This file section 4, README "Safety guards"       |
-| New supported file extension (Excel)         | `excel.py` dispatch, README table, this file section 5       |
-| New supported file extension (Word)          | `word.py` dispatch, README table, this file section 5        |
-| New supported file extension (PowerPoint)    | `powerpoint.py` dispatch, README table, this file section 5  |
+| New supported file extension                 | Facade `_zip_formats` / `_cfb_formats`, `__main__._HOST_BY_SUFFIX`, README table, this file section 5 |
 | New test file or fuzz target                 | This file section 8                               |
 | Spec/behavior change worth telling other implementers | `docs/ms-ovba-implementation-guide_v2.md` |
 

{pyopenvba-3.0.1 → pyopenvba-3.2.0}/docs/roadmap.md

@@ -1,7 +1,7 @@
 # pyOpenVBA Roadmap
 
 This roadmap tracks pyOpenVBA's progress against the 26 hard gates defined in
-[`xlsm_feature_completeness_gates.md`](../xlsm_feature_completeness_gates.md).
+[`xlsm_feature_completeness_gates.md`](xlsm_feature_completeness_gates.md).
 Per-gate status keys:
 
 - **PASS** — implemented; gate tests in [`tests/test_gates.py`](../tests/test_gates.py) pass.

{pyopenvba-3.0.1 → pyopenvba-3.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyOpenVBA"
-version = "3.0.1"
+version = "3.2.0"
 description = "Read and write VBA macros inside Excel, Word, and PowerPoint files in pure Python, no dependencies."
 readme = "README.md"
 license = { text = "MIT" }

{pyopenvba-3.0.1 → pyopenvba-3.2.0}/src/pyopenvba/__init__.py

@@ -204,4 +204,4 @@ __all__ = [
     "push_word",
 ]
 
-__version__ = "2.0.0"
+__version__ = "3.2.0"

{pyopenvba-3.0.1 → pyopenvba-3.2.0}/src/pyopenvba/__main__.py

@@ -3,13 +3,16 @@ Command-line entry point.
 
 Usage::
 
-    python -m pyopenvba pull <workbook> <dest_dir>
-    python -m pyopenvba push <src_dir> <workbook> [--out <new_path>] [--strict]
-    python -m pyopenvba ls   <workbook>
+    python -m pyopenvba pull <office_file> <dest_dir>
+    python -m pyopenvba push <src_dir> <office_file> [--out <new_path>] [--strict]
+    python -m pyopenvba ls   <office_file>
     python -m pyopenvba access-ls    <accdb>
     python -m pyopenvba access-pull  <accdb> <dest_dir>
     python -m pyopenvba access-disasm <accdb> [--module <name>] [--with-source]
-    python -m pyopenvba disasm <workbook|doc|pptx> [--module <name>] [--with-source]
+    python -m pyopenvba disasm <office_file> [--module <name>] [--with-source]
+
+``<office_file>`` may be any supported Excel, Word, or PowerPoint file;
+the host is selected by extension (see ``_HOST_BY_SUFFIX``).
 """
 
 from __future__ import annotations
@@ -18,26 +21,51 @@ import argparse
 import sys
 from pathlib import Path
 
-from pyopenvba import ExcelFile, PowerPointFile, WordFile, pull, push
+from pyopenvba import ExcelFile, PowerPointFile, WordFile
+
+
+def _resolve_host(path: Path) -> type | None:
+    """Return the host file class for ``path`` by extension, or ``None``
+    (after printing an error) when the extension is unsupported."""
+    host_cls = _HOST_BY_SUFFIX.get(path.suffix.lower())
+    if host_cls is None:
+        print(
+            f"error: unsupported file type {path.suffix.lower()!r}; expected one of "
+            f"{sorted(_HOST_BY_SUFFIX)}",
+            file=sys.stderr,
+        )
+    return host_cls
 
 
 def _cmd_pull(args: argparse.Namespace) -> int:
-    written = pull(args.workbook, args.dest, overwrite=not args.no_overwrite)
+    host_cls = _resolve_host(args.workbook)
+    if host_cls is None:
+        return 2
+    with host_cls(args.workbook) as host:
+        written = host.pull_modules(args.dest, overwrite=not args.no_overwrite)
     for p in written:
         print(p)
     return 0
 
 
 def _cmd_push(args: argparse.Namespace) -> int:
-    updated = push(args.src, args.workbook, out=args.out, strict=args.strict)
+    host_cls = _resolve_host(args.workbook)
+    if host_cls is None:
+        return 2
+    with host_cls(args.workbook) as host:
+        updated = host.push_modules(args.src, strict=args.strict)
+        host.save(args.out)
     for name in updated:
         print(name)
     return 0
 
 
 def _cmd_ls(args: argparse.Namespace) -> int:
-    with ExcelFile(args.workbook) as wb:
-        for m in wb.vba_project().modules:
+    host_cls = _resolve_host(args.workbook)
+    if host_cls is None:
+        return 2
+    with host_cls(args.workbook) as host:
+        for m in host.vba_project().modules:
             print(f"{m.kind.name:8s}  {m.name}")
     return 0
 
@@ -55,10 +83,9 @@ def _cmd_access_pull(args: argparse.Namespace) -> int:
     from pyopenvba.access_read import AccessReader
 
     db = AccessReader(args.database)
-    args.dest.mkdir(parents=True, exist_ok=True)
-    for m in db.iter_vba_modules():
-        out = args.dest / f"{m.name}.bas"
-        out.write_text(m.source, encoding="utf-8")
+    # pull_modules classifies standard modules as .bas and class modules
+    # as .cls, matching the Excel/Word/PowerPoint pull commands.
+    for out in db.pull_modules(args.dest):
         print(out)
     return 0
 
@@ -90,16 +117,19 @@ def _cmd_access_disasm(args: argparse.Namespace) -> int:
     return 0
 
 
+# Every extension listed here is accepted by the mapped host class;
+# keep this in lockstep with each facade's _ZIP_FORMATS / _CFB_FORMATS.
 _HOST_BY_SUFFIX: dict[str, type] = {
     ".xlsm": ExcelFile,
     ".xlsb": ExcelFile,
-    ".xltm": ExcelFile,
     ".xlam": ExcelFile,
+    ".xls": ExcelFile,
     ".docm": WordFile,
     ".dotm": WordFile,
+    ".doc": WordFile,
     ".pptm": PowerPointFile,
     ".potm": PowerPointFile,
-    ".ppam": PowerPointFile,
+    ".ppt": PowerPointFile,
 }