Metadata-Version: 2.5
Name: vba-reference
Version: 1.0.0
Summary: Programmatic, typed reference of the VBA object models for Excel, PowerPoint, Word, Access and the common shared COM type libraries (Office, ADO, MSXML, and more).
Project-URL: Homepage, https://github.com/WilliamSmithEdward/pyVBAReference
Project-URL: Repository, https://github.com/WilliamSmithEdward/pyVBAReference
Project-URL: Issues, https://github.com/WilliamSmithEdward/pyVBAReference/issues
Author: William Smith
License-Expression: MIT
License-File: LICENSE
Keywords: access,com,excel,macro,office,powerpoint,reference,typelib,vba,word
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Provides-Extra: generate
Requires-Dist: pywin32>=306; extra == 'generate'
Description-Content-Type: text/markdown

# pyVBAReference

A complete, machine-generated reference of the VBA (Visual Basic for Applications)
object models for Excel, PowerPoint, Word and Access, plus the nine shared COM
type libraries every host can reference. Every public type is exported as both
human-readable Markdown and machine-readable JSON.

## Layout

All generated data lives under `reference/` to keep the repo root clean:

```
reference/
  agentic_llm_primer.md  guide for AI agents (schema + grounding)
  index.json             master catalog of every library and type
  members.json           member name -> the types that define it
  <library>/
    md/     one .md per type   + _index.md
    json/   one .json per type + _index.json
  consolidated/          the same data folded into one set of files per app
    <app>.json / .md             every type
    <app>_constants.json / .md   every enumeration and module constant
    <app>_properties.json / .md  every property of every object
```

Both `md/` and `json/` hold the same data: signatures, return types, parameter
lists, property access modes, enum values, remarks, and examples - introspected
from the registered COM type libraries and enriched with descriptions from
Microsoft Learn.

## Libraries

Host applications:

| Folder       | Library                                  | Types |
| ------------ | ---------------------------------------- | ----- |
| `excel`      | Microsoft Excel 16.0 Object Library      | 1028  |
| `word`       | Microsoft Word 16.0 Object Library       | 750   |
| `powerpoint` | Microsoft PowerPoint 16.0 Object Library | 339   |
| `access`     | Microsoft Access 16.0 Object Library     | 289   |

Shared libraries, referenceable from any host:

| Folder      | Library                                              | Types |
| ----------- | ---------------------------------------------------- | ----- |
| `office`    | Microsoft Office 16.0 Object Library                 | 510   |
| `msforms`   | Microsoft Forms 2.0 Object Library                   | 166   |
| `adodb`     | Microsoft ActiveX Data Objects 6.1 Library           | 110   |
| `msxml`     | Microsoft XML, v6.0                                  | 101   |
| `vbide`     | Microsoft Visual Basic for Applications Extensibility | 45    |
| `scripting` | Microsoft Scripting Runtime                          | 28    |
| `vba`       | Visual Basic For Applications (language built-ins)   | 26    |
| `stdole`    | OLE Automation                                       | 11    |
| `winhttp`   | Microsoft WinHTTP Services, version 5.1              | 7     |

VBA language built-ins (`MsgBox`, `Format`, `CStr`, `vbCrLf`, ...) live in the
`vba` library, grouped into modules such as `Interaction` and `Strings`.

A type name that exists in several hosts (`Application`, `Range`, `Font`, ...)
resolves to the Excel one first; pass a library to pick another
(`vba.get_type("Application", "word")`).

## Finding something

- Don't know which type owns a member? Check `reference/members.json` - it maps
  every member name to the types that define it.
- Want the full catalog? See `reference/index.json` - all libraries and types.
- Know the type name? Open `reference/<library>/md/<TypeName>.md`.
- Browsing one library? Start at `reference/<library>/md/_index.md`.
- A global function (e.g. `MsgBox`)? It's in a module under `reference/vba/` -
  `MsgBox` is in `reference/vba/md/Interaction.md`.
- A constant's value (e.g. `xlCSV`)? See the enum file, e.g.
  `reference/excel/md/XlFileFormat.md`.
- Want one file instead of a folder tree? See `reference/consolidated/` below.

## Consolidated exports

`reference/consolidated/` holds the same data folded into one set of files per
application - Excel, PowerPoint, Word, Access, and `shared` for the libraries all
four have in common. Each set is three pairs of files:

