pyOpenVBA 5.2.4__tar.gz → 6.0.0__tar.gz

{pyopenvba-5.2.4 → pyopenvba-6.0.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.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyOpenVBA
-Version: 5.2.4
+Version: 6.0.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
@@ -504,6 +504,116 @@ 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
+```
+
+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

{pyopenvba-5.2.4 → pyopenvba-6.0.0}/README.md

@@ -467,6 +467,116 @@ 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
+```
+
+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

{pyopenvba-5.2.4 → pyopenvba-6.0.0}/docs/roadmap.md

@@ -42,6 +42,12 @@ done and what is not.
   `form.add_control()`, `form.add_page()`, `control.set_property()`,
   `python -m pyopenvba forms`).  Writing is lossless: an unedited form
   saves back byte for byte.
+- **Running the VBA**: a VBA interpreter and an in-memory Excel object
+  model (`pyopenvba.apps.excel.ExcelApplication`), so a macro can be
+  executed against a workbook loaded from a file or made up from
+  nothing, and the result written back out. Every expression answer is
+  measured against live Excel; see
+  [`vba_runtime.md`](vba_runtime.md).
 - Pure Python 3.10+, zero runtime dependencies.
 
 ### Unsupported (today)
@@ -85,7 +91,23 @@ done and what is not.
 
 ## Near-term roadmap (in priority order)
 
-_No open near-term items: all in-scope gates are PASS. See the "Out of scope" section below for explicitly deferred work._
+The MS-OVBA gates are all PASS. What is open belongs to the newer
+interpreter work, tracked in [`vba_runtime.md`](vba_runtime.md):
+
+1. An Access object model with its own measured probe file, following
+   the shape `apps/excel`, `apps/word` and `apps/powerpoint` set.
+2. More of the M library, which is 224 of the 859 names `#shared`
+   reports. The gaps are named rather than answered wrongly, so what to
+   add next is whatever a real query asks for.
+3. `WithEvents` and the document-module event handlers, so a
+   `Worksheet_Change` fires when a macro writes a cell.
+4. Array formulas that spill, which the calculation engine stops short
+   of: an array result shows its first element, as it did before
+   dynamic arrays.
+5. The shapes this reads but does not make: a group, a picture and a
+   chart. All three are read, and their members and parts are reachable;
+   `ShapeRange.Group` and `AddPicture` report themselves rather than
+   writing a part they cannot yet write.
 
 ## Out of scope (no current plans)
 

pyopenvba-6.0.0/docs/vba_runtime.md

