# williamsmithedward/pyopenvba architecture

> Architecture diagram of the GitHub repository williamsmithedward/pyopenvba, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/williamsmithedward/pyopenvba
- Repository: https://github.com/williamsmithedward/pyopenvba

## Overview

pyOpenVBA edits VBA projects and Power Query content inside Office packages without requiring Office. The main workflow is to open or create a host file, inspect or change its code, forms, references, or queries, then save it for reopening in the host. Excel also has a workbook-backed formula calculator; VBA object/runtime support and shared compound-file handling are internal layers. README relationships are used for the documented public workflows; unsampled implementation links are omitted where their call direction is uncertain.

Main entry points: [`src/pyopenvba/excel.py`](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/excel.py) (ExcelFile), [`src/pyopenvba/vba.py`](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/vba.py) (VBA projects), [`src/pyopenvba/word.py`](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/word.py) (WordFile), [`src/pyopenvba/powerpoint.py`](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/powerpoint.py) (PowerPointFile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hosts["Office VBA hosts"]
  node_excel_api["ExcelFile<br/>[excel.py]"]
  node_word_api["WordFile<br/>[word.py]"]
  node_ppt_api["PowerPointFile<br/>[powerpoint.py]"]
  node_access_api["AccessDatabase<br/>[database.py]"]
  node_vba_project["VBA projects<br/>[vba.py]"]
  node_forms["UserForms<br/>[forms.py]"]
end

subgraph group_excel["Excel capabilities"]
  node_excel_model["Excel workbook model<br/>[_model.py]"]
  node_formula_bridge["Formula workbook bridge<br/>[_engine_book.py]"]
  node_formula_engine["Formula engine"]
end

subgraph group_pq["Power Query"]
  node_pq_workbook["Power Query workbook<br/>[workbook.py]"]
end

subgraph group_runtime["Language runtime"]
  node_vba_interpreter["VBA interpreter<br/>[_runtime.py]"]
  node_object_model["VBA object model<br/>[_objects.py]"]
end

subgraph group_package["Package internals"]
  node_cfb["Compound files<br/>[cfb.py]"]
end

node_user(("Python user"))
node_office(("Office applications"))

node_user -->|"opens or creates"| node_excel_api
node_user -->|"opens or creates"| node_word_api
node_user -->|"opens or creates"| node_ppt_api
node_user -->|"opens or creates"| node_access_api
node_user -->|"opens or creates"| node_pq_workbook
node_excel_api -->|"edits VBA"| node_vba_project
node_word_api -->|"edits VBA"| node_vba_project
node_ppt_api -->|"edits VBA"| node_vba_project
node_access_api -->|"edits VBA"| node_vba_project
node_excel_api -->|"edits forms"| node_forms
node_excel_api -.->|"edits workbook"| node_excel_model
node_formula_bridge -->|"adapts workbook"| node_formula_engine
node_pq_workbook -->|"saves for reopening"| node_office
node_excel_api -->|"saves for reopening"| node_office
node_word_api -->|"saves for reopening"| node_office
node_ppt_api -->|"saves for reopening"| node_office
node_access_api -->|"saves for reopening"| node_office
node_vba_interpreter -.->|"dispatches members"| node_object_model
node_vba_project -->|"reads and writes"| node_cfb

click node_excel_api "https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/excel.py"
click node_word_api "https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/word.py"
click node_ppt_api "https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/powerpoint.py"
click node_access_api "https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/access/database.py"
click node_vba_project "https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/vba.py"
click node_forms "https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/forms.py"
click node_excel_model "https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/apps/excel/_model.py"
click node_formula_bridge "https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/apps/excel/_engine_book.py"
click node_formula_engine "https://github.com/williamsmithedward/pyopenvba/tree/main/src/pyopenvba/formula/_calc"
click node_pq_workbook "https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/powerquery/workbook.py"
click node_vba_interpreter "https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/interpreter/_runtime.py"
click node_object_model "https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/interpreter/_objects.py"
click node_cfb "https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/cfb.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_excel_api,node_word_api,node_ppt_api,node_access_api,node_vba_project,node_forms,node_user toneBlue
class node_excel_model,node_formula_bridge,node_formula_engine toneAmber
class node_pq_workbook toneMint
class node_vba_interpreter,node_object_model toneRose
class node_cfb,node_office toneIndigo
```

## Components

### Office VBA hosts

- [ExcelFile](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/excel.py): `src/pyopenvba/excel.py`
- [WordFile](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/word.py): `src/pyopenvba/word.py`
- [PowerPointFile](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/powerpoint.py): `src/pyopenvba/powerpoint.py`
- [AccessDatabase](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/access/database.py): `src/pyopenvba/access/database.py`
- [VBA projects](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/vba.py): `src/pyopenvba/vba.py`
- [UserForms](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/forms.py): `src/pyopenvba/forms.py`

### Excel capabilities

- [Excel workbook model](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/apps/excel/_model.py): `src/pyopenvba/apps/excel/_model.py`
- [Formula workbook bridge](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/apps/excel/_engine_book.py): `src/pyopenvba/apps/excel/_engine_book.py`
- [Formula engine](https://github.com/williamsmithedward/pyopenvba/tree/main/src/pyopenvba/formula/_calc): `src/pyopenvba/formula/_calc`

### Power Query

- [Power Query workbook](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/powerquery/workbook.py): `src/pyopenvba/powerquery/workbook.py`

### Language runtime

- [VBA interpreter](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/interpreter/_runtime.py): `src/pyopenvba/interpreter/_runtime.py`
- [VBA object model](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/interpreter/_objects.py): `src/pyopenvba/interpreter/_objects.py`

### Package internals

- [Compound files](https://github.com/williamsmithedward/pyopenvba/blob/main/src/pyopenvba/cfb.py): `src/pyopenvba/cfb.py`

### Other components

- **Python user**
- **Office applications**

## Connections

- Python user → ExcelFile: opens or creates
- Python user → WordFile: opens or creates
- Python user → PowerPointFile: opens or creates
- Python user → AccessDatabase: opens or creates
- Python user → Power Query workbook: opens or creates
- ExcelFile → VBA projects: edits VBA
- WordFile → VBA projects: edits VBA
- PowerPointFile → VBA projects: edits VBA
- AccessDatabase → VBA projects: edits VBA (evidence: `src/pyopenvba/access/database.py`)
- ExcelFile → UserForms: edits forms
- ExcelFile → Excel workbook model: edits workbook
- Formula workbook bridge → Formula engine: adapts workbook (evidence: `src/pyopenvba/apps/excel/_engine_book.py`)
- Power Query workbook → Office applications: saves for reopening
- ExcelFile → Office applications: saves for reopening
- WordFile → Office applications: saves for reopening
- PowerPointFile → Office applications: saves for reopening
- AccessDatabase → Office applications: saves for reopening
- VBA interpreter → VBA object model: dispatches members
- VBA projects → Compound files: reads and writes (evidence: `src/pyopenvba/vba.py`)