| File                      | Contents                                          |
| ------------------------- | ------------------------------------------------- |
| `<app>.json` / `.md`      | every type, with methods, events and parameter docs |
| `<app>_constants.json` / `.md` / `.csv`  | every enumeration and module constant, with values |
| `<app>_properties.json` / `.md` / `.csv` | every property of every object, with type and access |

The two CSVs are flat tables for importing into a spreadsheet. Properties, as
`Object,Property,Property split,Type,Access`:

```
Application,ActiveCell,Active Cell,Range,R_O
Worksheet,UsedRange,Used Range,Range,R_O
Worksheet,Name,Name,String,V
```

`Property split` is the same name split at capitals, for reading rather than
calling. `Access` is `R_O` read-only, `V` settable, `W_O` write-only.

Constants, as `Owner,Kind,Constant,Value,Description`:

```
XlFileFormat,Enumeration,xlCSV,6,CSV
XlFileFormat,Enumeration,xlWorkbookDefault,51,Workbook default
Constants,Module,vbCrLf,Chr(13) & Chr(10),
```

`Value` is written as a VB6 literal, so it drops straight into generated code:
bare numbers, quoted strings, and `Chr()` for the handful of constants whose
value is a control character. 26,543 property rows and 12,995 constant rows
across the ten files.

So the whole Word object model is one 3.6 MB JSON file or one 1.8 MB Markdown
file; every Excel constant is a 175 KB Markdown file. Nothing here is new data -
it is the per-type files concatenated, for grep, download, or feeding to a model.
Start at [`reference/consolidated/_index.md`](reference/consolidated/_index.md).

## Regenerating

Requires Windows with the relevant Office applications installed and `pywin32`:

```powershell
.venv\Scripts\python.exe scrape_excel_object_model.py
```

Flags: `--no-enrich` (signatures only, skip Microsoft Learn text),
`--refresh-docs` (force re-download of the documentation corpus), and
`--only word,powerpoint` (rebuild just those libraries; the master indexes and
consolidated exports still cover everything else).

The consolidated exports are rebuilt at the end of every run. To rebuild only
them - no Office or `pywin32` needed, just the generated JSON:

```powershell
python consolidate_reference.py
```

## For AI agents

See [agentic_llm_primer.md](reference/agentic_llm_primer.md) for the JSON schema and
guidance on grounding VBA code against this reference.

## Python library

The same data is exposed as an installable, typed Python package, `vba_reference`.
The JSON is bundled into the wheel, so an installed copy is self-contained; in this
repo it reads the generated folders directly.

```powershell
pip install -e .          # from this repo (editable)
# or: pip install vba-reference
```

```python
import vba_reference as vba

vba.library_names()                          # ['excel', 'powerpoint', 'word', ...]
ws = vba.get_type("Worksheet")               # TypeDoc (case-insensitive)
print(ws.remarks)
protect = ws.member("Protect")               # Member
[(p.name, p.optional) for p in protect.parameters]

vba.get_type("Document", "word")              # disambiguate by library
vba.locate_type("Application")                # every host that defines it
vba.find_members("MsgBox")                    # -> [MemberRef(library='vba', type='Interaction', ...)]
vba.find_members("SaveAs")                    # every type that defines SaveAs
vba.get_constant("XlFileFormat", "xlCSV").value   # 6
vba.get_constant("WdSaveFormat", "wdFormatPDF").value  # 17
```

Command-line interface (`vba-ref` once installed, or `python -m vba_reference`):

```powershell
vba-ref libs                     # list libraries and type counts
vba-ref where MsgBox             # where a member/type is defined
vba-ref type Worksheet           # full type entry
vba-ref member Worksheet Protect # one member with parameter docs
```

## License and attribution

The code in this repository is MIT licensed - see [LICENSE](LICENSE).

The generated data is two things with two origins. Type names, member
signatures, parameter lists, property access modes and enumeration values are
introspected from the COM type libraries themselves. The prose - descriptions,
remarks and code examples - comes from
[MicrosoftDocs/VBA-Docs](https://github.com/MicrosoftDocs/VBA-Docs), published
by Microsoft Corporation under
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) with its code samples
under the MIT License. It is redistributed here under CC BY 4.0 with
attribution to Microsoft.

This project is not affiliated with or endorsed by Microsoft.

