xlio 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- xlio-0.1.0/.gitignore +23 -0
- xlio-0.1.0/CAPTURING.md +91 -0
- xlio-0.1.0/CHANGELOG.md +127 -0
- xlio-0.1.0/CONTRIBUTING.md +79 -0
- xlio-0.1.0/LICENSE +21 -0
- xlio-0.1.0/NOTICE +29 -0
- xlio-0.1.0/PKG-INFO +61 -0
- xlio-0.1.0/README.md +33 -0
- xlio-0.1.0/capture/__init__.py +0 -0
- xlio-0.1.0/capture/attributes_probe.py +217 -0
- xlio-0.1.0/capture/edition.py +56 -0
- xlio-0.1.0/capture/errors_probe.py +212 -0
- xlio-0.1.0/capture/excel.py +18 -0
- xlio-0.1.0/capture/fixtures.py +256 -0
- xlio-0.1.0/capture/package_open.applescript +73 -0
- xlio-0.1.0/capture/package_probe.py +345 -0
- xlio-0.1.0/capture/paths.py +12 -0
- xlio-0.1.0/capture/probe.py +176 -0
- xlio-0.1.0/capture/repair_probe.py +208 -0
- xlio-0.1.0/capture/restore_alerts.applescript +2 -0
- xlio-0.1.0/capture/save_copy.applescript +33 -0
- xlio-0.1.0/capture/save_open.applescript +29 -0
- xlio-0.1.0/capture/text_probe.py +264 -0
- xlio-0.1.0/capture/theme_probe.py +84 -0
- xlio-0.1.0/capture/value_probe.py +161 -0
- xlio-0.1.0/capture/views_probe.py +189 -0
- xlio-0.1.0/docs/_templates/page.html +15 -0
- xlio-0.1.0/docs/_templates/search.html +96 -0
- xlio-0.1.0/docs/api.md +363 -0
- xlio-0.1.0/docs/changelog.md +2 -0
- xlio-0.1.0/docs/conf.py +55 -0
- xlio-0.1.0/docs/index.md +29 -0
- xlio-0.1.0/pagefind.yml +7 -0
- xlio-0.1.0/pyproject.toml +110 -0
- xlio-0.1.0/src/xlio/__init__.py +231 -0
- xlio-0.1.0/src/xlio/_book.py +381 -0
- xlio-0.1.0/src/xlio/_cells.py +487 -0
- xlio-0.1.0/src/xlio/_comments.py +144 -0
- xlio-0.1.0/src/xlio/_conditional.py +396 -0
- xlio-0.1.0/src/xlio/_drawing.py +531 -0
- xlio-0.1.0/src/xlio/_package.py +405 -0
- xlio-0.1.0/src/xlio/_patch.py +144 -0
- xlio-0.1.0/src/xlio/_print.py +339 -0
- xlio-0.1.0/src/xlio/_rich.py +165 -0
- xlio-0.1.0/src/xlio/_richvalue.py +101 -0
- xlio-0.1.0/src/xlio/_structure.py +822 -0
- xlio-0.1.0/src/xlio/_styles.py +802 -0
- xlio-0.1.0/src/xlio/_tables.py +588 -0
- xlio-0.1.0/src/xlio/_theme.py +161 -0
- xlio-0.1.0/src/xlio/_types.py +247 -0
- xlio-0.1.0/src/xlio/_workbook.py +950 -0
- xlio-0.1.0/src/xlio/_write.py +772 -0
- xlio-0.1.0/src/xlio/_zip.py +268 -0
- xlio-0.1.0/src/xlio/data/presetTableStyles.xml +18070 -0
- xlio-0.1.0/src/xlio/ns.py +76 -0
- xlio-0.1.0/src/xlio/presets.py +50 -0
- xlio-0.1.0/src/xlio/py.typed +0 -0
- xlio-0.1.0/tests/__init__.py +0 -0
- xlio-0.1.0/tests/captures/attributes.tsv +89 -0
- xlio-0.1.0/tests/captures/errors.tsv +62 -0
- xlio-0.1.0/tests/captures/package.tsv +72 -0
- xlio-0.1.0/tests/captures/repair.tsv +15 -0
- xlio-0.1.0/tests/captures/text.tsv +291 -0
- xlio-0.1.0/tests/captures/text_launch_convert.tsv +108 -0
- xlio-0.1.0/tests/captures/text_launch_dont.tsv +108 -0
- xlio-0.1.0/tests/captures/text_launch_none.tsv +14 -0
- xlio-0.1.0/tests/captures/theme_bound.tsv +8 -0
- xlio-0.1.0/tests/captures/value_forms.tsv +31 -0
- xlio-0.1.0/tests/captures/views.tsv +46 -0
- xlio-0.1.0/tests/conftest.py +26 -0
- xlio-0.1.0/tests/files/excel/conditional.xlsx +0 -0
- xlio-0.1.0/tests/files/excel/drawings.xlsx +0 -0
- xlio-0.1.0/tests/files/excel/handmade.xlsx +0 -0
- xlio-0.1.0/tests/files/excel/notes.xlsx +0 -0
- xlio-0.1.0/tests/files/excel/tables.xlsx +0 -0
- xlio-0.1.0/tests/files/excel_formulas.xlsx +0 -0
- xlio-0.1.0/tests/files/iterate_cached.xlsx +0 -0
- xlio-0.1.0/tests/files/marker_typed.xlsx +0 -0
- xlio-0.1.0/tests/files/metadata.xml +2 -0
- xlio-0.1.0/tests/files/rdrichvalue.xml +2 -0
- xlio-0.1.0/tests/files/rdrichvaluestructure.xml +2 -0
- xlio-0.1.0/tests/test_api.py +454 -0
- xlio-0.1.0/tests/test_attributes.py +143 -0
- xlio-0.1.0/tests/test_citations.py +52 -0
- xlio-0.1.0/tests/test_conditional.py +222 -0
- xlio-0.1.0/tests/test_crafted.py +468 -0
- xlio-0.1.0/tests/test_drawing.py +431 -0
- xlio-0.1.0/tests/test_errors.py +73 -0
- xlio-0.1.0/tests/test_excel_files.py +105 -0
- xlio-0.1.0/tests/test_numbers.py +110 -0
- xlio-0.1.0/tests/test_patch.py +182 -0
- xlio-0.1.0/tests/test_print.py +194 -0
- xlio-0.1.0/tests/test_read.py +414 -0
- xlio-0.1.0/tests/test_repair.py +70 -0
- xlio-0.1.0/tests/test_structure.py +474 -0
- xlio-0.1.0/tests/test_styles.py +346 -0
- xlio-0.1.0/tests/test_tables.py +274 -0
- xlio-0.1.0/tests/test_value_forms.py +63 -0
- xlio-0.1.0/tests/test_views.py +64 -0
- xlio-0.1.0/tests/test_write.py +340 -0
- xlio-0.1.0/tests/watchdog.py +245 -0
xlio-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# environments and caches
|
|
2
|
+
.venv/
|
|
3
|
+
__pycache__/
|
|
4
|
+
*.py[cod]
|
|
5
|
+
.pytest_cache/
|
|
6
|
+
.mypy_cache/
|
|
7
|
+
.ruff_cache/
|
|
8
|
+
dist/
|
|
9
|
+
build/
|
|
10
|
+
*.egg-info/
|
|
11
|
+
|
|
12
|
+
# macOS and editors
|
|
13
|
+
.DS_Store
|
|
14
|
+
.idea/
|
|
15
|
+
.vscode/
|
|
16
|
+
*.sublime-workspace
|
|
17
|
+
|
|
18
|
+
# capture output (Excel's copies, the stated edition)
|
|
19
|
+
capture/build/
|
|
20
|
+
|
|
21
|
+
# documentation build (Sphinx HTML and the Pagefind index inside it)
|
|
22
|
+
docs/_build/
|
|
23
|
+
node_modules/
|
xlio-0.1.0/CAPTURING.md
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Capturing Excel's behavior
|
|
2
|
+
|
|
3
|
+
What xlio reads, refuses and writes is checked against what Excel 16 for Mac does with the same
|
|
4
|
+
file. Such behavior is captured from Excel, never written from memory or taken from another
|
|
5
|
+
program's output. Captured data lives in `tests/captures/`, the scripts that produce it in
|
|
6
|
+
`capture/`, and each test that uses a capture names it.
|
|
7
|
+
|
|
8
|
+
## Method
|
|
9
|
+
|
|
10
|
+
1. A script in `capture/` builds small workbooks, each differing from a control in one way (a
|
|
11
|
+
`<v>` rewritten as `nan`, a row moved past the grid).
|
|
12
|
+
2. Excel opens each workbook with alerts off and saves a copy (`capture/save_copy.applescript`).
|
|
13
|
+
A file Excel would offer to repair fails to open with error -50 while alerts are off; that
|
|
14
|
+
is recorded as `refused`.
|
|
15
|
+
3. The script reads Excel's verdict and the values Excel saved from the copy's XML, and writes a
|
|
16
|
+
TSV with a header naming the suite, the Excel build, the edition and update channel, the
|
|
17
|
+
locale, the date and the method.
|
|
18
|
+
|
|
19
|
+
## Steps that need a person
|
|
20
|
+
|
|
21
|
+
Some behavior shows only to a person: Excel's repair dialog, and its notice of default
|
|
22
|
+
conversions for a `.csv` file, which an AppleScript open does not show (it applies the default,
|
|
23
|
+
"Convert"). Such a step opens the file through Launch Services (`open -a "Microsoft Excel"`) and
|
|
24
|
+
then exits; it sends Excel nothing more until you have answered the dialog and run its next step
|
|
25
|
+
(answering the conversion notice while a script was querying Excel crashed Excel twice, on
|
|
26
|
+
16.115). Copy a repair report's text into the next step's `--report`; the script keeps only its
|
|
27
|
+
records, without paths.
|
|
28
|
+
|
|
29
|
+
## Rules for the scripts
|
|
30
|
+
|
|
31
|
+
- Non-interactive: `display alerts` is turned off and restored on every exit path, including
|
|
32
|
+
errors; otherwise Excel would silently fail to open or repair files afterwards.
|
|
33
|
+
- A script refuses to run while Excel has any workbook open, opens only workbooks it creates,
|
|
34
|
+
and closes them without saving unless saving is the point.
|
|
35
|
+
- Excel is sandboxed: workbooks are built inside its container
|
|
36
|
+
(`~/Library/Containers/com.microsoft.Excel/Data/Documents/xlio/`), so it opens them without
|
|
37
|
+
asking for access, and are deleted afterwards.
|
|
38
|
+
- The edition is stated by the person capturing (`XLIO_EXCEL_EDITION`, or
|
|
39
|
+
`capture/build/excel_edition.txt`), since the build number alone does not say which features
|
|
40
|
+
Excel has (`capture/edition.py`).
|
|
41
|
+
- Floats are written into workbooks as their shortest exact text (`repr`).
|
|
42
|
+
- One capture at a time, and none while a test or a run feeds crafted input to the reader (the
|
|
43
|
+
memory watchdog would compete with Excel).
|
|
44
|
+
|
|
45
|
+
## Captures
|
|
46
|
+
|
|
47
|
+
| capture | script | what it records |
|
|
48
|
+
|---|---|---|
|
|
49
|
+
| `package` | `capture/package_probe.py` | archives, DTDs and sizes no column, row or font can have: whether Excel opens the file, and the widths, heights and font size it reads |
|
|
50
|
+
| `value_forms` | `capture/value_probe.py` | number forms Excel never writes in a `<v>` (`nan`, `INF`, `1e400`, `+5`, ` 5`, a subnormal), and rows and columns off the grid: whether Excel opens the file, and the value it reads |
|
|
51
|
+
| `errors` | `capture/errors_probe.py` | each error code written plainly in a `<v>` (as a constant and as a formula's cached value), `#VALUE!` with a rich value of each `errorType` 0 to 20, and formulas returning the newer errors: whether Excel opens the file, and the error it reads (`ERROR.TYPE`, `VALUETOTEXT`) and writes |
|
|
52
|
+
| `views` | `capture/views_probe.py` | `activeCell` values Excel does not write, selections for absent panes, zoom, `activeTab` and sheet `state` out of range, head records after `sheetData`: whether Excel opens the file, and the view it saves |
|
|
53
|
+
| `attributes` | `capture/attributes_probe.py` | flags that are not booleans, sizes that are not numbers, indexes past their tables, colors, rotations and font sizes out of range, page setup values, absent margins, print names: whether Excel opens the file, and what it saves |
|
|
54
|
+
| `theme_bound` | `capture/theme_probe.py` | the theme color index past which Excel refuses a file, bisected |
|
|
55
|
+
| `text` | `capture/text_probe.py` | `.csv` files opened through File > Open's defaults (AppleScript): every cell of the copy with its type, value and number format, the sheet name and the standard font, for conversions (quoted and bare), encodings and structure |
|
|
56
|
+
| `text_launch_*` | `capture/text_probe.py --launch-open`, `--launch CHOICE` | three of those files opened as a person opens them (Launch Services), Excel's notice of default conversions answered by the person (`convert`, `dont`, or `none` when it did not appear) |
|
|
57
|
+
| `repair` | `capture/repair_probe.py` | reversed drawing anchors and invalid conditional formats opened by a person, Excel's repair answered Yes: what the repaired workbook keeps, and the repair report's records |
|
|
58
|
+
|
|
59
|
+
`capture/fixtures.py` is not a capture: it has Excel save workbooks XlsxWriter builds (tables
|
|
60
|
+
and filters, conditional formats, drawings, notes) into `tests/files/excel/`, and with `--adopt`
|
|
61
|
+
takes a workbook made by hand in Excel (threaded comments, icons, pictures in cells), each
|
|
62
|
+
stripped of paths and people.
|
|
63
|
+
|
|
64
|
+
`package` and `value_forms` gave the same results under Office 2021 (Excel 16.114.3) and
|
|
65
|
+
Microsoft 365 (Excel 16.115, Current Channel).
|
|
66
|
+
|
|
67
|
+
The `text` and `text_launch_*` captures serve no code in this release: they record how Excel
|
|
68
|
+
opens CSV files, for the text formats (CSV, TSV, fixed width) planned for the next minor
|
|
69
|
+
release.
|
|
70
|
+
|
|
71
|
+
## Captures kept elsewhere
|
|
72
|
+
|
|
73
|
+
Some rules were captured by xlrecalc, where this code was first written, and are cited with a
|
|
74
|
+
link: the outer whitespace Excel drops
|
|
75
|
+
([`whitespace.tsv`](https://github.com/sheetmill/xlrecalc/blob/main/tests/captures/whitespace.tsv)),
|
|
76
|
+
dynamic-array and rich-value metadata
|
|
77
|
+
([`arrays.tsv`](https://github.com/sheetmill/xlrecalc/blob/main/tests/captures/arrays.tsv)) and
|
|
78
|
+
text results read by Excel
|
|
79
|
+
([`test_excel_live.py`](https://github.com/sheetmill/xlrecalc/blob/main/tests/test_excel_live.py)).
|
|
80
|
+
|
|
81
|
+
## Platforms
|
|
82
|
+
|
|
83
|
+
Every capture here is from Excel for Mac. Excel for Windows is not captured; where the two may
|
|
84
|
+
differ, the reader follows the Mac.
|
|
85
|
+
|
|
86
|
+
## Test workbooks
|
|
87
|
+
|
|
88
|
+
`tests/files/excel/` holds the workbooks `capture/fixtures.py` had Excel save.
|
|
89
|
+
`tests/files/marker_typed.xlsx`, `iterate_cached.xlsx` and `excel_formulas.xlsx` were saved by
|
|
90
|
+
Excel for Mac for xlrecalc's tests (https://github.com/sheetmill/xlrecalc/blob/main/CAPTURING.md)
|
|
91
|
+
and copied from there, stripped of paths and editors.
|
xlio-0.1.0/CHANGELOG.md
ADDED
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
## [0.1.0] - 2026-11-15
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
- The xlsx reader and surgical writer, extracted from xlrecalc (where they are private) to be
|
|
14
|
+
shared by the sheetmill packages.
|
|
15
|
+
- `xlio.open()` returns a `Workbook`: every sheet with its kind and state (`Sheet.kind`,
|
|
16
|
+
`Sheet.state`), defined names, calculation settings, the date system, dynamic-array and
|
|
17
|
+
rich-value metadata, and whether the file is a template or macro-enabled. `Sheet.cells()`
|
|
18
|
+
streams a worksheet's cells, optionally within a range, each with its value, type, formula,
|
|
19
|
+
style index and metadata indexes.
|
|
20
|
+
- Values are read as Excel reads them: a subnormal number reads as 0; a cell with an error rich
|
|
21
|
+
value behind its `vm` reads as the error Excel shows (`#SPILL!`, `#CALC!`, `#FIELD!`,
|
|
22
|
+
`#CONNECT!`, `#BLOCKED!`, `#UNKNOWN!`, `#BUSY!`, `#TIMEOUT!`, by its `errorType`), whatever
|
|
23
|
+
the cell caches, and type 14 as the number 0, as Excel saves it; errors are `ErrorCode`
|
|
24
|
+
values (a `str` enum holding every error Excel defines). A file with an error code written
|
|
25
|
+
as text that Excel refuses there (any but the first seven, `#GETTING_DATA` and `#BUSY!`), or
|
|
26
|
+
a rich-value error type it refuses, is refused. Numbers too long or too large for any
|
|
27
|
+
attribute are bounded, never an error.
|
|
28
|
+
- `Workbook.parts` gives every part of the package raw (bytes, stream or element tree), with
|
|
29
|
+
its content type, and `Relationship` records for any part's relationships. `xlio.ns` holds
|
|
30
|
+
the namespace, relationship-type and extension-URI constants, with extension URIs in the
|
|
31
|
+
exact case Excel matches.
|
|
32
|
+
- `xlio.patch()` writes changed cells (cached formula results, constants, formulas, array
|
|
33
|
+
ranges) into a copy of a workbook, every other part copied byte for byte; it takes Python
|
|
34
|
+
values (`CellEdit`, `ArrayFill`). A cell given a new value loses its `vm`, since Excel shows
|
|
35
|
+
the rich value a `vm` points to rather than the value beside it.
|
|
36
|
+
- `xlio.check()` checks that Excel would open a package as it is, without a repair, for a
|
|
37
|
+
file handed to another reader: every part's size, checksum and DTD, then every worksheet
|
|
38
|
+
read whole (structure, cells, drawing anchors, conditional formats). It costs about as much
|
|
39
|
+
as reading every cell; `xlio.open()` stays lazy. It refuses the font sizes and font colors
|
|
40
|
+
Excel refuses (a theme index past the theme's 12 colors), as the styles do. A known limit:
|
|
41
|
+
formulas are not parsed, so a file Excel repairs for a formula that does not parse passes.
|
|
42
|
+
- `ReadLimits.max_total_bytes` counts each part once, however often it is read.
|
|
43
|
+
- `ReadLimits.max_cells` bounds the grid area one read of a worksheet covers, and
|
|
44
|
+
`ReadLimits.UNTRUSTED` is a preset for files from people the caller does not trust.
|
|
45
|
+
- The package checks refuse an OLE compound file (an `.xls` workbook or a password-protected
|
|
46
|
+
xlsx) and a binary `.xlsb` workbook with a message saying so, and check every part's stated
|
|
47
|
+
size against the limits before anything is read.
|
|
48
|
+
- A sheet's structure: `Sheet.properties` (tab color, outline directions, code name),
|
|
49
|
+
`Sheet.views` (zoom, gridlines and their color, headings, zeros, panes, selections, the
|
|
50
|
+
active cell as a `CellRef`, taken as Excel takes it, with the text as written kept; a
|
|
51
|
+
selection for a pane the view does not have is refused, as Excel refuses it),
|
|
52
|
+
`Sheet.format` (default sizes) and `Sheet.columns`, read from the part's head up to its
|
|
53
|
+
cells; `Sheet.rows`, gathered by a whole pass of `Sheet.cells()` (otherwise one
|
|
54
|
+
pass that skips the cells); `Sheet.merges` and `Sheet.hyperlinks` with their external
|
|
55
|
+
targets. A head record written after the cells is refused by the pass, as Excel refuses
|
|
56
|
+
it.
|
|
57
|
+
- Sizes are read as Excel reads them: a column width is kept in points modulo 65,536 (a
|
|
58
|
+
negative width wraps; NaN and infinity are 0), a row height is its magnitude and wraps past
|
|
59
|
+
409.5, and the defaults Excel refuses (`defaultColWidth` of 300, `defaultRowHeight` of NaN)
|
|
60
|
+
are refused; the text as written stays beside each (`raw_width`, `raw_height`). A width
|
|
61
|
+
that is not a number is 0 and an empty height is 0; a column range Excel refuses (a `min`
|
|
62
|
+
that is not a number, or past `max`) is refused.
|
|
63
|
+
- Attribute values Excel never writes are read as Excel reads them: a color's `rgb` of fewer
|
|
64
|
+
than eight digits, or not hex, and a tint outside -1 to 1; a `textRotation` past 255; a
|
|
65
|
+
rich-text run's font size (clamped to 1 to 409.55) and a differential format's (refused
|
|
66
|
+
at 0 or past 409.55, also by `check()`). A cell whose style, cell-metadata or
|
|
67
|
+
value-metadata index is past its table is refused, as Excel refuses it.
|
|
68
|
+
- `Workbook.theme` (color scheme, with Excel's theme index order, and font scheme),
|
|
69
|
+
`Workbook.styles.indexed_colors` (a custom palette), `Workbook.views` and
|
|
70
|
+
`Workbook.properties`.
|
|
71
|
+
- `unparsed` on `Workbook` and `Sheet`: every element xlio does not model, whole, so nothing is
|
|
72
|
+
dropped without a trace.
|
|
73
|
+
- `Workbook.styles` in full: custom number formats, fonts, pattern and gradient fills,
|
|
74
|
+
borders, cell formats with their font, fill, border, alignment, protection and named style
|
|
75
|
+
resolved (an index that leads nowhere is `None`), named styles and differential formats.
|
|
76
|
+
A font size is its magnitude, and a size outside 1 to 409 is refused, as Excel refuses it.
|
|
77
|
+
- Tables and filters: `Sheet.tables` (each table part with its columns, totals, calculated
|
|
78
|
+
formulas, style options, filter and sort), `Sheet.autofilter` (values, date groups, custom,
|
|
79
|
+
top 10, dynamic, color and icon filters, button settings) and `Sheet.sort_state`. An absent
|
|
80
|
+
table style option is off, as Excel draws it.
|
|
81
|
+
- Table styles: `Styles.table_styles` (the workbook's own, with their differential formats
|
|
82
|
+
resolved) and `Styles.table_style(name)`, which falls back to `xlio.presets`: Excel's 144
|
|
83
|
+
built-in table and pivot table styles from ECMA-376, shipped as data with Ecma
|
|
84
|
+
International's notice (`NOTICE`).
|
|
85
|
+
- Conditional formats: `Sheet.conditional_formats`, every rule typed (cell value, expression,
|
|
86
|
+
text, blank, error, date, top and bottom, average, unique and duplicate rules, color scales,
|
|
87
|
+
data bars, icon sets) with its formulas and its differential format, and each rule Excel 2010
|
|
88
|
+
extended joined with its extension rule by `x14:id` (`Rule.x14`: data bar borders, direction,
|
|
89
|
+
negative colors and axis, new and custom icon sets). Rules that exist only in the extension are
|
|
90
|
+
formats of their own. The extension is read only under the URI Excel reads, compared exactly.
|
|
91
|
+
`Sheet.extensions` lists every `extLst` entry with its URI as written. A format whose
|
|
92
|
+
`sqref` is not a list of cells and ranges is dropped, as Excel drops it; one of a type
|
|
93
|
+
outside the schema or with a `dxfId` past the table, which Excel repairs, is refused by
|
|
94
|
+
`check()`.
|
|
95
|
+
- Drawings: `Sheet.drawing` gives the sheet's anchored objects in z-order (file order, across
|
|
96
|
+
anchor kinds and through `AlternateContent`, whose branch is chosen as Excel is captured
|
|
97
|
+
choosing it and kept raw beside), each with its anchor in EMU, kind, name, alternative text
|
|
98
|
+
and hidden flag; pictures with their image part and content type, SVG image, crop, rotation,
|
|
99
|
+
flips and outline, and a linked picture's target, which is never followed. A two-cell anchor
|
|
100
|
+
that ends before it starts, by whole cells on either axis, is read as Excel repairs it (its
|
|
101
|
+
corners swapped on that axis, `Anchor.repaired`) and refused by `check()`; offsets reversed
|
|
102
|
+
within one cell are kept, as Excel keeps them.
|
|
103
|
+
`Sheet.background` gives the background picture's part.
|
|
104
|
+
- VML: `Sheet.legacy_drawing` gives the VML part's bytes and its shapes (note boxes, form
|
|
105
|
+
controls) read by a bounded extractor, since VML is often not well-formed XML: the anchor,
|
|
106
|
+
visibility, cell, style, fill, stroke and shadow. `ReadLimits.max_vml_bytes` bounds it.
|
|
107
|
+
- Notes and threaded comments: `Sheet.comments` (cell, author, rich text),
|
|
108
|
+
`Sheet.threaded_comments` (thread, author, date, resolved) and `Workbook.persons`.
|
|
109
|
+
- Printing: `Sheet.row_breaks` and `Sheet.column_breaks`, `Sheet.page_setup` (paper, orientation,
|
|
110
|
+
scale and fitting, page numbers, margins, print options, headers and footers), and
|
|
111
|
+
`Sheet.print_area` and `Sheet.print_titles` from the defined names scoped to the sheet by its
|
|
112
|
+
place in `<sheets>` as written (`Sheet.position`: hidden sheets and sheets without a part
|
|
113
|
+
count, as `localSheetId` and `activeTab` count them), each range as written, with the reason
|
|
114
|
+
a part was not usable (`#REF!`, a formula, another sheet's range).
|
|
115
|
+
- `Workbook.external_links`: the parts of the workbook's links to other workbooks.
|
|
116
|
+
- Rich values: `Workbook.rich_values` gives the rich value behind each value-metadata index (a
|
|
117
|
+
cell's `vm`): a picture placed in a cell as an `ImageValue` (its image part, alternative
|
|
118
|
+
text, origin and sizing as stored; the cell itself caches `#VALUE!`), anything else (data
|
|
119
|
+
types, errors) as a raw `RichValue`.
|
|
120
|
+
- Rich text: `Workbook.rich_strings` (runs with their fonts, phonetic guides and their
|
|
121
|
+
properties) and `Sheet.cells(rich=True)`, which gives shared and inline strings their runs
|
|
122
|
+
(`Cell.rich`); `Cell.phonetic` for the `ph` flag.
|
|
123
|
+
- Each rule read from Excel's behavior rests on a capture from Excel for Mac, with its probe
|
|
124
|
+
(`CAPTURING.md`), and the tests read workbooks Excel saved.
|
|
125
|
+
|
|
126
|
+
[Unreleased]: https://github.com/sheetmill/xlio/compare/v0.1.0...HEAD
|
|
127
|
+
[0.1.0]: https://github.com/sheetmill/xlio/releases/tag/v0.1.0
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
## Issues and bug reports
|
|
4
|
+
|
|
5
|
+
Bug reports are welcome. The most useful report includes a small workbook that shows the
|
|
6
|
+
problem (or the part of it that matters, such as one sheet's XML), what Excel does with it, what
|
|
7
|
+
xlio does, and your Excel version and platform. Please do not attach a workbook that holds
|
|
8
|
+
anyone's private data.
|
|
9
|
+
|
|
10
|
+
## Pull requests
|
|
11
|
+
|
|
12
|
+
The project is just getting started, so pull requests aren't being accepted yet while
|
|
13
|
+
the API, release process and review practices settle. This will be
|
|
14
|
+
revisited after the first releases. In the meantime, if you have a change in mind,
|
|
15
|
+
please open an issue describing it.
|
|
16
|
+
|
|
17
|
+
When pull requests open, these rules will apply:
|
|
18
|
+
|
|
19
|
+
- AI-assisted contributions must be disclosed in the pull request description.
|
|
20
|
+
- The contributor must understand every line of the change and be able to explain it when asked.
|
|
21
|
+
- Undisclosed or unexplained AI-generated pull requests may be closed without review.
|
|
22
|
+
|
|
23
|
+
## Setting up
|
|
24
|
+
|
|
25
|
+
Python 3.11 or later. Either route installs the package in editable mode with the development
|
|
26
|
+
and documentation tools:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
uv sync --group docs
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
python -m venv .venv && source .venv/bin/activate
|
|
34
|
+
pip install -e . --group dev --group docs # needs pip 25.1 or later
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`uv.lock` pins the versions CI tests with, and `uv sync` installs exactly those versions.
|
|
38
|
+
pip and other tools ignore it and resolve the latest versions the dependency groups in
|
|
39
|
+
`pyproject.toml` allow, which is normally fine but is not what CI runs.
|
|
40
|
+
|
|
41
|
+
## Checks to run before proposing a change
|
|
42
|
+
|
|
43
|
+
All of these must pass. CI runs the same set on Python 3.11 to 3.14, plus a run without
|
|
44
|
+
openpyxl, a development dependency. Prefix each with `uv run` on the uv route.
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
pytest
|
|
48
|
+
ruff check .
|
|
49
|
+
ruff format --check .
|
|
50
|
+
mypy
|
|
51
|
+
sphinx-build -n -W docs docs/_build/html # the strict documentation build
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
`pytest --tier slow`, as CI runs it, adds the costly cases. Tests that feed crafted packages to
|
|
55
|
+
the reader run in a child process under a memory limit (`tests/watchdog.py`), so a guard that
|
|
56
|
+
regresses fails the test instead of exhausting the machine.
|
|
57
|
+
|
|
58
|
+
## Expected results
|
|
59
|
+
|
|
60
|
+
What the reader accepts, refuses and reads is what Excel 16 for Mac does with the same file.
|
|
61
|
+
Such behavior is captured from Excel, never written from memory or taken from another program
|
|
62
|
+
(`CAPTURING.md`). Captured files are never edited by hand.
|
|
63
|
+
|
|
64
|
+
## Commit messages
|
|
65
|
+
|
|
66
|
+
A commit made with the help of an AI tool ends with the trailer
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
Assisted-by: <tool>:<model ID>
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
as its last line, after a blank line, naming the tool and the exact model, for example
|
|
73
|
+
`Assisted-by: Claude Code:claude-opus-5-5`. One trailer per tool and model used.
|
|
74
|
+
|
|
75
|
+
## How this project's own commits are made
|
|
76
|
+
|
|
77
|
+
Most of the code is written with Claude Code, reviewed before each commit and tested against
|
|
78
|
+
results captured from real Excel. Every such commit carries the git trailer
|
|
79
|
+
`Assisted-by: Claude Code:<model ID>`, so the history records which model took part.
|
xlio-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ethan Post
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
xlio-0.1.0/NOTICE
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
xlio includes data from a third party:
|
|
2
|
+
|
|
3
|
+
src/xlio/data/presetTableStyles.xml
|
|
4
|
+
The definitions of the built-in table and pivot table styles, from ECMA-376 Office Open XML
|
|
5
|
+
File Formats, Part 1, 5th edition (December 2016), byte for byte as Ecma International
|
|
6
|
+
publishes it: the file presetTableStyles.xml inside OfficeOpenXML-SpreadsheetMLStyles.zip,
|
|
7
|
+
inside
|
|
8
|
+
https://ecma-international.org/wp-content/uploads/ECMA-376-1_5th_edition_december_2016.zip
|
|
9
|
+
SHA-256 74c6cf73d551bb2bd33a51690d4922095260b6647b2a38fcbc0d6da6c6275d7e
|
|
10
|
+
It is included under Ecma International's text copyright policy, version 3 (December 2025),
|
|
11
|
+
which permits copying it into a standard conformant product provided that the notice below
|
|
12
|
+
is included on all such copies:
|
|
13
|
+
https://www.ecma-international.org/policies/by-ipr/ecma-text-copyright-policy/
|
|
14
|
+
Its default copyright notice follows.
|
|
15
|
+
|
|
16
|
+
----------------------------------------------------------------------------------------------
|
|
17
|
+
|
|
18
|
+
COPYRIGHT NOTICE
|
|
19
|
+
© Ecma International
|
|
20
|
+
By obtaining and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions.
|
|
21
|
+
This document may be copied, published and distributed to others, and certain derivative works of it may be prepared, copied, published, and distributed, in whole or in part, provided that the above copyright notice and this Copyright License and Disclaimer are included on all such copies and derivative works. The only derivative works that are permissible under this Copyright License and Disclaimer are:
|
|
22
|
+
(i) works which incorporate all or portion of this document for the purpose of providing commentary or explanation (such as an annotated version of the document),
|
|
23
|
+
(ii) works which incorporate all or portion of this document for the purpose of incorporating features that provide accessibility,
|
|
24
|
+
(iii) translations of this document into languages other than English and into different formats and
|
|
25
|
+
(iv) works by making use of this specification in standard conformant products by implementing (e.g. by copy and paste wholly or partly) the functionality therein.
|
|
26
|
+
However, the content of this document itself may not be modified in any way, including by removing the copyright notice or references to Ecma International, except as required to translate it into languages other than English or into a different format.
|
|
27
|
+
The official version of an Ecma International document is the English language version on the Ecma International website. In the event of discrepancies between a translated version and the official version, the official version shall govern.
|
|
28
|
+
The limited permissions granted above are perpetual and will not be revoked by Ecma International or its successors or assigns.
|
|
29
|
+
This document and the information contained herein is provided on an “AS IS” basis and ECMA INTERNATIONAL DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
|
xlio-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: xlio
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Internal xlsx reader and writer of the sheetmill project, extracted from xlrecalc; not intended for direct use.
|
|
5
|
+
Project-URL: Homepage, https://github.com/sheetmill/xlio
|
|
6
|
+
Project-URL: Documentation, https://xlio.readthedocs.io
|
|
7
|
+
Project-URL: Source, https://github.com/sheetmill/xlio
|
|
8
|
+
Project-URL: Changelog, https://github.com/sheetmill/xlio/blob/main/CHANGELOG.md
|
|
9
|
+
Project-URL: Issues, https://github.com/sheetmill/xlio/issues
|
|
10
|
+
Author: Ethan Post
|
|
11
|
+
License-Expression: MIT AND LicenseRef-Ecma-Text-Copyright-Policy
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
License-File: NOTICE
|
|
14
|
+
Keywords: excel,ooxml,reader,spreadsheet,writer,xlsm,xlsx
|
|
15
|
+
Classifier: Development Status :: 3 - Alpha
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
24
|
+
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
|
|
25
|
+
Classifier: Typing :: Typed
|
|
26
|
+
Requires-Python: >=3.11
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# xlio
|
|
30
|
+
|
|
31
|
+
**xlio is an internal package of the sheetmill project.** It reads xlsx files as Excel reads
|
|
32
|
+
them and changes their cells without disturbing anything else. It was extracted from
|
|
33
|
+
[xlrecalc](https://github.com/sheetmill/xlrecalc), whose own reader and writer it began as, to be
|
|
34
|
+
shared by the sheetmill packages. It is not intended for direct use: its API may change in any
|
|
35
|
+
minor release (0.1 to 0.2) without the deprecation period the public sheetmill packages give,
|
|
36
|
+
while patch releases only fix bugs and keep the API. If you depend on it anyway, pin a minor
|
|
37
|
+
version (for example `xlio==0.1.*`).
|
|
38
|
+
|
|
39
|
+
It is written in pure Python with the standard library only. The reader checks a package before
|
|
40
|
+
it parses anything (part count and sizes, compression methods, encryption, names used twice, a
|
|
41
|
+
DTD in any part) and refuses what Excel refuses; the writer copies every part it does not change
|
|
42
|
+
byte for byte and rewrites only the cells it is given.
|
|
43
|
+
|
|
44
|
+
xlio is part of the [sheetmill](https://github.com/sheetmill) project, with
|
|
45
|
+
[xlformat](https://github.com/sheetmill/xlformat), which applies Excel number formats,
|
|
46
|
+
[xlrecalc](https://github.com/sheetmill/xlrecalc), which recalculates workbooks, and
|
|
47
|
+
[sheetpeek](https://github.com/sheetmill/sheetpeek), which shows workbooks as Excel does.
|
|
48
|
+
|
|
49
|
+
## Development
|
|
50
|
+
|
|
51
|
+
`uv sync --group docs` then `uv run pytest`; `CONTRIBUTING.md` has the pip route, the full set of
|
|
52
|
+
checks and the commit conventions.
|
|
53
|
+
|
|
54
|
+
Most of the code is written with Claude Code, reviewed before each commit and tested against
|
|
55
|
+
results captured from Excel; see `CONTRIBUTING.md`.
|
|
56
|
+
|
|
57
|
+
## License
|
|
58
|
+
|
|
59
|
+
The code is under the MIT license (`LICENSE`). `src/xlio/data/presetTableStyles.xml`, the
|
|
60
|
+
built-in table and pivot table styles from ECMA-376, is under Ecma International's text
|
|
61
|
+
copyright policy, as published by Ecma; see `NOTICE`.
|
xlio-0.1.0/README.md
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# xlio
|
|
2
|
+
|
|
3
|
+
**xlio is an internal package of the sheetmill project.** It reads xlsx files as Excel reads
|
|
4
|
+
them and changes their cells without disturbing anything else. It was extracted from
|
|
5
|
+
[xlrecalc](https://github.com/sheetmill/xlrecalc), whose own reader and writer it began as, to be
|
|
6
|
+
shared by the sheetmill packages. It is not intended for direct use: its API may change in any
|
|
7
|
+
minor release (0.1 to 0.2) without the deprecation period the public sheetmill packages give,
|
|
8
|
+
while patch releases only fix bugs and keep the API. If you depend on it anyway, pin a minor
|
|
9
|
+
version (for example `xlio==0.1.*`).
|
|
10
|
+
|
|
11
|
+
It is written in pure Python with the standard library only. The reader checks a package before
|
|
12
|
+
it parses anything (part count and sizes, compression methods, encryption, names used twice, a
|
|
13
|
+
DTD in any part) and refuses what Excel refuses; the writer copies every part it does not change
|
|
14
|
+
byte for byte and rewrites only the cells it is given.
|
|
15
|
+
|
|
16
|
+
xlio is part of the [sheetmill](https://github.com/sheetmill) project, with
|
|
17
|
+
[xlformat](https://github.com/sheetmill/xlformat), which applies Excel number formats,
|
|
18
|
+
[xlrecalc](https://github.com/sheetmill/xlrecalc), which recalculates workbooks, and
|
|
19
|
+
[sheetpeek](https://github.com/sheetmill/sheetpeek), which shows workbooks as Excel does.
|
|
20
|
+
|
|
21
|
+
## Development
|
|
22
|
+
|
|
23
|
+
`uv sync --group docs` then `uv run pytest`; `CONTRIBUTING.md` has the pip route, the full set of
|
|
24
|
+
checks and the commit conventions.
|
|
25
|
+
|
|
26
|
+
Most of the code is written with Claude Code, reviewed before each commit and tested against
|
|
27
|
+
results captured from Excel; see `CONTRIBUTING.md`.
|
|
28
|
+
|
|
29
|
+
## License
|
|
30
|
+
|
|
31
|
+
The code is under the MIT license (`LICENSE`). `src/xlio/data/presetTableStyles.xml`, the
|
|
32
|
+
built-in table and pivot table styles from ECMA-376, is under Ecma International's text
|
|
33
|
+
copyright policy, as published by Ecma; see `NOTICE`.
|
|
File without changes
|