pyOpenVBA 2.0.0__tar.gz → 3.0.0__tar.gz

{pyopenvba-2.0.0 → pyopenvba-3.0.0}/.gitignore

@@ -50,3 +50,8 @@ demo/output/
 # Debug/diagnostic scratch scripts
 demo/_diag*.py
 demo/_isolate.py
+
+# Access p-code RE corpus (regenerable via
+# tests/live_access_test/_corpus_generate.ps1)
+tests/live_access_test/re_corpus/
+

{pyopenvba-2.0.0 → pyopenvba-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyOpenVBA
-Version: 2.0.0
+Version: 3.0.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
@@ -39,7 +39,7 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://img.shields.io/pypi/v/pyOpenVBA.svg)](https://pypi.org/project/pyOpenVBA/)
 [![Python versions](https://img.shields.io/pypi/pyversions/pyOpenVBA.svg)](https://pypi.org/project/pyOpenVBA/)
 [![CI](https://github.com/WilliamSmithEdward/pyOpenVBA/actions/workflows/ci.yml/badge.svg)](https://github.com/WilliamSmithEdward/pyOpenVBA/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/LICENSE.md)
 [![Downloads](https://img.shields.io/pypi/dm/pyOpenVBA.svg)](https://pypi.org/project/pyOpenVBA/)
 
 **Read and write VBA macros inside Excel, Word, and PowerPoint files, in pure Python.**
@@ -52,6 +52,8 @@ Supports:
 * Excel (`.xlsm`, `.xlsb`, `.xlam`, `.xls`)
 * PowerPoint (`.pptm`, `.potm`, `.ppt`)
 * Word (`.docm`, `.dotm`, `.doc`)
+* Access (`.accdb`) - **read-only**, see
+  [docs/msaccess_lessons_learned.md](docs/msaccess_lessons_learned.md)
 
 <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>
 
@@ -226,18 +228,9 @@ with ExcelFile("workbook.xlsm") as wb:
         kind=VBAModuleKind.standard,
     )
 
-    # Add a class module (VB_Base attribute is required)
-    _CLASS_VB_BASE = "0{FCFB3D2A-A0FA-1068-A738-08002B3371B5}"
+    # Add a class module (header is synthesized automatically)
     project.add_module(
         "MyClass",
-        f'Attribute VB_Name = "MyClass"\r\n'
-        f'Attribute VB_Base = "{_CLASS_VB_BASE}"\r\n'
-        "Attribute VB_GlobalNameSpace = False\r\n"
-        "Attribute VB_Creatable = False\r\n"
-        "Attribute VB_PredeclaredId = False\r\n"
-        "Attribute VB_Exposed = False\r\n"
-        "Attribute VB_TemplateDerived = False\r\n"
-        "Attribute VB_Customizable = False\r\n"
         "Option Explicit\r\n",
         kind=VBAModuleKind.other,
     )
@@ -335,6 +328,45 @@ modules, `.cls` for class modules and code-behind.
 | `.potm`   | Macro-enabled template       |  yes |  yes  |    no      |
 | `.ppt`    | Legacy (PowerPoint 97-2003)  |  yes |  yes  |    no      |
 
+### Access (read-only)
+
+| Extension | What it is                   | Read | Write | create_new |
+|-----------|------------------------------|:----:|:-----:|:----------:|
+| `.accdb`  | Access database (ACE engine) |  yes |  no   |    no      |
+
+Access stores compiled VBA p-code (the `rU@` + `CAFE` rows in the LVAL
+catalog) separately from the OVBA source cache. The compiled p-code is
+authoritative for the Access GUI; mutations to the source cache do not
+survive reload because Access never recompiles from the cache. After
+extensive reverse-engineering experiments we concluded that a
+production-quality writer would require a complete VBA7 p-code
+assembler, which is out of scope. See
+[docs/msaccess_lessons_learned.md](docs/msaccess_lessons_learned.md)
+for the full chronicle.
+
+What `AccessReader` does support:
+
+- `AccessReader(path)` / `vba_module_names()` / `read_vba_module(name)`
+- `read_vba_module_with_attributes(name)`
+- `vba_modules()` (dict of name -> source)
+- `iter_vba_modules()` (rich `VBAModule` records)
+- `export_module()` / `export_modules()` / `pull_modules()` (write `.bas` / `.cls` to disk)
+- `read_project_info()`, `identifiers()`, `find_interned_strings()`,
+  `find_module_streams()`, `iter_pcode_streams()`, `disassemble_module()`
+- `iter_msys_objects()` / `msys_objects()` / `iter_msys_modules()` /
+  `find_msys_module()` (MSysObjects catalog inspection)
+- Top-level helper: `pyopenvba.pull_access(database, dest_dir)`
+
+```python
+from pyopenvba import AccessReader, pull_access
+
+with AccessReader("database.accdb") as db:
+    for name, source in db.vba_modules().items():
+        print(name, len(source))
+
+pull_access("database.accdb", "./vba_src")   # export every module to .bas / .cls
+```
+
 Every save is verified to reopen in the host application **without** the
 "we found a problem with some content" repair dialog.
 
@@ -385,7 +417,7 @@ following are preserved byte-for-byte but not interpreted:
 - Re-signing digitally signed projects.
 - ActiveX license editing.
 
-See [docs/roadmap.md](docs/roadmap.md) for the full feature matrix.
+See [docs/roadmap.md](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/docs/roadmap.md) for the full feature matrix.
 
 ---
 
@@ -395,7 +427,7 @@ See [docs/roadmap.md](docs/roadmap.md) for the full feature matrix.
 src/pyopenvba/
   __init__.py     public API (ExcelFile, WordFile, PowerPointFile,
                               pull/push, pull_word/push_word, pull_ppt/push_ppt,
-                              VBAModuleKind, exceptions)
+                              VBAModuleKind, synthesize_class_header, exceptions)
   excel.py        ExcelFile facade (ZIP / CFB dispatch, pull/push helpers)
   word.py         WordFile facade
   powerpoint.py   PowerPointFile facade
@@ -408,10 +440,10 @@ src/pyopenvba/
 
 For deeper documentation:
 
-- [docs/architecture.md](docs/architecture.md) - internal module layout.
-- [docs/ms-ovba-implementation-guide_v2.md](docs/ms-ovba-implementation-guide_v2.md) -
+- [docs/architecture.md](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/docs/architecture.md) - internal module layout.
+- [docs/ms-ovba-implementation-guide_v2.md](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/docs/ms-ovba-implementation-guide_v2.md) -
   language-agnostic guide for re-implementing MS-OVBA in another language.
-- [docs/roadmap.md](docs/roadmap.md) - per-feature implementation status.
+- [docs/roadmap.md](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/docs/roadmap.md) - per-feature implementation status.
 
 ---
 
@@ -438,4 +470,4 @@ pushed.
 
 ## License
 
-[MIT](LICENSE.md).
+[MIT](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/LICENSE.md).

{pyopenvba-2.0.0 → pyopenvba-3.0.0}/README.md

@@ -3,7 +3,7 @@
 [![PyPI version](https://img.shields.io/pypi/v/pyOpenVBA.svg)](https://pypi.org/project/pyOpenVBA/)
 [![Python versions](https://img.shields.io/pypi/pyversions/pyOpenVBA.svg)](https://pypi.org/project/pyOpenVBA/)
 [![CI](https://github.com/WilliamSmithEdward/pyOpenVBA/actions/workflows/ci.yml/badge.svg)](https://github.com/WilliamSmithEdward/pyOpenVBA/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/LICENSE.md)
 [![Downloads](https://img.shields.io/pypi/dm/pyOpenVBA.svg)](https://pypi.org/project/pyOpenVBA/)
 
 **Read and write VBA macros inside Excel, Word, and PowerPoint files, in pure Python.**
@@ -16,6 +16,8 @@ Supports:
 * Excel (`.xlsm`, `.xlsb`, `.xlam`, `.xls`)
 * PowerPoint (`.pptm`, `.potm`, `.ppt`)
 * Word (`.docm`, `.dotm`, `.doc`)
+* Access (`.accdb`) - **read-only**, see
+  [docs/msaccess_lessons_learned.md](docs/msaccess_lessons_learned.md)
 
 <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>
 
@@ -190,18 +192,9 @@ with ExcelFile("workbook.xlsm") as wb:
         kind=VBAModuleKind.standard,
     )
 
-    # Add a class module (VB_Base attribute is required)
-    _CLASS_VB_BASE = "0{FCFB3D2A-A0FA-1068-A738-08002B3371B5}"
+    # Add a class module (header is synthesized automatically)
     project.add_module(
         "MyClass",
-        f'Attribute VB_Name = "MyClass"\r\n'
-        f'Attribute VB_Base = "{_CLASS_VB_BASE}"\r\n'
-        "Attribute VB_GlobalNameSpace = False\r\n"
-        "Attribute VB_Creatable = False\r\n"
-        "Attribute VB_PredeclaredId = False\r\n"
-        "Attribute VB_Exposed = False\r\n"
-        "Attribute VB_TemplateDerived = False\r\n"
-        "Attribute VB_Customizable = False\r\n"
         "Option Explicit\r\n",
         kind=VBAModuleKind.other,
     )
@@ -299,6 +292,45 @@ modules, `.cls` for class modules and code-behind.
 | `.potm`   | Macro-enabled template       |  yes |  yes  |    no      |
 | `.ppt`    | Legacy (PowerPoint 97-2003)  |  yes |  yes  |    no      |
 
+### Access (read-only)
+
+| Extension | What it is                   | Read | Write | create_new |
+|-----------|------------------------------|:----:|:-----:|:----------:|
+| `.accdb`  | Access database (ACE engine) |  yes |  no   |    no      |
+
+Access stores compiled VBA p-code (the `rU@` + `CAFE` rows in the LVAL
+catalog) separately from the OVBA source cache. The compiled p-code is
+authoritative for the Access GUI; mutations to the source cache do not
+survive reload because Access never recompiles from the cache. After
+extensive reverse-engineering experiments we concluded that a
+production-quality writer would require a complete VBA7 p-code
+assembler, which is out of scope. See
+[docs/msaccess_lessons_learned.md](docs/msaccess_lessons_learned.md)
+for the full chronicle.
+
+What `AccessReader` does support:
+
+- `AccessReader(path)` / `vba_module_names()` / `read_vba_module(name)`
+- `read_vba_module_with_attributes(name)`
+- `vba_modules()` (dict of name -> source)
+- `iter_vba_modules()` (rich `VBAModule` records)
+- `export_module()` / `export_modules()` / `pull_modules()` (write `.bas` / `.cls` to disk)
+- `read_project_info()`, `identifiers()`, `find_interned_strings()`,
+  `find_module_streams()`, `iter_pcode_streams()`, `disassemble_module()`
+- `iter_msys_objects()` / `msys_objects()` / `iter_msys_modules()` /
+  `find_msys_module()` (MSysObjects catalog inspection)
+- Top-level helper: `pyopenvba.pull_access(database, dest_dir)`
+
+```python
+from pyopenvba import AccessReader, pull_access
+
+with AccessReader("database.accdb") as db:
+    for name, source in db.vba_modules().items():
+        print(name, len(source))
+
+pull_access("database.accdb", "./vba_src")   # export every module to .bas / .cls
+```
+
 Every save is verified to reopen in the host application **without** the
 "we found a problem with some content" repair dialog.
 
@@ -349,7 +381,7 @@ following are preserved byte-for-byte but not interpreted:
 - Re-signing digitally signed projects.
 - ActiveX license editing.
 
-See [docs/roadmap.md](docs/roadmap.md) for the full feature matrix.
+See [docs/roadmap.md](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/docs/roadmap.md) for the full feature matrix.
 
 ---
 
@@ -359,7 +391,7 @@ See [docs/roadmap.md](docs/roadmap.md) for the full feature matrix.
 src/pyopenvba/
   __init__.py     public API (ExcelFile, WordFile, PowerPointFile,
                               pull/push, pull_word/push_word, pull_ppt/push_ppt,
-                              VBAModuleKind, exceptions)
+                              VBAModuleKind, synthesize_class_header, exceptions)
   excel.py        ExcelFile facade (ZIP / CFB dispatch, pull/push helpers)
   word.py         WordFile facade
   powerpoint.py   PowerPointFile facade
@@ -372,10 +404,10 @@ src/pyopenvba/
 
 For deeper documentation:
 
-- [docs/architecture.md](docs/architecture.md) - internal module layout.
-- [docs/ms-ovba-implementation-guide_v2.md](docs/ms-ovba-implementation-guide_v2.md) -
+- [docs/architecture.md](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/docs/architecture.md) - internal module layout.
+- [docs/ms-ovba-implementation-guide_v2.md](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/docs/ms-ovba-implementation-guide_v2.md) -
   language-agnostic guide for re-implementing MS-OVBA in another language.
-- [docs/roadmap.md](docs/roadmap.md) - per-feature implementation status.
+- [docs/roadmap.md](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/docs/roadmap.md) - per-feature implementation status.
 
 ---
 
@@ -402,4 +434,4 @@ pushed.
 
 ## License
 
-[MIT](LICENSE.md).
+[MIT](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/LICENSE.md).

{pyopenvba-2.0.0 → pyopenvba-3.0.0}/docs/architecture.md

@@ -33,12 +33,34 @@ knows about the layer below it but not the layer above.
 |   - identical save() pipeline as ExcelFile             |
 |   - pull / push disk workflow                          |
 +--------------------------------------------------------+
+| access_read.py  AccessReader facade  (READ-ONLY)         |
+|   - ACE / Jet 4 page reader (.accdb, .mdb)             |
+|   - MS-OVBA blob discovery via signature scan          |
+|   - LVAL page-chain walker                             |
+|   - read_vba_module(name) -> str (pure Python)         |
+|   - get_module / vba_modules / iter_vba_modules        |
+|   - pull_modules / export_modules / export_module      |
+|   - read_vba_module_with_attributes (full preamble)    |
+|   - read_project_info / identifiers                    |
+|   - find_interned_strings / find_module_streams        |
+|   - iter_pcode_streams / read_module_pcode_stream      |
+|   - disassemble_module (via vba_pcode)                 |
+|   - iter_msys_objects / find_msys_module               |
+|       (MSysObjects system catalog reader)              |
+|   - NO write APIs; see msaccess_lessons_learned.md     |
++--------------------------------------------------------+
 | vba.py          VBA project layer                      |
 |   - MS-OVBA compression / decompression                |
 |   - dir / PROJECT / PROJECTwm / PROJECTlk parsers      |
 |   - VBAProject + VBAModule data model                  |
 |   - cache invalidation, signature detection            |
 +--------------------------------------------------------+
+| vba_pcode.py    VBA7 p-code disassembler  (EXPERIMENTAL)|
+|   - 264-entry VBA7 opcode table (factual data)         |
+|   - per-line p-code streaming parser                   |
+|   - source-line correlation (to_annotated_listing)     |
+|   - dependency-free (no oletools, no pcodedmp)         |
++--------------------------------------------------------+
 | cfb.py          MS-CFB layer                           |
 |   - Compound File Binary parser/writer                 |
 |   - stream + storage CRUD (case-insensitive lookup)    |
@@ -50,7 +72,10 @@ Other files:
 - `exceptions.py` — exception hierarchy shared by all layers.
 - `__init__.py` — public re-exports (`ExcelFile`, `pull`, `push`,
   `VBAModuleKind`, exceptions).
-- `__main__.py` — `python -m pyopenvba {pull,push,ls}` CLI.
+- `__main__.py` — `python -m pyopenvba
+  {pull,push,ls,access-ls,access-pull,access-disasm,disasm}` CLI.
+  `disasm` / `access-disasm` accept `--with-source` to interleave
+  the original VBA source with the decoded p-code.
 - `_templates/__init__.py` — generated module embedding a
   zlib-compressed base85 blob of a freshly Excel-authored empty `.xlsm`,
   consumed by `ExcelFile.create_new()`. Regenerated from
@@ -154,6 +179,84 @@ If any of steps 3-10 fail, the on-disk file is **never modified** —
 all work is done on the in-memory CFB and the final bytes are written
 in one atomic-ish operation.
 
+### 3.3 Access read-only model (`AccessReader`)
+
+`.accdb`/`.mdb` files are exposed through a **read-only** facade.
+After an extensive reverse-engineering effort (chronicled in
+[docs/msaccess_lessons_learned.md](msaccess_lessons_learned.md))
+pyOpenVBA does not support writing back to Access databases. Use
+Access COM (`win32com.client.Dispatch("Access.Application")`) if you
+need to programmatically modify VBA inside a `.accdb`.
+
+The Access on-disk layout differs from Excel/Word/PowerPoint:
+
+* The MS-OVBA blob on the LVAL chain is a **passive cache**. Zero-filling
+  the entire blob has no effect on what Access (or the VBA editor)
+  displays — verified end-to-end on a live fixture. This is what
+  pyOpenVBA reads.
+* The **authoritative** sources Access reads from are:
+  * **Project metadata** — the MS-OVBA `dir` stream (Section 2.3.4.2)
+    OVBA-compressed in a single LVAL row; located by content
+    (decompressed prefix = `01 00 04 00 00 00`). Parsed by
+    `AccessReader.read_project_info()` -> `AccessVBAProject` (system kind,
+    LCID, code page, project name, references, modules with class flag,
+    private/read-only flags).
+  * **Module bytecode** — the compiled VBA p-code. Lives in LVAL rows
+    whose payload starts with magic `72 55 40 00` ('rU@\0'). The
+    **module-active** one is identified deterministically by the
+    12-byte prefix `72 55 40 00 00 00 00 00 00 00 40 00`
+    (byte 10 = 0x40). Exposed via
+    `AccessReader.read_module_pcode_stream()` and `iter_pcode_streams()`.
+    Compiled p-code is **fully anonymised**: opcodes and slot
+    references with no user-authored text. The standard MS-OVBA
+    `0xCAFE` module stream coexists alongside `rU@` in a separate
+    LVAL row and is what `AccessReader.disassemble_module()` consumes
+    via the pure-Python `pyopenvba.vba_pcode` decoder.
+  * **Identifier inventory** — every project-level identifier name
+    (typelib refs, project name, module/proc/variable names, intrinsic
+    call targets such as `MsgBox`) is enumerated in the
+    `_VBA_PROJECT`-equivalent stream stored UNCOMPRESSED in the LVAL
+    row whose first 2 bytes are the `CC 61` Office magic. Exposed via
+    `AccessReader.identifiers() -> tuple[AccessVBAIdentifier, ...]`.
+  * **Comment text** — stored verbatim in plaintext rows tagged
+    `E3 00 00 00 <u16-LE length> <ASCII payload>` (apostrophe stripped).
+  * **String literal text** — stored verbatim in rows tagged
+    `B9 00 <u16-LE length> <ASCII payload> <12-byte trailer>`,
+    exposed via `AccessReader.find_interned_strings()`.
+
+The **MSysObjects** system catalog is also surfaced read-only:
+`AccessReader.iter_msys_objects()`, `msys_objects()`,
+`iter_msys_modules()`, `find_msys_object(name, *, type_=None)`,
+`find_msys_module(name)`. Each row yields an `AccessSysObject`
+dataclass (id_, parent_id, type_, flags, name, page, slot). VBA code
+modules carry `type_ == MSYS_TYPE_MODULE` (-32761, 0x8007) and are
+parented to the `Modules` container row.
+
+### Excel-symmetric VBA module read API
+
+`AccessReader` exposes the same ergonomic read surface as `ExcelFile` /
+`WordFile` / `PowerPointFile`: `get_module(name)`,
+`vba_modules() -> dict[str, str]`, `read_vba_module(name)`,
+`read_vba_module_with_attributes(name)`, `iter_vba_modules()`,
+`pull_modules(dest_dir)`, `export_module(name)`,
+`export_modules(dest_dir, *, include_attributes=False)`. The
+top-level helper `pyopenvba.pull_access(database, dest_dir)` mirrors
+`pull` / `pull_word` / `pull_ppt`. There is intentionally no
+`push_access` symbol.
+
+### Why no write path
+
+Access stores compiled VBA p-code (the `rU@` + `CAFE` rows) separately
+from the OVBA source cache. The compiled p-code is authoritative for
+the Access GUI; mutations to the source cache do not survive reload
+because Access never recompiles from the cache. We could not locate a
+recompile trigger. A production-quality writer would require a full
+VBA7 p-code assembler (instruction emission, identifier table
+re-indexing, jump fixup, MSysObjects long-value chunk reflow, ACE
+page allocator parity). That is out of scope. See
+[docs/msaccess_lessons_learned.md](msaccess_lessons_learned.md) for
+the empirical results matrix and the reasoning in full.
+
 ---
 
 ## 4. Mutation safety gates
@@ -256,10 +359,14 @@ tests/
   test_powerpoint.py           PowerPointFile facade, end-to-end
   test_pull_push.py            Disk workflow
   test_gates.py                Per-roadmap-gate regression tests
+  test_access.py               AccessReader read path: page walk,
+                               LVAL chain walk, MS-OVBA blob decode,
+                               byte-for-byte oracle parity (EXPERIMENTAL)
   fuzz_corpus/                 Persistent fuzz seeds (see test_gates.py Gate 23)
   live_excel_testing/          Real fixture workbooks (Excel)
   live_word_testing/           Real fixture documents (Word)
   live_powerpoint_testing/     Real fixture presentations (PowerPoint)
+  live_access_test/            Real fixture databases (Access) + COM oracle
 ```
 
 - **Always** run pytest with `-p no:randomly` to keep ordering

{pyopenvba-2.0.0 → pyopenvba-3.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyOpenVBA"
-version = "2.0.0"
+version = "3.0.0"
 description = "Read and write VBA macros inside Excel, Word, and PowerPoint files in pure Python, no dependencies."
 readme = "README.md"
 license = { text = "MIT" }
@@ -86,3 +86,37 @@ testpaths = ["tests"]
 include = ["src", "tests"]
 pythonVersion = "3.10"
 typeCheckingMode = "strict"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "B", "UP", "SIM", "I", "RUF", "PIE", "C4", "PERF", "N", "TC", "RET", "TRY"]
+# Ignore rules that conflict with the project's strict-pyright typing posture,
+# intentional MS-spec naming, or stylistic preferences:
+#   B009    getattr(obj, "_private")  -- deliberate to bypass reportPrivateUsage in tests
+#   PIE807  default_factory=lambda: [] -- pyright strict cannot infer element type from bare `list`
+#   TRY003  raising vanilla exception messages is fine in this project
+#   E501    long lines are tolerated where they aid readability of binary specs
+#   N801/N802/N806  mixed-case names mirror MS-OVBA spec record/field names
+#   PERF203 try/except inside loops is required for per-row recovery in parsers
+#   PERF401 manual list builds are clearer than comprehensions in spec-driven code
+#   SIM105  contextlib.suppress is slower; explicit try/except is preferred
+#   TRY300  try-else is stylistic
+#   TC001/TC003  moving runtime-required imports into TYPE_CHECKING risks breakage
+ignore = [
+    "B009",
+    "PIE807",
+    "TRY003",
+    "E501",
+    "N801",
+    "N802",
+    "N806",
+    "PERF203",
+    "PERF401",
+    "SIM105",
+    "TRY300",
+    "TC001",
+    "TC003",
+]

{pyopenvba-2.0.0 → pyopenvba-3.0.0}/src/pyopenvba/__init__.py

@@ -13,10 +13,13 @@ Supported formats
 Public API
 ----------
     from pyopenvba import (
-        ExcelFile, WordFile, PowerPointFile,
+        ExcelFile, WordFile, PowerPointFile, AccessReader,
         pull, push, pull_word, push_word, pull_ppt, push_ppt,
+        pull_access,
     )
 
+    # Access (.accdb) is READ-ONLY. See docs/msaccess_lessons_learned.md.
+
     # In-process module edit (Excel)
     with ExcelFile("workbook.xlsm") as wb:
         modules = wb.vba_modules()          # dict[name -> source]
@@ -44,26 +47,29 @@ Public API
 
     pull_ppt("presentation.pptm", "./vba_src") # extract modules (PowerPoint)
     push_ppt("./vba_src", "presentation.pptm")
+
+    pull_access("database.accdb", "./vba_src") # extract modules (Access, read-only)
 """
 
 from pathlib import Path
-from typing import Union
 
+from pyopenvba.access_read import AccessReader
 from pyopenvba.excel import ExcelFile
-from pyopenvba.word import WordFile
-from pyopenvba.powerpoint import PowerPointFile
 from pyopenvba.exceptions import (
-    PyOpenVBAError,
     CFBError,
-    VBAProjectError,
+    PyOpenVBAError,
     UnsupportedFormatError,
+    VBAProjectError,
 )
+from pyopenvba.powerpoint import PowerPointFile
 from pyopenvba.vba import VBAModuleKind
+from pyopenvba.vba import synthesize_class_header as synthesize_class_header
+from pyopenvba.word import WordFile
 
 
 def pull(
-    workbook: Union[str, Path],
-    dest_dir: Union[str, Path],
+    workbook: str | Path,
+    dest_dir: str | Path,
     *,
     encoding: str = "utf-8",
     overwrite: bool = True,
@@ -77,10 +83,10 @@ def pull(
 
 
 def push(
-    src_dir: Union[str, Path],
-    workbook: Union[str, Path],
+    src_dir: str | Path,
+    workbook: str | Path,
     *,
-    out: Union[str, Path, None] = None,
+    out: str | Path | None = None,
     encoding: str = "utf-8",
     strict: bool = False,
 ) -> list[str]:
@@ -96,8 +102,8 @@ def push(
 
 
 def pull_word(
-    document: Union[str, Path],
-    dest_dir: Union[str, Path],
+    document: str | Path,
+    dest_dir: str | Path,
     *,
     encoding: str = "utf-8",
     overwrite: bool = True,
@@ -111,10 +117,10 @@ def pull_word(
 
 
 def push_word(
-    src_dir: Union[str, Path],
-    document: Union[str, Path],
+    src_dir: str | Path,
+    document: str | Path,
     *,
-    out: Union[str, Path, None] = None,
+    out: str | Path | None = None,
     encoding: str = "utf-8",
     strict: bool = False,
 ) -> list[str]:
@@ -130,8 +136,8 @@ def push_word(
 
 
 def pull_ppt(
-    presentation: Union[str, Path],
-    dest_dir: Union[str, Path],
+    presentation: str | Path,
+    dest_dir: str | Path,
     *,
     encoding: str = "utf-8",
     overwrite: bool = True,
@@ -145,10 +151,10 @@ def pull_ppt(
 
 
 def push_ppt(
-    src_dir: Union[str, Path],
-    presentation: Union[str, Path],
+    src_dir: str | Path,
+    presentation: str | Path,
     *,
-    out: Union[str, Path, None] = None,
+    out: str | Path | None = None,
     encoding: str = "utf-8",
     strict: bool = False,
 ) -> list[str]:
@@ -163,21 +169,39 @@ def push_ppt(
     return updated
 
 
+def pull_access(
+    database: str | Path,
+    dest_dir: str | Path,
+    *,
+    encoding: str = "utf-8",
+    overwrite: bool = True,
+) -> list[Path]:
+    """
+    Export every VBA module from an Access ``database`` (.accdb) into
+    ``dest_dir`` as ``.bas`` / ``.cls`` files. Returns the paths
+    written. Mirrors :func:`pull` / :func:`pull_word` / :func:`pull_ppt`.
+    """
+    db = AccessReader(database)
+    return db.pull_modules(dest_dir, encoding=encoding, overwrite=overwrite)
+
+
 __all__ = [
+    "AccessReader",
+    "CFBError",
     "ExcelFile",
-    "WordFile",
     "PowerPointFile",
-    "VBAModuleKind",
     "PyOpenVBAError",
-    "CFBError",
-    "VBAProjectError",
     "UnsupportedFormatError",
+    "VBAModuleKind",
+    "VBAProjectError",
+    "WordFile",
     "pull",
-    "push",
-    "pull_word",
-    "push_word",
+    "pull_access",
     "pull_ppt",
+    "pull_word",
+    "push",
     "push_ppt",
+    "push_word",
 ]
 
 __version__ = "2.0.0"