pyOpenVBA 5.2.4__tar.gz → 6.1.0__tar.gz

{pyopenvba-5.2.4 → pyopenvba-6.1.0}/.gitignore

@@ -36,6 +36,9 @@ Thumbs.db
 tests/fixtures/*.xlsm
 tests/fixtures/*.xls
 
+# Workbooks the measuring scripts build to ask live Office a question
+tests/fixtures/mlang/_scratch/
+
 # Manually-generated Excel verification set (rebuilt by
 # scripts/build_excel_verification_set.py)
 tests/live_excel_testing/_excel_verify/

{pyopenvba-5.2.4 → pyopenvba-6.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyOpenVBA
-Version: 5.2.4
+Version: 6.1.0
 Summary: Read and write VBA macros and Excel Power Query in pure Python, no dependencies.
 Project-URL: Homepage, https://github.com/WilliamSmithEdward/pyOpenVBA
 Project-URL: Repository, https://github.com/WilliamSmithEdward/pyOpenVBA
@@ -140,6 +140,29 @@ pip install -e ".[dev]"
 The four host classes share the same module API: `module_names()`,
 `get_module()`, `set_module()`, `save()`.
 
+They also share `references()`, `add_reference()` and `remove_reference()`.
+These edit the VBA project's library references, as in Tools > References:
+
+```python
+with ExcelFile("workbook.xlsm") as wb:
+    wb.add_reference("Word")  # Excel, Word, PowerPoint and Access presets
+    wb.add_reference("Scripting", "420B2830-E718-11CF-893D-00A0C9054228",
+                     path="C:/Windows/System32/scrrun.dll")
+    for reference in wb.references():
+        print(reference.name, reference.guid, reference.version)
+    wb.remove_reference("Word")  # also accepts a GUID; returns whether removed
+    wb.save()
+```
+
+Adding an existing GUID or removing an absent reference is a no-op.
+The existing Access `drop_reference()` spelling remains available and raises
+if the reference is absent. VBA and the file's own host library are implicit;
+they are not listed or added. MSForms cannot be removed while UserForms exist.
+Removing a library does not rewrite code that names its types. Library paths
+are resolution hints; adding a reference does not install the library or add
+its implementation to the headless runtime. Use these methods to persist edits,
+rather than mutating `VBAProject.references` directly.
+
 ### Excel
 
 ```python
@@ -504,6 +527,341 @@ What the format is, and how each rule was measured, is in
 
 ---
 
+## Running the macros
+
+Reading and writing VBA is one thing; this runs it. `ExcelApplication`
+is an Excel instance in memory, with a VBA interpreter attached: load a
+workbook, execute a macro, look at what it did, write the file back.
+
+```python
+from pyopenvba.apps.excel import ExcelApplication
+
+app = ExcelApplication.open("report.xlsm")   # sheets, names, queries, macros
+app.run("BuildReport")
+print(app.describe())                        # a readable dump of the grid
+app.save("report_out.xlsm")
+```
+
+State can also be made up from nothing, with no file at all:
+
+```python
+app = ExcelApplication()
+app.add_workbook()
+app.add_module('Sub Main()\n    Range("A1").Value = 42\nEnd Sub\n', name="Module1")
+app.run("Main")
+app.sheet(1).value("A1")          # 42
+app.evaluate('Range("A1").Value * 2')   # 84
+```
+
+Failures are three separate exceptions, because they mean different
+things: `VBACompileError` for VBA that does not compile,
+`VBARuntimeError` for an error VBA itself would raise, carrying the
+number `Err` would hold, and `VBAUnsupportedError` for real VBA that
+pyOpenVBA does not implement. The third is never trappable by
+`On Error`: a gap here must not be swallowed and reported as a result.
+
+Formulas are calculated, not just carried: write one from a macro and
+read the answer back.
+
+```python
+app.add_module('''
+Sub Total()
+    Range("A1:A3").Value = 10
+    Range("B1").Formula = "=SUM(A1:A3)"
+End Sub
+''', name="Module1")
+app.run("Total")
+app.sheet(1).value("B1")          # 30.0
+```
+
+About a hundred worksheet functions are implemented; anything else
+Excel has says so by name rather than quietly answering `#NAME?`.
+
+Power Query is evaluated too. Refreshing a query works out its M and
+writes the rows to the sheet it loads to, so the table, its queryTable
+and the saved file all follow:
+
+```python
+app = ExcelApplication.open("sales.xlsx")
+app.refresh_query("Summary")      # the rows, headers first
+app.save("sales_out.xlsx")
+```
+
+Queries can name each other, `Excel.CurrentWorkbook()` reads the
+workbook's own tables and named ranges, and a source this cannot reach
+without a network or a driver reports itself rather than guessing.
+
+Word and PowerPoint run their macros too, each with its own object
+model:
+
+```python
+from pyopenvba.apps.word import WordApplication
+from pyopenvba.apps.powerpoint import PowerPointApplication
+
+doc = WordApplication.open("report.docm")
+doc.run("Relabel")
+doc.save("report_out.docm")
+
+deck = PowerPointApplication.open("deck.pptm")
+deck.run("Rebuild")
+deck.slide(1).shapes()            # what is on the first slide
+deck.save("deck_out.pptm")
+```
+
+Shapes are read and written on all three surfaces: adding, moving,
+resizing, renaming, retyping and deleting, with the macro a click runs
+attached or removed. In Excel that is `Shape.OnAction`, form-control
+buttons included; in PowerPoint it is
+`ActionSettings(ppMouseClick).Run`; Word has no macro on a shape and
+says so rather than pretending.
+
+```python
+app.add_module('''
+Sub Draw()
+    Dim sh As Object
+    Set sh = ActiveSheet.Shapes.AddFormControl(0, 100, 50, 90, 30)
+    sh.Name = "Go"
+    sh.OnAction = "Refresh"
+    sh.TextFrame.Characters.Text = "Refresh"
+End Sub
+''', name="Module1")
+app.run("Draw")
+app.save("with_button.xlsm")      # Excel opens it as a button
+```
+
+The same worksheet shapes can be edited directly from Python:
+
+```python
+app = ExcelApplication.open("report.xlsm", with_vba=False)
+sheet = app.sheet(1)
+sheet.add_button(name="Refresh", left=100, top=50, width=90, height=30,
+                 text="Refresh", macro="RefreshReport")
+sheet.update_shape("Refresh", left=120, text="Refresh report")
+print(sheet.shape("Refresh").control)  # control details
+sheet.update_shape("Refresh", macro="")  # unlink its macro
+sheet.remove_shape("Refresh")
+app.save("report_out.xlsm")
+```
+
+`Range.Formula` and `Range.FormulaR1C1` support scalar and array writes, with
+shared bounds, error and merge handling. `FormulaR1C1` converts relative,
+absolute and mixed references. Both properties return scalar or
+two-dimensional array results, including requested trailing blank cells.
+References survive save/reopen as ordinary A1 formulas. Array writes support
+custom lower bounds, single-axis expansion, mixed values and formulas, and
+Excel's `#N/A` filling for uncovered cells.
+
+VBA `Range.Find`, `FindNext` and `FindPrevious` support single-area searches
+over formula text or displayed values, with whole/partial matching,
+wildcards, case sensitivity, traversal order and wraparound. Whole-sheet
+searches keep empty cells sparse. Multi-area, comment and format searches,
+and `MatchByte=True`, remain unsupported.
+
+One `ExcelApplication` can hold multiple workbooks. Workbook handles let Python
+callers select and save a particular book without depending on the active book:
+
+```python
+source_book = app.add_workbook()
+source = app.sheet(1, workbook=source_book)
+source.set_value("A1", 10)
+destination_book = app.open_workbook("destination.xlsx")
+destination = app.sheet(1, workbook=destination_book)
+source.copy_range("A1:B5", destination, "D2", name_conflict="rename")
+copied_sheet = source.copy(after=destination)  # omit before/after for a new book
+copied_sheet.move(before=destination)
+app.save("destination.xlsx", workbook=destination_book)
+```
+
+VBA supports `Workbooks.Add`, `Open`, `Activate`, `Close`, and `Worksheet.Copy`
+before/after a sheet in another open workbook. Copies preserve modeled cells,
+merges and relevant names. Range copies import names used by formulas, including
+aliases. `name_conflict="reuse"` (the default) uses the destination definition,
+matching unattended Excel; `"rename"` imports names with unused `_2`, `_3`, etc.
+suffixes and rewrites copied formulas; `"error"` rejects collisions before making
+changes. Names referencing the source sheet retain their cell addresses on the
+destination sheet; they do not shift with the paste offset. External-link range
+copies, relative name imports, sheet-copy name conflicts, drawings,
+controls and advanced worksheet metadata are explicitly unsupported. Opening
+additional workbooks does not create independent VBA execution projects.
+
+VBA `Worksheet.Move Before:=...` / `After:=...` uses the same anchors as Copy.
+Omitting both moves the sheet into a new workbook. Cross-book moves invalidate
+held VBA worksheet, range and local-name objects (error 424), matching Excel;
+reacquire them from the destination. Python `move` returns the new sheet view.
+Same-book reordering preserves object identity. Moving the last sheet to an existing
+workbook closes the empty source; moving its only sheet to a new workbook raises
+1004. Moves that need external links or unsupported sheet-content transfer fail
+before changing either workbook.
+
+Named ranges support create/read/update/delete through VBA `Names` collections
+and shared Python APIs. `app` operates on workbook names; `app.sheet(...)`
+operates on worksheet-local names. Snapshots include scope, reference, visibility
+and comments; renaming updates dependent formulas.
+
+```python
+app.add_named_range("Revenue", "=Sheet1!$B$2:$B$10", comment="Sales totals")
+app.sheet(1).add_named_range("Revenue", "=$C$2:$C$10", visible=False)
+print(app.named_ranges())                  # workbook and local definitions
+print(app.named_range("Revenue"))         # workbook definition
+app.update_named_range("Revenue", new_name="Sales", refers_to="=Sheet1!$B$2:$B$20")
+app.sheet(1).update_named_range("Revenue", comment="Local override")
+app.remove_named_range("Sales")
+app.sheet(1).remove_named_range("Revenue")
+app.save("named_ranges.xlsm")
+```
+
+Whole-row/column `Insert` and `Delete` update cell references, including absolute
+and cross-sheet references, range boundaries and defined names, and move row
+heights and column widths. Deleted targets become `#REF!`. Partial-cell reference
+updates and full formatting/metadata movement remain incomplete; sheets with
+merges or shapes are explicitly unsupported.
+
+`Range.Copy Destination:=...` handles overlapping copies, blank source cells,
+repeated destination blocks and relative formula shifts, and copies each
+cell's format. Merged-cell and multi-area copies, large destinations and
+clipboard pastes remain incomplete.
+
+`Range.Merge`, `UnMerge`, `MergeCells` and single-cell `MergeArea` support
+merged-region editing and save/reopen. Ordinary overlapping merges expand
+to include the existing regions; `Across=True` merges each row separately.
+Excel's first nonempty value or formula is retained, and partial clears raise
+error 1004. Multi-area merges, across merges over existing multi-row regions,
+and full merge-formatting parity remain outside the measured support.
+
+Cell formats read and write the way Excel does: `Font`, `Interior`,
+`Borders`, `BorderAround`, the alignment and protection properties,
+`NumberFormat` and `ClearFormats`. A read over several cells answers Null
+when they differ, theme colours take their tints the way Excel computes
+them, and a border between two cells is stored and read the way Excel
+shares it. A workbook Excel formatted reads back exactly as Excel reads
+it, and a save adds only the stylesheet entries the file lacks, spelled
+as Excel spells them. Formatting whole rows, whole columns or the whole
+sheet keeps the row, column and sheet formats Excel keeps, with the
+cells Excel makes where they cross, and saves them as Excel does. Named
+cell styles and conditional formats are not implemented yet.
+
+Row heights, column widths and hidden rows and columns behave as they do
+in Excel on a 96-DPI display, the one the model emulates: `RowHeight = 20`
+reads back 20, draws 19.5pt tall and saves as Excel saves it; `Hidden`,
+`UseStandardHeight`, `UseStandardWidth`, `Height`, `Width`, `Left`, `Top`
+and a sheet's standard sizes follow, and all of it is read from and saved
+to the file. A row grows or shrinks with the fonts its cells, its own
+format and its columns show, as Excel's does, from heights measured in
+live Excel for the common Office and Windows fonts; a row
+whose height rests on an unmeasured font, a mix of fonts, or wrapped
+text reports itself unsupported, and column `AutoFit` measures no text
+yet.
+
+`shapes()` and `shape(name)` return detached snapshots, including each
+control's linked cell, list range and value. Use `update_shape` to make
+an edit. `add_shape` creates a measured AutoShape and `add_textbox`
+creates a horizontal text box; coordinates and sizes are nonnegative
+points. `update_control(name, linked_cell="$H$1", list_range="$J$1:$J$3")`
+edits saved form-control bindings (list ranges apply to dropdowns and
+list boxes); use an empty string to disconnect a binding. References
+may be A1 cells/ranges or workbook and worksheet-local names in this
+workbook. These binding edits leave cell
+values untouched. `set_control_value(name, 1)` checks a checkbox; use
+`-4146` or `0` to uncheck it and `2` for mixed. Changed states write
+True, False or #N/A to the linked cell. Direct cell writes and calculated
+formulas also update linked checkboxes, including links across sheets.
+VBA exposes the same state through `Shape.ControlFormat.Value`; its
+`LinkedCell` setter follows Excel's rebinding behavior.
+For single-selection dropdowns and list boxes backed by ranges,
+`set_control_value(name, 2)` selects the second row; zero clears the
+selection. These controls synchronize numeric indexes with linked cells.
+VBA also supports `ControlFormat.ListFillRange` and `ListCount`.
+Changing the source range clamps the selection or restores it from the
+linked cell without overwriting that cell.
+
+Named bindings support aliases, local-name precedence and changes to a
+name's target. A linked name covering a rectangle writes its top-left
+cell. Missing names remain saved; they provide no linked target and an
+empty list source. Shrinking or deleting a named list source adjusts its
+selection. Named `CHOOSE`, `IF`, `INDEX`, `OFFSET` and `INDIRECT` formulas support dynamic
+targets, including cell-driven list sizes and addresses. `INDEX` supports
+single-area sources and zero indices selecting whole rows or columns.
+Invalid `INDEX` and `OFFSET` ranges provide empty sources.
+`CHOOSE` and `IF` resolve only the selected branch; selected scalar values
+or errors provide empty sources, and cell-driven conditions redirect bindings.
+`INDIRECT` accepts A1 and absolute R1C1 addresses, including quoted sheet names.
+Other reference formulas, multi-area `INDEX`, relative R1C1 `INDIRECT`,
+cyclic aliases and external workbook bindings remain explicitly unsupported.
+
+Inline lists support `control_items`, `add_control_item`,
+`update_control_item`, `remove_control_item`, and `clear_control_items`.
+Their VBA equivalents are `List(index)`, `AddItem`, `RemoveItem`, and
+`RemoveAllItems`. Item edits adjust selection indexes without changing
+the linked cell. Use `set_control_selection_mode(name, 2)` and
+`set_control_selection(name, [1, 3])` for multi-selection; mode 3 is
+extended selection. Snapshots expose `items`, `selection_mode`, and
+`selected_indices`. VBA supports `ControlFormat.MultiSelect` and
+`Shape.DrawingObject.Selected(index)`. A multi-selection list's scalar
+`Value` read raises Excel error 1004.
+
+`set_control_items(name, ["one", "two"])` replaces the entire list after
+validating every string. VBA supports whole-list `ControlFormat.List`
+reads and assignments: reads return a detached one-based Variant array,
+or Null when empty. VBA assignments follow Excel's error behavior,
+including retaining a successfully written prefix when a later array
+element is invalid. Python replacement validates before making changes.
+
+As in Excel, adding or replacing an item in a range-backed list
+disconnects the source and starts a new inline list; it does not edit
+the source cells. Clearing disconnects it too, while removing individual
+range-backed items raises an error. These conversions reset selection
+and can write zero to the linked cell. Edit the source cells directly
+when the control should remain range-backed.
+Spinners and scroll bars support `set_control_value` and VBA
+`ControlFormat.Value`, `LinkedCell`, `Min`, `Max` and `SmallChange`.
+Scroll bars also expose `LargeChange`; Excel rejects that member on
+spinners. Direct values must fit the bounds. Numeric linked-cell values
+clamp the control while preserving the cell, text preserves its state,
+and empty/error cells reset it to its minimum. Snapshots retain numeric
+bounds and increments, and saved controls preserve their type and state.
+Excel can reconcile a saved control with its linked cell when opening
+the file; its stored value alone does not determine the displayed state.
+`add_form_control(control_type, name="Choices", left=12, top=20)` creates
+buttons (0), checkboxes (1), dropdowns (2), group boxes (4), labels (5),
+list boxes (6), option buttons (7), scroll bars (8), and spinners (9).
+It uses the same geometry, caption, macro and name arguments as `add_button`.
+Multi/extended lists retain selections when switching between those two
+modes. Changing their source keeps only selected indexes that fit the new
+range; switching to single selection clears them. VBA rebinding writes the
+stored scalar index when the destination cell differs, even though a
+multi-selection list does not expose a scalar `Value` getter.
+Radio groups support off (`-4146` or `0`) and on (`1`) through
+`set_control_value` and VBA `ControlFormat.Value`. Selecting a button clears
+its peers and writes its one-based group index to the shared linked cell;
+cell edits select that index without rewriting the cell. Text preserves
+selection; empty/error cells and out-of-range indexes clear it. Group
+membership stays stable during ordinary movement and is reconstructed from
+group-box geometry on reopening, matching Excel. Non-overlapping boxes
+support interleaved creation and regrouping, including a separate unboxed
+group. Splitting preserves selected buttons; merging keeps the first
+selected button in control order. Adding a box to split interleaved radios
+preserves the linked cell's previous index. Radios can also be created
+inside existing overlapping or nested boxes: earlier boxes win partial
+overlaps, while a strictly nested inner box wins regardless of creation
+order. Adding and deleting those boxes transfers group links and selections
+with Excel's measured behavior. A late nested box leaves the link with its
+surviving outer group. An identical box can transfer the original link to
+an unlinked unboxed group; an already linked unboxed group keeps its link.
+Deleting a radio leaves the linked cell
+unchanged; deleting the leader retains the link for a boxed group and
+clears it for an unboxed group.
+Creating pictures, charts and shape groups remains tracked work.
+Removing a control cleans up its worksheet record, properties
+part, relationship and VML while preserving other controls and notes.
+
+Every answer the interpreter, the calculation engine and the three
+object models give was measured in the application itself rather than
+assumed, and a file nobody changed saves back byte for byte. What is
+implemented, what is not, and how it was measured is in
+[docs/vba_runtime.md](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/docs/vba_runtime.md).
+
+---
+
 ## Supported formats
 
 ### Excel
@@ -535,6 +893,39 @@ outside the project, so it is read and written in every package above.
 | `.potm`   | Macro-enabled template       |  yes |  yes  |    no      |
 | `.ppt`    | Legacy (PowerPoint 97-2003)  |  yes |  yes  |    no      |
 
+### Files with no VBA project
+
+A file saved before its first macro has no VBA project: no
+`vbaProject.bin` in a `.xlsm`, `.docm` or `.pptm`, and no project storage
+in a binary file. That is its normal shape, and it opens like any other.
+`has_vba_project()` says False, listing reads such as `module_names()`,
+`vba_modules()`, `forms()` and `references()` answer empty, and a read or
+write that needs the project raises `NoVBAProjectError`, a kind of
+`VBAProjectError`:
+
+```python
+with ExcelFile("book.xlsm") as wb:
+    if wb.has_vba_project():
+        print(wb.module_names())
+```
+
+`add_vba_project()` gives a `.xlsm`, `.docm` or `.pptm` a project, the
+one its application makes for a first macro. In Excel that is a
+document module for the workbook and one for each sheet, named as Excel
+names them; in Word it is `ThisDocument`; in PowerPoint it is empty. Add
+modules to it and save:
+
+```python
+with ExcelFile("book.xlsm") as wb:
+    if not wb.has_vba_project():
+        wb.add_vba_project().add_module("Module1", "Public Sub Hello()\r\nEnd Sub\r\n")
+    wb.save()
+```
+
+A project its application would not write is not written here either:
+Excel writes only the code names for one with no code in it, and
+PowerPoint nothing for one with no module.
+
 ### Access
 
 | Extension | What it is                   | Read | Write | create_new |
@@ -581,8 +972,19 @@ the file still asks for the original password in the VBE.
 
 ### Digitally signed projects
 
-Any change to the macros invalidates a digital signature. On mutation the
-library drops the stale signature streams and emits a `UserWarning`:
+Any change to the macros invalidates a digital signature. Excel, Word and
+PowerPoint keep the signature of a `.xlsm`, `.docm` or `.pptm` in parts
+beside `vbaProject.bin`, and `vba_signature()` reads it from there:
+
+```python
+info = wb.vba_signature()
+info.present, info.kinds, info.parts
+# (True, ['v3', 'agile', 'legacy'], ['xl/vbaProjectSignatureV3.bin', ...])
+```
+
+On a save that changes the project, the library takes the signature out
+as the applications do: the parts, their relationships and their entries
+in `[Content_Types].xml`. It then emits a `UserWarning`:
 
 ```python
 import warnings
@@ -591,6 +993,11 @@ warnings.filterwarnings("error", category=UserWarning)   # treat as fatal
 wb.save(allow_invalidate_signature=True)                 # or accept it
 ```
 
+A save that changes nothing keeps the signature. A signature in a binary
+`.xls`, `.doc` or `.ppt` file is not looked for: there it lives in the
+file's property sets or a string table, and no signed binary file has
+been measured.
+
 ---
 
 ## Out of scope
@@ -642,6 +1049,7 @@ For more:
 - [docs/power_query.md](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/docs/power_query.md): how Excel stores Power Query, and how each rule was measured.
 - [docs/ms-ovba-implementation-guide_v2.md](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/docs/ms-ovba-implementation-guide_v2.md): a language-agnostic guide to re-implementing MS-OVBA.
 - [docs/roadmap.md](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/docs/roadmap.md): per-feature status.
+- [docs/host_completeness.md](docs/host_completeness.md): whole-host completion criteria and the Excel coverage audit; Excel, then Word, then PowerPoint.
 
 ---
 
@@ -677,6 +1085,14 @@ PyPI when a `v*.*.*` tag is pushed.
 
 ---
 
+## Built with this
+
+[xlide-mcp](https://github.com/WilliamSmithEdward/xlide_mcp)
+is an MCP server built on this. It gives an AI agent the VBA, the
+UserForms and the Power Query inside an Office file, so a model can read
+a macro, rewrite it and save it back without anyone exporting modules by
+hand. Every container this library opens is one that server can reach.
+
 ## License
 
 [MIT](https://github.com/WilliamSmithEdward/pyOpenVBA/blob/main/LICENSE.md).