@@ -0,0 +1,374 @@
+# Running VBA against an in-memory Office application
+
+pyOpenVBA reads and writes the VBA in an Office file.  This part runs
+it: a VBA interpreter, and an object model with real state behind it, so
+a macro can be executed and its effect inspected without Office.
+
+Three hosts: `ExcelApplication`, `WordApplication` and
+`PowerPointApplication`, each with its own object model and its own
+measured probe file.
+
+```python
+from pyopenvba.apps.excel import ExcelApplication
+
+app = ExcelApplication.open("report.xlsm")   # sheets, names, queries, macros
+app.run("BuildReport")                       # evaluate the VBA
+print(app.describe())                        # what is in there now
+app.save("report_out.xlsm")                  # write it back
+```
+
+or with nothing to start from:
+
+```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
+```
+
+Word and PowerPoint work the same way:
+
+```python
+from pyopenvba.apps.word import WordApplication
+
+app = WordApplication.open("report.docm")
+app.run("Relabel")
+print(app.describe())
+app.save("report_out.docm")
+```
+
+```python
+from pyopenvba.apps.powerpoint import PowerPointApplication
+
+app = PowerPointApplication.open("deck.pptm")
+app.run("Rebuild")
+app.slide(1).shapes()            # what is on the first slide
+app.save("deck_out.pptm")
+```
+
+## The three ways it can fail
+
+They are separate exception types because they mean different things to
+whoever is reading the output.
+
+| Exception | Means | Trappable by `On Error`? |
+| --- | --- | --- |
+| `VBACompileError` | The source is not valid VBA. Raised when the module is loaded, as the VBA compiler does. | No, as in VBA |
+| `VBARuntimeError` | An error VBA itself would raise, carrying the number and description `Err` would hold. | Yes |
+| `VBAUnsupportedError` | Real VBA that pyOpenVBA does not implement. | **No, deliberately** |
+
+The third one is the point of the separation.  A statement, a function
+or an object member that Excel would have run and this cannot is a gap
+in pyOpenVBA, not a mistake by whoever wrote the macro, and reporting it
+as either of the other two would say otherwise.
+
+It is not trappable on purpose.  If `On Error Resume Next` could swallow
+it, a script would carry on past a step that never happened and report a
+result computed from a state that never existed.
+
+An unknown object member is told apart by the type library rather than
+guessed: `Worksheet.PivotTables` is a real member, so reaching for it is
+`VBAUnsupportedError`; `Worksheet.Pivottabel` is not, so it is VBA's own
+run-time error 438.  The inventory is generated by
+`scripts/build_object_inventory.py` and committed as
+`interpreter/_inventory_data.py`.
+
+## How the semantics were settled
+
+Every answer the interpreter gives to an expression was measured in live
+Excel rather than reasoned about.  `tests/fixtures/vba_semantics/probes.txt`
+holds the expressions; `scripts/measure_vba_semantics.py` runs them
+through Excel via pyvbaharness and records what came back;
+`tests/test_vba_semantics.py` holds the interpreter to that file, with no
+Office needed.
+
+That is how the model ended up with things a plausible implementation
+would have got wrong:
+
+- `30000 + 30000` overflows, because both operands are Integers and VBA
+  does not widen the result.  Integer width is carried on every value.
+- `&HFFFF` is -1 and `&HFFFFFFFF` is -1, but the first is an Integer and
+  the second a Long: the width comes from how many digits were written.
+- `1 < "1"` is False.  A number against a string reads the string as a
+  number rather than sorting numbers before strings.
+- `Len(n)` is 4 for a Long holding 12345 and 5 for a Variant holding the
+  same number: `Len` is a size in bytes for anything that is not a
+  String.
+- A Double prints in full while its digits fit in 15 character
+  positions and in exponent form otherwise, so `999999999999999` is
+  written out and `1E+15` is not, and `0.000000000000001` is written out
+  and `1E-16` is not.
+- `Right("abc", 5)` is `"abc"`, `Hex(-1)` is `FFFF` for an Integer, and
+  `Round(-0.5)` prints `-0`.
+
+The calculation engine was settled the same way, in
+`tests/fixtures/formula/probes.txt`: each formula was written into a
+cell in live Excel and what the cell showed was recorded.  That sweep
+is what settled these:
+
+- `2^3^2` is 64, because `^` chains to the left, and `-2^2` is 4,
+  because a minus sign binds tighter than the power.
+- `0.1+0.2=0.3` is TRUE: a comparison is settled on the fifteen
+  significant digits a cell would show, not on the bits.
+- ROUND rounds half away from zero and MOD takes the sign of its
+  divisor, neither of which matches the VBA function of the same name.
+- A range contributes only its numbers to SUM while a literal converts,
+  so `SUM(A1,"2")` is three and a range holding "2" adds nothing; COUNT
+  walks past an error that SUM would stop at.
+- `=A1` on an empty cell is 0, and `DATE(...)` brings a date format
+  with it while `EOMONTH(...)` leaves the serial number showing.
+
+The same method covers the Excel object model:
+`tests/fixtures/excel_model/probes.txt` and `tests/test_excel_model.py`,
+measured with `python scripts/measure_vba_semantics.py excel`.  That
+sweep is what settled these:
+
+- A cell keeps every number as a Double, and reads a string the way it
+  reads typing: `"5"` becomes the number, `"1/2/2020"` becomes a Date,
+  and `""` leaves the cell Empty.
+- `Range("A1:B2").Value = Array(7, 8)` puts 7 in A2 as well as A1: a
+  flat array is one row, repeated down.
+- `End` looks at the neighbour, so `End(xlDown)` from a lone A1 is
+  A1048576 rather than A1.
+- `Range("ZZ")` is error 1004, because a column on its own needs the
+  colon.
+
+Power Query is measured by the same method, through the engine that
+ships with Excel: `scripts/measure_m.py` builds a workbook whose query
+evaluates every expression in `tests/fixtures/mlang/probes.txt`,
+refreshes it, and records what came back, 25 to a refresh.  All 269 are
+replayed by `tests/test_mlang_semantics.py`.  That sweep settled these:
+
+- `Number.Round(2.5)` is 2 and `Number.Round(3.5)` is 4: M rounds half
+  to even, where Excel's own ROUND rounds away from zero.  It writes
+  the answer as `2.0`, keeping the decimal places the number arrived
+  with, so `Number.Round(2.345, 2)` writes `2.340`.
+- `#date(2021, 3, 4) + #duration(0, 12, 0, 0)` is still a date, not a
+  datetime: the day the moment lands on.
+- A duration writes its day count only when it has one, so three hours
+  is `03:00:00` and a day and two hours is `1.02:00:00`.
+- `10/0` is `∞`, `0/0` is NaN and `Number.Sqrt(-1)` is NaN, none of
+  which is an error.
+- A row whose test comes out null is dropped by `Table.SelectRows`, the
+  same as a row that tested false.
+- `{"0".."9"}` is the ten digits: a range can be over characters.
+- M has `Uri.EscapeDataString` and no `Uri.UnescapeDataString`, which is
+  why `#shared` is asked for the list of names rather than assuming the
+  library is symmetric.
+
+Word and PowerPoint were measured the same way, into
+`tests/fixtures/word_model` and `tests/fixtures/powerpoint_model`, with
+`python scripts/measure_vba_semantics.py word` and `powerpoint`.  Their
+answers are not each other's, which is the reason for measuring each:
+
+- A missing shape raises -2147024809 in Excel and Word, and
+  -2147188160 in PowerPoint.  Neither is 1004.
+- Word places a shape from the page and reports it against the column
+  and the paragraph, so `AddShape(1, 10, 20, 100, 50)` comes back with
+  a Left of -62 and a Top of -52 against the default inch margins.
+- Word's names for its own shapes are not Excel's: a rounded rectangle
+  is "Rectangle: Rounded Corners", a can is a "Cylinder" and a text box
+  is "Text Box".  PowerPoint's are Excel's, every one of them.
+- A new shape's number comes from one counter per sheet, slide or
+  document, over every kind.  A rectangle and then an oval are
+  "Rectangle 1" and "Oval 2"; delete both and the next rectangle is
+  "Rectangle 3"; a new sheet or slide starts again at one.  The same
+  rule in all three hosts.
+- The preset geometry behind an msoShapeType is not guessable from its
+  name, and several presets belong to a shape other than the one they
+  sound like: 11 is `plus`, 12 is `pentagon`, and `star5` is 92.  The
+  whole table was read out of files Office saved, by
+  `python scripts/measure_shape_types.py`.
+- `Document.Shapes` is listed by z-order, which rises as shapes are
+  added; the runs in the file hold the newest first.
+- A Word range reads with its paragraph mark, an in-line shape is one
+  Chr(1) in the text, and a floating one is no character at all.
+- Assigning `Content.Text` takes the shapes with it.  Asked of Word, a
+  document with five floating shapes and one in-line had none of either
+  afterwards.
+- PowerPoint's slide is 960 by 540 points, its `Presentation.Saved` is
+  a Long where Word's `Document.Saved` is a Boolean, and
+  `ActionSettings(1).Action` stays at ppActionRunMacro once set even
+  before a macro is named.
+
+The shapes themselves were measured by having each application build
+one of every kind it can hold and say what it then reported about each:
+`python scripts/measure_shapes.py all`, kept in
+`tests/fixtures/shapes`.
+
+Three live gates ask what only Office can answer, behind
+`RUN_LIVE_EXCEL=1`, `RUN_LIVE_WORD=1` and `RUN_LIVE_POWERPOINT=1`: that
+the same macro leaves the same state behind on both sides, that a file
+written here opens with everything the model does not describe still in
+it, and that shapes drawn here are the shapes Office reads back.
+
+## What is implemented
+
+**The language.** Every statement form: the declarations, `If` in both
+shapes, `For`, `For Each`, `Do` in all four, `While`, `Select Case`,
+`With`, `Exit`, `GoTo` and labels, `On Error` with `Resume`, `ReDim`,
+`Erase`, the `Mid` statement, `Type` and `Enum`, class modules with
+`Property Get/Let/Set` and `Class_Initialize`, `ByRef` and `ByVal`,
+`Optional` with defaults, `ParamArray`, named arguments, `Static`
+locals, and conditional compilation.
+
+`On Error GoTo` does not unwind the stack: the handler runs where the
+error happened, so `Resume Next` hands control back to the statement
+after it even inside a loop, which is what a loop-and-skip macro
+depends on.
+
+**The runtime library.** The conversion, maths, string, date, array and
+information functions, `Format` (shared with the Access engine, which is
+the same function in Office), `MsgBox` and `InputBox`, and the financial
+functions that are closed forms.
+
+`MsgBox` does not block.  It records the message and answers from a
+queue the caller primed, so a macro that would have stopped for a prompt
+runs to the end and the prompt is visible afterwards.
+
+**Excel.** Application, Workbooks, Workbook, Sheets, Worksheet, Range
+with multiple areas, Font, Interior, Names, Queries, Shapes, and a
+short list of worksheet functions.  Cells hold values, formulas, number
+formats and a little formatting.
+
+**Word.** Application, Documents, Document, Range, Paragraphs,
+Paragraph, Shapes, InlineShapes, Shape, WrapFormat, TextFrame and
+TextRange.  The text is read and can be assigned; a document whose
+text nobody assigned and whose shapes nobody moved is written back byte
+for byte, so styles, headers and numbering survive a shape edit.
+
+**PowerPoint.** Application, Presentations, Presentation, PageSetup,
+Slides, Slide, Shapes, Shape, GroupItems, TextFrame, TextRange,
+ActionSettings and ActionSetting, with `ActiveWindow.View.Slide` to
+reach the slide in view.
+
+**Shapes, on all three.** Adding, reading, moving, resizing, renaming,
+retyping and deleting: `AddShape`, `AddTextbox`, `AddLine`, and
+`AddFormControl` in Excel.  The macro a click runs is `Shape.OnAction`
+in Excel and `ActionSettings(ppMouseClick).Run` in PowerPoint; Word has
+no such thing, and says so rather than pretending.
+
+An Excel form control is four parts of the workbook at once -- the
+hidden shape in the drawing, the sheet's own record of it, a part
+saying which control it is, and the VML Excel draws it from -- and its
+macro lives in two of them.  Making one and wiring it up writes all
+four, which is what lets a button a macro created open as a button.
+
+**Formulas are calculated.** `pyopenvba.formula` parses and evaluates
+them; the workbook keeps track of which cells are stale and what feeds
+what.  Calculation is on demand: reading a stale cell works it out, and
+working it out works out whatever it reads, so nothing is ordered up
+front and INDIRECT is no harder than a plain reference.  Writing a cell
+spoils whatever reads it, a volatile function is recomputed every time,
+a formula written to a block or copied has its relative references
+moved, a circular reference leaves a zero and is recorded, and manual
+calculation mode keeps the old value until something calls Calculate,
+which is what Excel shows until F9.
+
+About a hundred worksheet functions are implemented, chosen by what
+macros actually call: the aggregations and their -IF and -IFS forms, the
+lookups, the text and date families, the information tests, and the
+logical functions.  Anything else Excel has says so by name rather than
+answering `#NAME?`, which is reserved for a function Excel has not got
+either.
+
+**Power Query is evaluated.** `pyopenvba.mlang` is an M evaluator, so
+`WorkbookQuery.Refresh` works out the query's rows and writes them to
+the sheet it loads to; the table and its queryTable follow, and a save
+writes what the refresh produced. Bindings are lazy as M's are, one
+query can name another, and `Excel.CurrentWorkbook()` reads the tables
+and named ranges of the workbook being refreshed. A source that cannot
+be reached from a library with no network and no drivers -- a database,
+a web service, a folder somewhere else -- says so by name.
+
+```python
+app = ExcelApplication.open("sales.xlsx")
+app.refresh_query("Summary")      # rows, headers first
+app.save("sales_out.xlsx")
+```
+
+**Files.** A workbook is read from `.xlsx`, `.xlsm` or `.xlam`, a
+document from `.docx`, `.docm` or `.dotm`, and a presentation from
+`.pptx`, `.pptm` or `.potm`, each written back with only what changed
+rewritten: a sheet, a slide or a body nobody touched keeps its bytes,
+and an unchanged file saves byte for byte.  A workbook made from
+nothing is written from the template captured from a freshly
+Excel-authored file; Word and PowerPoint have no such template yet, so
+a document or a presentation is edited rather than created.
+
+## What is not
+
+- **Array formulas do not spill.** An array result lands in the one cell
+  that holds the formula and shows its first element, which is what
+  Excel did before dynamic arrays.  Implicit intersection is applied to
+  a multi-cell reference beside an operator, as Excel's `@` does.
+- **Power Query reaches nothing off the machine.** The language is
+  evaluated and a local source is read, but `Sql.Database`, `Web.Contents`,
+  `OData.Feed` and the rest of the connectors report themselves rather
+  than opening a connection. 224 of M's 859 library names are
+  implemented; the others are named as gaps, not answered wrongly.
+- **No events.** `WithEvents` sinks are not connected and `RaiseEvent`
+  says so.  A `Worksheet_Change` handler will not fire when a macro
+  writes a cell.
+- **Nothing outside the model.** File I/O, the file system verbs, the
+  registry, `Shell`, `SendKeys`, `CreateObject` and `Declare` into a DLL
+  all report themselves unsupported rather than reaching the real
+  machine.
+- **`.xlsb` cells.** The binary sheet part is not read; its VBA project
+  is readable through `ExcelFile` as before.  The same goes for the
+  legacy `.doc`, `.ppt` and `.xls`, whose text and shapes live in
+  binary streams this does not read.
+- **No document or presentation from nothing.** Word and PowerPoint
+  open a real file and edit it; only Excel has a template to write one
+  from.
+- **Grouping is not done here.** A group in a file is read, and its
+  members are reachable through `GroupItems`, but `ShapeRange.Group`
+  reports itself rather than making one.
+- **A picture or a chart is read, not made.** `AddPicture` says so;
+  the media and the chart parts a new one needs are not written.
+- A type-suffixed name is the same variable as the name without it, so
+  the implicit-typing trick where `a%` and `a$` are two variables is not
+  modelled.
+
+## Where the parts live
+
+| Module | What it is |
+| --- | --- |
+| `interpreter/_lex.py` | Tokenizer |
+| `interpreter/_preprocess.py` | `#If` resolved before parsing |
+| `interpreter/_parse.py` | Parser, producing `_ast.py` |
+| `interpreter/_values.py` | Variant semantics: conversions and operators |
+| `interpreter/_objects.py` | How VBA reaches an object and how one answers |
+| `interpreter/_intrinsics.py` | The VBA runtime library |
+| `interpreter/_runtime.py` | The interpreter itself |
+| `interpreter/_inventory.py` | Which members the real classes have |
+| `apps/excel/_model.py` | Excel's object model |
+| `apps/excel/_calc.py` | Which cells are stale, and what they come to |
+| `formula/_parse.py` | The formula grammar |
+| `formula/_engine.py` | Evaluating one formula against a grid |
+| `formula/_functions.py` | The worksheet functions |
+| `apps/excel/_io.py` | Reading and writing the workbook file |
+| `apps/excel/_bridge.py` | What a project sees when Excel is the host |
+| `apps/excel/_shapes.py` | A sheet's shapes, as a macro reaches them |
+| `apps/word/` | Word's object model, its bridge and its file |
+| `apps/powerpoint/` | PowerPoint's, the same three |
+| `shapes/_values.py` | What a shape is, in all three hosts' words |
+| `shapes/_drawingml.py` | The DrawingML the three of them share |
+| `shapes/_xlsx.py` | A worksheet's drawing layer and its controls |
+| `shapes/_pptx.py` | A slide's shape tree |
+| `shapes/_docx.py` | A document's drawings, floating and in line |
+| `apps/excel/_refresh.py` | A query evaluated and landed on a sheet |
+| `mlang/_parse.py` | The M grammar |
+| `mlang/_eval.py` | Evaluating M, lazily |
+| `mlang/_library.py` | The M library |
+| `mlang/_inventory.py` | Which names Power Query has, from `#shared` |
+
+## What comes next
+
+Access gets the same shape as the other three: an object model under
+`apps/`, a bridge, and a measured probe file.  The document-module
+events are the other open piece, so that writing a cell from a macro
+fires `Worksheet_Change`, and after that the parts of each host's model
+that no probe has reached yet -- Word's tables and headers,
+PowerPoint's slide masters, Excel's pivot tables.

{pyopenvba-5.2.4 → pyopenvba-6.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyOpenVBA"
-version = "5.2.4"
+version = "6.0.0"
 description = "Read and write VBA macros and Excel Power Query in pure Python, no dependencies."
 readme = "README.md"
 license = { text = "MIT" }
@@ -88,6 +88,7 @@ include = [
     "docs/architecture.md",
     "docs/power_query.md",
     "docs/roadmap.md",
+    "docs/vba_runtime.md",
     "docs/ms-ovba-implementation-guide_v2.md",
 ]