pyOfficeEditor 0.2.2__tar.gz → 0.3.0__tar.gz

{pyofficeeditor-0.2.2 → pyofficeeditor-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyOfficeEditor
-Version: 0.2.2
+Version: 0.3.0
 Summary: Edit the document surface of Excel, Word, PowerPoint and Access in pure Python, no dependencies.
 Project-URL: Homepage, https://github.com/WilliamSmithEdward/pyOfficeEditor
 Project-URL: Repository, https://github.com/WilliamSmithEdward/pyOfficeEditor
@@ -50,7 +50,23 @@ cell, the formula, the paragraph, the slide, the table, the query.
 > Excel. Conditional formatting reads and writes every rule family Excel has.
 > Data validation covers every rule Excel has, dropdowns included. Sheets
 > protect, hide, colour their tabs, set their own view, and print the way
-> you set them up. Hyperlinks, outline grouping, and the shapes on a sheet.
+> you set them up. Hyperlinks, outline grouping, and the shapes on a sheet:
+> AutoShapes, text boxes, lines and all nine Forms controls read, added,
+> removed and pointed at a macro, with a control's linked cell, list range
+> and value. Autofilters, on a sheet or a table, read and write every
+> criterion but colour and icon, and hide the rows they exclude, because
+> Excel does not recompute a filter when the workbook opens. A cell's text
+> is what Excel shows for it, number format and all. Notes and threaded
+> comments, replies included, read and write the way Excel writes them,
+> and so do pictures, text in more than one font, and named cell styles,
+> all of Excel's own among them. Charts are read, series by series, and
+> added in eight kinds as Excel's Insert Chart writes them; their
+> references move with the cells they read, and so do pivot tables and
+> their caches, refusing the edits Excel refuses. Formulas calculate:
+> 493 of Excel's 525 functions, held to 10,958 formulas Excel
+> calculated, to the last bit for all but the few functions the tests
+> name, with the results written into the cells as Excel's
+> recalculation would write them.
 > Rows and columns can be inserted and deleted, with every reference in the
 > workbook following or breaking exactly as Excel breaks it, `A:A` and `2:4`
 > included. Nothing about a sheet makes that refuse any more: validation,
@@ -59,7 +75,9 @@ cell, the formula, the paragraph, the slide, the table, the query.
 
 ```python
 import datetime as dt
-from pyofficeeditor.excel import Border, Dxf, Workbook, cell_is, gradient
+from pyofficeeditor.excel import (
+    Border, Dxf, FilterColumn, Workbook, cell_is, criteria, gradient,
+)
 
 with Workbook.open("orders.xlsx") as book:
     sheet = book["Data"]
@@ -84,6 +102,8 @@ with Workbook.open("orders.xlsx") as book:
     table = sheet.add_table("Sales", "A1:F20", totals_row=True)
     table.column_names                           # from the header row
     table.data_range                             # excludes header and totals
+    sheet.set_table_filter("Sales", [FilterColumn(1, criteria(">100"))])
+                                                 # and hides the rows it drops
 
     sheet.set_row_height(1, 24)                  # points, exact
     sheet.set_column_hidden(4, True)
@@ -101,6 +121,9 @@ with Workbook.open("orders.xlsx") as book:
     summary["A1"].formula = "=SUM(Data!D2:D5)"
     book.add_defined_name("Totals", "Data!$D$2:$D$5")
     book.rename_sheet("Data", "Q1 Data")     # formulas and names both follow
+
+    summary.evaluate("SUM(Totals)/4")            # what a formula would give
+    book.calculate()                             # every formula, results cached
     book.save()
 ```
 
@@ -163,29 +186,54 @@ data descriptors.
 |   _values     the six cell encodings, and serial dates |
 |   _styles     number formats, which is how a date is   |
 |               told from a number                       |
+|   _numfmt     what a number format shows, rounding and |
+|               Excel's fictional 1900 leap day included |
+|   _collate    Windows word sort, the order and the     |
+|               equality a filter compares text by       |
+|   _filters    autofilters, and which rows they hide:   |
+|               Excel does not recompute one on open     |
 |   _formats    fonts, fills, borders, alignment, as     |
 |               immutable values                         |
+|   _cellstyles named styles, and Excel's definitions of |
+|               its own                                  |
 |   _tables     ListObjects: their own parts and wiring  |
 |   _dimensions widths, heights, hiding, frozen panes    |
-|   _names      defined names, and the rules tables share |
-|   _shapes     shapes, and the grid that places a control |
-|   _pagesetup  margins in inches, and the three header   |
-|               boxes coded into one string               |
+|   _names      defined names, and the naming rules      |
+|               tables share with them                   |
+|   _shapes     shapes, and the grid that places a       |
+|               control                                  |
+|   _comments   notes and threads, and the box each gets |
+|   _pictures   images, sized as Excel sizes them        |
+|   _charts     what each chart plots, and chart sheets  |
+|   _chartbuild charts written as Excel's Insert Chart   |
+|               writes them                              |
+|   _pivots     where each pivot table is, and what its  |
+|               cache reads                              |
+|   _richtext   runs of text in several fonts, read as   |
+|               Excel shows them, not as marked up       |
+|   _pagesetup  margins in inches, and the three header  |
+|               boxes coded into one string              |
 |   _validation what a cell accepts, and the inverted    |
 |               attribute behind its dropdown            |
 |   _conditional  cfRules, and the compatibility formula |
 |                 that makes them fire                   |
 |   _dxf        differential formats: what a rule paints |
-|   _addresses  the five notations an address is spelled  |
-|               in, two of them zero-based                |
-|   _rowcol     inserting and deleting rows and columns,  |
+|   _addresses  the five notations an address is spelled |
+|               in, two of them zero-based               |
+|   _rowcol     inserting and deleting rows and columns, |
 |               and moving everything that records a     |
 |               cell address                             |
-|   _tokens     a formula, broken into editable pieces    |
+|   _tokens     a formula, broken into editable pieces   |
 |   _formulas   shifting and breaking references, for    |
 |               shared formulas, a renamed sheet, and    |
 |               the #REF! a deletion leaves behind       |
+|   _calc/      the formula engine: a parser, an         |
+|               evaluator with Excel's arithmetic, the   |
+|               functions, and whole-workbook            |
+|               calculation                              |
 |   _sharedstrings   the per-workbook string table       |
+|   _xstring    text as SpreadsheetML spells it: _xHHHH_ |
+|               for what XML cannot carry                |
 |   _schema     where a child element has to go          |
 +--------------------------------------------------------+
 | word / powerpoint / access   to follow, in that order  |
@@ -333,6 +381,13 @@ RUN_LIVE_EXCEL=1 python -m pytest -m live -p no:randomly
 
 Windows and Excel only. Everything else in the suite runs anywhere.
 
+## Built with this
+
+[xlide-mcp](https://github.com/WilliamSmithEdward/xlide_mcp)
+is an MCP server built on this. This library is what answers when an
+agent asks it for a cell, a formula, a table or a conditional rule, and
+what writes the change back with the rest of the package left alone.
+
 ## License
 
 MIT. See [LICENSE.md](LICENSE.md).

{pyofficeeditor-0.2.2 → pyofficeeditor-0.3.0}/README.md

@@ -13,7 +13,23 @@ cell, the formula, the paragraph, the slide, the table, the query.
 > Excel. Conditional formatting reads and writes every rule family Excel has.
 > Data validation covers every rule Excel has, dropdowns included. Sheets
 > protect, hide, colour their tabs, set their own view, and print the way
-> you set them up. Hyperlinks, outline grouping, and the shapes on a sheet.
+> you set them up. Hyperlinks, outline grouping, and the shapes on a sheet:
+> AutoShapes, text boxes, lines and all nine Forms controls read, added,
+> removed and pointed at a macro, with a control's linked cell, list range
+> and value. Autofilters, on a sheet or a table, read and write every
+> criterion but colour and icon, and hide the rows they exclude, because
+> Excel does not recompute a filter when the workbook opens. A cell's text
+> is what Excel shows for it, number format and all. Notes and threaded
+> comments, replies included, read and write the way Excel writes them,
+> and so do pictures, text in more than one font, and named cell styles,
+> all of Excel's own among them. Charts are read, series by series, and
+> added in eight kinds as Excel's Insert Chart writes them; their
+> references move with the cells they read, and so do pivot tables and
+> their caches, refusing the edits Excel refuses. Formulas calculate:
+> 493 of Excel's 525 functions, held to 10,958 formulas Excel
+> calculated, to the last bit for all but the few functions the tests
+> name, with the results written into the cells as Excel's
+> recalculation would write them.
 > Rows and columns can be inserted and deleted, with every reference in the
 > workbook following or breaking exactly as Excel breaks it, `A:A` and `2:4`
 > included. Nothing about a sheet makes that refuse any more: validation,
@@ -22,7 +38,9 @@ cell, the formula, the paragraph, the slide, the table, the query.
 
 ```python
 import datetime as dt
-from pyofficeeditor.excel import Border, Dxf, Workbook, cell_is, gradient
+from pyofficeeditor.excel import (
+    Border, Dxf, FilterColumn, Workbook, cell_is, criteria, gradient,
+)
 
 with Workbook.open("orders.xlsx") as book:
     sheet = book["Data"]
@@ -47,6 +65,8 @@ with Workbook.open("orders.xlsx") as book:
     table = sheet.add_table("Sales", "A1:F20", totals_row=True)
     table.column_names                           # from the header row
     table.data_range                             # excludes header and totals
+    sheet.set_table_filter("Sales", [FilterColumn(1, criteria(">100"))])
+                                                 # and hides the rows it drops
 
     sheet.set_row_height(1, 24)                  # points, exact
     sheet.set_column_hidden(4, True)
@@ -64,6 +84,9 @@ with Workbook.open("orders.xlsx") as book:
     summary["A1"].formula = "=SUM(Data!D2:D5)"
     book.add_defined_name("Totals", "Data!$D$2:$D$5")
     book.rename_sheet("Data", "Q1 Data")     # formulas and names both follow
+
+    summary.evaluate("SUM(Totals)/4")            # what a formula would give
+    book.calculate()                             # every formula, results cached
     book.save()
 ```
 
@@ -126,29 +149,54 @@ data descriptors.
 |   _values     the six cell encodings, and serial dates |
 |   _styles     number formats, which is how a date is   |
 |               told from a number                       |
+|   _numfmt     what a number format shows, rounding and |
+|               Excel's fictional 1900 leap day included |
+|   _collate    Windows word sort, the order and the     |
+|               equality a filter compares text by       |
+|   _filters    autofilters, and which rows they hide:   |
+|               Excel does not recompute one on open     |
 |   _formats    fonts, fills, borders, alignment, as     |
 |               immutable values                         |
+|   _cellstyles named styles, and Excel's definitions of |
+|               its own                                  |
 |   _tables     ListObjects: their own parts and wiring  |
 |   _dimensions widths, heights, hiding, frozen panes    |
-|   _names      defined names, and the rules tables share |
-|   _shapes     shapes, and the grid that places a control |
-|   _pagesetup  margins in inches, and the three header   |
-|               boxes coded into one string               |
+|   _names      defined names, and the naming rules      |
+|               tables share with them                   |
+|   _shapes     shapes, and the grid that places a       |
+|               control                                  |
+|   _comments   notes and threads, and the box each gets |
+|   _pictures   images, sized as Excel sizes them        |
+|   _charts     what each chart plots, and chart sheets  |
+|   _chartbuild charts written as Excel's Insert Chart   |
+|               writes them                              |
+|   _pivots     where each pivot table is, and what its  |
+|               cache reads                              |
+|   _richtext   runs of text in several fonts, read as   |
+|               Excel shows them, not as marked up       |
+|   _pagesetup  margins in inches, and the three header  |
+|               boxes coded into one string              |
 |   _validation what a cell accepts, and the inverted    |
 |               attribute behind its dropdown            |
 |   _conditional  cfRules, and the compatibility formula |
 |                 that makes them fire                   |
 |   _dxf        differential formats: what a rule paints |
-|   _addresses  the five notations an address is spelled  |
-|               in, two of them zero-based                |
-|   _rowcol     inserting and deleting rows and columns,  |
+|   _addresses  the five notations an address is spelled |
+|               in, two of them zero-based               |
+|   _rowcol     inserting and deleting rows and columns, |
 |               and moving everything that records a     |
 |               cell address                             |
-|   _tokens     a formula, broken into editable pieces    |
+|   _tokens     a formula, broken into editable pieces   |
 |   _formulas   shifting and breaking references, for    |
 |               shared formulas, a renamed sheet, and    |
 |               the #REF! a deletion leaves behind       |
+|   _calc/      the formula engine: a parser, an         |
+|               evaluator with Excel's arithmetic, the   |
+|               functions, and whole-workbook            |
+|               calculation                              |
 |   _sharedstrings   the per-workbook string table       |
+|   _xstring    text as SpreadsheetML spells it: _xHHHH_ |
+|               for what XML cannot carry                |
 |   _schema     where a child element has to go          |
 +--------------------------------------------------------+
 | word / powerpoint / access   to follow, in that order  |
@@ -296,6 +344,13 @@ RUN_LIVE_EXCEL=1 python -m pytest -m live -p no:randomly
 
 Windows and Excel only. Everything else in the suite runs anywhere.
 
+## Built with this
+
+[xlide-mcp](https://github.com/WilliamSmithEdward/xlide_mcp)
+is an MCP server built on this. This library is what answers when an
+agent asks it for a cell, a formula, a table or a conditional rule, and
+what writes the change back with the rest of the package left alone.
+
 ## License
 
 MIT. See [LICENSE.md](LICENSE.md).

{pyofficeeditor-0.2.2 → pyofficeeditor-0.3.0}/docs/architecture.md

@@ -67,16 +67,44 @@ Each layer knows the layer below it and not the layer above.
 |                 rather than permissions                   |
 |   _pagesetup    margins in inches, headers as one string  |
 |   _hyperlinks   links, whose address is in a relationship |
+|   _filters      autofilters, and which rows they hide:    |
+|                 Excel does not recompute one on open      |
+|   _numfmt       what a number format shows, rounding and  |
+|                 the fictional 1900 leap day included      |
+|   _collate      Windows word sort, the order and the      |
+|                 equality a filter compares text by        |
 |   _shapes       shapes, and the grid a form control needs |
+|   _comments     notes and threads, and the box each gets  |
+|   _pictures     images, sized as Excel sizes them         |
+|   _charts       what each chart plots, and chart sheets   |
+|   _chartbuild   charts written as Excel's Insert Chart    |
+|                 writes them                               |
+|   _pivots       where each pivot table is, and what its   |
+|                 cache reads                               |
+|   _richtext     runs of text in several fonts, read as    |
+|                 Excel shows them, not as marked up        |
 |   _conditional  cfRules, and the compatibility formula    |
 |                 that makes them fire                      |
 |   _dxf          differential formats: what a rule paints  |
 |   _styles       the five style tables; is this a date?   |
 |   _formats      fonts, fills, borders, alignment, as     |
 |                 immutable values                         |
+|   _cellstyles   named styles, and Excel's definitions of |
+|                 its own                                  |
 |   _formulas     reference shifting for shared formulas, |
 |                 and repointing a renamed sheet          |
+|   _calc/        the formula engine                      |
+|     lexer, parser, nodes   formula text into a tree,    |
+|                 with Excel's precedence                 |
+|     values, numbers, dates, precise   Excel's scalars,  |
+|                 coercion, and arithmetic past IEEE's    |
+|     evaluator, registry, functions/   a tree evaluated |
+|                 against a workbook, function by family  |
+|     engine      every formula in dependency order,     |
+|                 results written back                    |
 |   _sharedstrings  the per-workbook string table         |
+|   _xstring      text as SpreadsheetML spells it, with   |
+|                 _xHHHH_ for what XML cannot carry       |
 |   _reference    A1 notation, bijective base-26          |
 |   _schema       the child order CT_Worksheet and         |
 |                 CT_Workbook require                     |
@@ -112,7 +140,9 @@ Each layer knows the layer below it and not the layer above.
   something from the container, `opc.py` grows a method.
 - Inside `excel/`, the four private modules are pure: `_reference`,
   `_styles`, `_formulas` and `_values` know about elements and strings, not
-  about packages or files. `workbook.py` is the only one that does.
+  about packages or files. `workbook.py` is the only one that does. So are
+  `_numfmt`, `_collate` and `_filters`: the worksheet hands a filter its
+  cells and the date, and the filter decides rows without touching it.
 - `Worksheet` owns the part and does the work, addressed by `CellRef`.
   `Cell` and `Range` are views that delegate to it, so nothing is reachable
   only through a cell. That is why `Worksheet.get_value` and friends are
@@ -219,6 +249,21 @@ The Excel surface is exported from `pyofficeeditor.excel`:
 | `Styles`, `SharedStrings` | `excel/_styles.py`, `excel/_sharedstrings.py` | the shared parts |
 | `column_letter`, `column_index` | `excel/_reference.py` | bijective base-26 |
 | `MAX_ROW`, `MAX_COLUMN` | `excel/_reference.py` | Excel's real limits |
+| `AutoFilter`, `FilterColumn`, `ValueFilter`, `CustomFilter`, `Comparison`, `FilterOperator`, `Top10Filter`, `DynamicFilter`, `DateGroup`, `OpaqueCriterion`, `criteria` | `excel/_filters.py` | a filter's criteria, validated as Excel validates them |
+| `FilterOutcome` | `excel/_filters.py` | which rows applying a filter hid, showed and left alone |
+| `Comment` | `excel/_comments.py` | a note on a cell: text, author, and whether it shows |
+| `ThreadedComment`, `Reply` | `excel/_comments.py` | a conversation on a cell, and each answer in it |
+| `TextRun` | `excel/_richtext.py` | part of a cell's text, and the font it shows in |
+| `CellStyle` | `excel/_cellstyles.py` | a named cell style: its format, and what of a cell it sets |
+| `Chart`, `ChartSeries` | `excel/_charts.py` | what a chart plots, and each series' references |
+| `ChartSheet` | `excel/_charts.py` | a tab that is one chart and holds no cells |
+| `PivotTable` | `excel/_pivots.py` | where a pivot table is, and what its cache was read from |
+| `format_value` | `excel/_numfmt.py` | the text Excel shows for a value under a format code |
+| `Calculation` | `excel/_calc/engine.py` | what `Workbook.calculate()` did, and which formulas kept their cached value |
+| `FormulaSyntaxError` | `excel/_calc/lexer.py` | formula text Excel would refuse, and where |
+
+`UnsupportedFormulaError`, in `exceptions.py`, is what `Worksheet.evaluate`
+raises for a formula needing something the engine does not have.
 
 `opc.py` also exports the path helpers (`normalize_part_name`,
 `rels_part_for`, `resolve_target`, `relative_target`) and the content-type
@@ -300,11 +345,41 @@ tests/
   test_excel_settings.py        protection, tab colour, view, visibility
   test_excel_pagesetup.py       margins, orientation, headers, print area
   test_excel_links.py           hyperlinks and outline grouping
+  test_excel_filters.py         autofilters on sheets and tables, and the
+                                rows they hide
+  test_excel_filter_semantics.py  which rows each criterion keeps, case
+                                by case against filter_semantics.json
+  test_excel_numfmt.py          what a number format shows, against
+                                number_formats.json
   test_excel_shapes.py          shapes, against what Excel said of them
+  test_excel_controls.py        what a form control is wired to
+  test_excel_shapes_write.py    adding, removing and rewiring shapes
+  test_excel_comments.py        notes and threads, against what Excel said
+  test_excel_pictures.py        pictures, against what Excel said of them
+  test_excel_xstring.py         _xHHHH_ escapes, character by character,
+                                against what Excel wrote and read
+  test_excel_escapes.py         that text everywhere a workbook keeps it,
+                                against escapes_answers.json
+  test_excel_richtext.py        text in several fonts, against the fonts
+                                Excel showed and the entries it wrote
+  test_excel_cellstyles.py      named styles, against the cells Excel
+                                styled itself
+  test_excel_charts.py          charts and chart sheets, and every
+                                reference after nine edits, against the
+                                files Excel saved after the same edits
+  test_excel_pivots.py          pivot tables through nineteen edits, and
+                                the ones Excel refuses
+  test_excel_chartbuild.py      charts added, against the parts Excel
+                                wrote for the same charts
   test_excel_dxf.py             differential formats and the dxfs table
+  test_excel_calc.py            the formula parser, Excel's arithmetic,
+                                and calculating a whole workbook
+  test_excel_formula_corpus.py  every formula in formulas.xlsx,
+                                calculated and held to Excel's result
   test_excel_live_gate.py       real Excel, opt-in
-  fixtures/excel/               three committed Excel-authored packages,
-                                plus two built on demand; see its README
+  fixtures/excel/               twenty-one Excel-authored packages:
+                                three sourced, eighteen scripted, and
+                                three measured corpora; see its README
 ```
 
 - **Always** run pytest with `-p no:randomly` to keep ordering reproducible.
@@ -312,14 +387,17 @@ tests/
   merge: `pyright src tests`.
 - **Ruff** must pass: `ruff check src tests scripts`.
 - New behavior lands with its test in the same commit.
-- The suite needs no Office installation. It runs against six committed
+- The suite needs no Office installation. It runs against twenty-one committed
   Excel-authored packages, an `.xlsb` among them, and against
   openpyxl-authored ones generated during the run, because a reader that
   only ever sees one producer's output encodes that producer's habits as
   rules.
 - Richer Excel-authored fixtures come from
   `scripts/build_excel_fixtures.py`, which drives real Excel through
-  `pyvbaharness`. Tests needing them skip when they are absent.
+  `pyvbaharness`. Tests needing them skip when they are absent. The three
+  measured corpora come from `scripts/measure_number_formats.py`,
+  `scripts/measure_filters.py` and `scripts/measure_formulas.py` the same
+  way.
 
 ### 8.1 The fidelity gate
 
@@ -470,9 +548,77 @@ the file. The stored number is exposed as-is, because a conversion right for
 one font and quietly wrong for the rest is worse than none. Row heights carry
 no such trap: they are points, and 24 stores as 24.
 
-**A dimension needs its companion flag.** A `width` without `customWidth="1"`
-and an `ht` without `customHeight="1"` are ignored, so the value looks like it
-never took.
+**A row height needs its companion flag, and a column needs a width.** An
+`ht` without `customHeight="1"` is ignored, so the value looks like it never
+took. A `width` is honoured with or without `customWidth="1"`, but a `<col>`
+with no `width` at all is a column of width 0: an entry carrying only
+`outlineLevel`, `collapsed`, `style` or nothing shows as hidden, and stays
+hidden when its outline is expanded. So every entry this library makes for a
+column at the standard width carries that width, the one Excel writes: the
+sheet's `defaultColWidth` when it has one, and otherwise a width fixed by the
+Normal font, measured per font. Grouping columns hid them outright until this
+was measured.
+
+**A filter is stored twice, and Excel trusts the second copy.** The criteria
+live in `<autoFilter>`, and which rows they hide lives on each row's `hidden`
+flag. Excel does not recompute a filter when the workbook opens: it lights
+the dropdowns from the first and shows the rows the second allows. So setting
+a filter here decides every row, and that needs Excel's own rules. A value
+list compares the text a cell *shows*, which is why `_numfmt` renders number
+formats as Excel does, and compares it by Windows word sort, which `_collate`
+reproduces. Both are held to corpora measured from Excel,
+`number_formats.json` and `filter_semantics.json`, because the specification
+states neither. A row that hangs on something not modelled, a colour filter
+or a formula whose cached result an edit has made stale, is left as it was
+rather than guessed at, and `FilterOutcome` says which rows those were.
+
+**A chart reads the workbook through formulas.** Everything a chart plots,
+a series' name, categories and values, and a title linked to a cell, is a
+sheet-qualified reference in a `<c:f>` of the chart's own part. A chart on
+any sheet, or on a chart sheet, may read from any other, so inserting or
+deleting rows on one sheet has to visit every chart part in the workbook,
+and renaming a sheet likewise. Measured, the references move exactly as a
+cell's formula does, down to `Data!#REF!` for one deleted outright. Excel's
+object model is no witness for that last case: it reports the old address
+until the file is reopened, and then refuses to report the series, so the
+fixture records the references in the files Excel saved.
+
+**A pivot table is two parts away from its cells.** Its location is in its
+own part and the range its cache was read from is in the cache's, and
+neither is in the sheet. Excel refuses an insertion or deletion that cuts
+through a pivot table, and so does this library, rather than guess at a
+layout Excel would not produce; one that takes all of it deletes it, and its
+cache when nothing else reads from that, as Excel does.
+
+**A named style is defined only once something uses it.** A workbook's
+`cellStyles` names each style it has and points at the style's format in
+`cellStyleXfs`, whose `apply...="0"` attributes say what the style leaves
+out. Excel's own styles are not in a workbook until a cell uses one, when
+Excel writes one out from a definition of its own, and so does this library,
+from Excel's definitions as Excel wrote them. Those definitions name the
+theme's typefaces rather than the Normal style's, so they follow a change
+of theme and not a change of Normal. A cell in a style carries a copy of what
+the style sets, and its own `apply...="1"` marks where it differs.
+
+**Text is not stored as XML stores it.** XML cannot carry most control
+characters, and an attribute turns a line break into a space. SpreadsheetML
+spells such a character `_xHHHH_` instead, and escapes the underscore of any
+literal text that would read as one, so `_x0041_` in a cell is stored
+`_x005F_x0041_`. Excel writes uppercase hex in element text, where a line
+break stays a line break, and lowercase hex in attributes, where it does not,
+and reads either. Every place a workbook keeps text goes through
+`_xstring`, because one that does not either writes a file Excel refuses or
+reads back seven characters for one. A table's headers are the exception:
+Excel replaces such a character there with U+FFFD rather than escaping it.
+
+**Rich text is read by rules its markup does not state.** Excel writes the
+first run of a cell's text with no font and gives the cell that run's font;
+every later run carries its font in full. Other writers leave runs less
+complete, and Excel reads them by rules measured here rather than found in
+the specification. Runs with no font show in the cell's font until a run has
+one, and in the workbook's default font after that. A run's font takes what
+it leaves unsaid from the default font as well, so a run that says only
+"bold" in a Courier cell shows in the default typeface, not in Courier.
 
 **Inserting a row is not a local edit.** A cell's address is written into the
 file in a dozen places, and missing one gives a workbook that opens cleanly
@@ -590,6 +736,28 @@ Note that `ActiveWindow.SplitRow` and `SplitColumn` are *not* how to verify a
 freeze: a workbook Excel froze itself reports 0 for both, so they discriminate
 nothing. `Panes.Count` and where `VisibleRange` starts do.
 
+**A formula's value is Excel's arithmetic, not IEEE's.** The engine in
+`excel/_calc` is held to `formulas.xlsx`, where each of 10,958 formulas sits
+beside the value Excel calculated for it, and what that corpus pinned down
+is written into the modules that follow it. Equality reads both sides to
+fifteen digits. A formula's last `+` or `-`, and SUM's last addition, give
+0 under eight units in the last place of the left operand, which the
+corpus found by measuring each pair of numbers both ways round. A number
+literal or a number read from text keeps fifteen digits, cut. Arithmetic
+reproduces the x87 unit Excel computes in (`precise.py`): each operation
+rounds to 64 bits and then to 53, so `8^(-1/3)` is exactly 0.5 though
+`1/1.9999999999999998` is not, EXP and LN follow F2XM1 and FYL2X, and SIN,
+COS and TAN reduce with pi to 64 bits. Sums run in order through
+`precise.summed`, never Python's `sum`, which compensates from 3.12 on.
+Where the corpus narrowed a function to a few units in the last place
+without fixing it, the test says so by name.
+
+The engine calculates without recursion. Reading a cell whose formula is
+not calculated raises `PendingCellsError` naming every such cell the read
+touched; those go on an explicit stack and the reader is tried again.
+A range read names all its uncalculated cells at once, so a SUM over a
+column of formulas retries once, not once per cell.
+
 ### 8.3 The live gate
 
 `test_excel_live_gate.py` is the only check that can prove Excel accepts what