xlformat 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.
- xlformat-0.1.0/.gitignore +23 -0
- xlformat-0.1.0/ARCHITECTURE.md +592 -0
- xlformat-0.1.0/CAPTURING.md +514 -0
- xlformat-0.1.0/CHANGELOG.md +46 -0
- xlformat-0.1.0/CONTRIBUTING.md +81 -0
- xlformat-0.1.0/LICENSE +21 -0
- xlformat-0.1.0/PKG-INFO +201 -0
- xlformat-0.1.0/QUIRKS.md +124 -0
- xlformat-0.1.0/README.md +174 -0
- xlformat-0.1.0/capture/__init__.py +4 -0
- xlformat-0.1.0/capture/__main__.py +8 -0
- xlformat-0.1.0/capture/build.py +129 -0
- xlformat-0.1.0/capture/build_probe_workbook.py +120 -0
- xlformat-0.1.0/capture/capture.py +276 -0
- xlformat-0.1.0/capture/capture_template.applescript +105 -0
- xlformat-0.1.0/capture/cases.py +1569 -0
- xlformat-0.1.0/capture/convert_2023.py +58 -0
- xlformat-0.1.0/capture/diff_captures.py +83 -0
- xlformat-0.1.0/capture/formula_diff.py +64 -0
- xlformat-0.1.0/capture/glyph_fit.py +151 -0
- xlformat-0.1.0/capture/invalid.py +99 -0
- xlformat-0.1.0/capture/probe_behavior.applescript +125 -0
- xlformat-0.1.0/capture/probe_color_bulk.applescript +57 -0
- xlformat-0.1.0/capture/probe_file.applescript +34 -0
- xlformat-0.1.0/capture/probe_file_many.applescript +44 -0
- xlformat-0.1.0/capture/probe_timing.applescript +55 -0
- xlformat-0.1.0/capture/retier.py +63 -0
- xlformat-0.1.0/capture/rounding_models.py +103 -0
- xlformat-0.1.0/capture/schema.py +113 -0
- xlformat-0.1.0/capture/tiers.py +45 -0
- xlformat-0.1.0/docs/_templates/page.html +15 -0
- xlformat-0.1.0/docs/_templates/search.html +96 -0
- xlformat-0.1.0/docs/api.md +39 -0
- xlformat-0.1.0/docs/changelog.md +2 -0
- xlformat-0.1.0/docs/conf.py +52 -0
- xlformat-0.1.0/docs/index.md +38 -0
- xlformat-0.1.0/docs/quirks.md +21 -0
- xlformat-0.1.0/docs/testing.md +84 -0
- xlformat-0.1.0/docs/usage.md +99 -0
- xlformat-0.1.0/docs/width.md +78 -0
- xlformat-0.1.0/pagefind.yml +7 -0
- xlformat-0.1.0/pyproject.toml +111 -0
- xlformat-0.1.0/src/xlformat/__init__.py +100 -0
- xlformat-0.1.0/src/xlformat/_assemble.py +134 -0
- xlformat-0.1.0/src/xlformat/_datetime.py +253 -0
- xlformat-0.1.0/src/xlformat/_errors.py +12 -0
- xlformat-0.1.0/src/xlformat/_fraction.py +186 -0
- xlformat-0.1.0/src/xlformat/_glyphs_calibri.py +595 -0
- xlformat-0.1.0/src/xlformat/_measure.py +100 -0
- xlformat-0.1.0/src/xlformat/_number.py +300 -0
- xlformat-0.1.0/src/xlformat/_palette.py +36 -0
- xlformat-0.1.0/src/xlformat/_parser.py +818 -0
- xlformat-0.1.0/src/xlformat/_quirks.py +39 -0
- xlformat-0.1.0/src/xlformat/_render.py +281 -0
- xlformat-0.1.0/src/xlformat/_text.py +33 -0
- xlformat-0.1.0/src/xlformat/_values.py +151 -0
- xlformat-0.1.0/src/xlformat/py.typed +0 -0
- xlformat-0.1.0/tests/captures/capture2023.tsv.gz +0 -0
- xlformat-0.1.0/tests/captures/capture2023_sample.tsv.gz +0 -0
- xlformat-0.1.0/tests/captures/capture2026.tsv.gz +0 -0
- xlformat-0.1.0/tests/captures/clock_boundaries.tsv +198 -0
- xlformat-0.1.0/tests/captures/clock_formulas.tsv.gz +0 -0
- xlformat-0.1.0/tests/captures/colors.tsv +182 -0
- xlformat-0.1.0/tests/captures/conditions_rounding.tsv +199 -0
- xlformat-0.1.0/tests/captures/date1904.tsv +348 -0
- xlformat-0.1.0/tests/captures/datetime.tsv.gz +0 -0
- xlformat-0.1.0/tests/captures/fraction.tsv.gz +0 -0
- xlformat-0.1.0/tests/captures/fraction_random.tsv.gz +0 -0
- xlformat-0.1.0/tests/captures/fraction_threshold.tsv.gz +0 -0
- xlformat-0.1.0/tests/captures/fraction_ties.tsv +249 -0
- xlformat-0.1.0/tests/captures/lone_zero.tsv +108 -0
- xlformat-0.1.0/tests/captures/measure10.measure.tsv +525 -0
- xlformat-0.1.0/tests/captures/measure10.tsv +13 -0
- xlformat-0.1.0/tests/captures/measure11.measure.tsv +525 -0
- xlformat-0.1.0/tests/captures/measure11.tsv +13 -0
- xlformat-0.1.0/tests/captures/measure12.measure.tsv +525 -0
- xlformat-0.1.0/tests/captures/measure12.tsv +13 -0
- xlformat-0.1.0/tests/captures/measure14.measure.tsv +525 -0
- xlformat-0.1.0/tests/captures/measure14.tsv +13 -0
- xlformat-0.1.0/tests/captures/measure16.measure.tsv +525 -0
- xlformat-0.1.0/tests/captures/measure16.tsv +13 -0
- xlformat-0.1.0/tests/captures/measure9.measure.tsv +525 -0
- xlformat-0.1.0/tests/captures/measure9.tsv +13 -0
- xlformat-0.1.0/tests/captures/numeric_core.tsv.gz +0 -0
- xlformat-0.1.0/tests/captures/numeric_core_width.tsv.gz +0 -0
- xlformat-0.1.0/tests/captures/parser_check.tsv.gz +0 -0
- xlformat-0.1.0/tests/captures/rounding_15digit.tsv +147 -0
- xlformat-0.1.0/tests/captures/scientific.tsv.gz +0 -0
- xlformat-0.1.0/tests/captures/selection_fallback.tsv +52 -0
- xlformat-0.1.0/tests/captures/space_fill10.tsv +213 -0
- xlformat-0.1.0/tests/captures/space_fill11.tsv +213 -0
- xlformat-0.1.0/tests/captures/space_fill12.tsv +213 -0
- xlformat-0.1.0/tests/captures/space_fill14.tsv +213 -0
- xlformat-0.1.0/tests/captures/space_fill16.tsv +213 -0
- xlformat-0.1.0/tests/captures/space_fill9.tsv +213 -0
- xlformat-0.1.0/tests/captures/text_overflow.tsv +61 -0
- xlformat-0.1.0/tests/captures/width_fill.tsv.gz +0 -0
- xlformat-0.1.0/tests/captures/width_general.measure.tsv +60 -0
- xlformat-0.1.0/tests/captures/width_general.tsv.gz +0 -0
- xlformat-0.1.0/tests/captures/width_general14.measure.tsv +60 -0
- xlformat-0.1.0/tests/captures/width_general14.tsv.gz +0 -0
- xlformat-0.1.0/tests/conftest.py +20 -0
- xlformat-0.1.0/tests/test_captures.py +205 -0
- xlformat-0.1.0/tests/test_cell.py +49 -0
- xlformat-0.1.0/tests/test_datetime.py +58 -0
- xlformat-0.1.0/tests/test_examples.py +24 -0
- xlformat-0.1.0/tests/test_measure.py +57 -0
- xlformat-0.1.0/tests/test_package.py +5 -0
- xlformat-0.1.0/tests/test_parser.py +237 -0
- xlformat-0.1.0/tests/test_values.py +88 -0
|
@@ -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
|
+
# documentation build (Sphinx HTML and the Pagefind index inside it)
|
|
13
|
+
docs/_build/
|
|
14
|
+
node_modules/
|
|
15
|
+
|
|
16
|
+
# macOS and editors
|
|
17
|
+
.DS_Store
|
|
18
|
+
.idea/
|
|
19
|
+
.vscode/
|
|
20
|
+
*.sublime-workspace
|
|
21
|
+
|
|
22
|
+
# generated capture data (workbooks, probe output); the TSVs under tests/captures are committed
|
|
23
|
+
capture/build/
|
|
@@ -0,0 +1,592 @@
|
|
|
1
|
+
# Architecture
|
|
2
|
+
|
|
3
|
+
Companions: `CAPTURING.md` (test data) and `QUIRKS.md` (Excel evidence per quirk). Callers with
|
|
4
|
+
error cells: see section 5.
|
|
5
|
+
|
|
6
|
+
## 1. Scope and principles
|
|
7
|
+
|
|
8
|
+
`xlformat` turns a value and an Excel number-format string into the text Excel displays.
|
|
9
|
+
Pure Python, standard library only, Python 3.11+. Priorities in order: match Excel 16 for Mac,
|
|
10
|
+
then speed, then code quality. Excel's behavior is the specification; ECMA-376 section 18.8.31
|
|
11
|
+
is a secondary reference and is wrong or silent in places where Excel is definite.
|
|
12
|
+
|
|
13
|
+
Out of scope for 0.1: locales other than en-US (format codes are parsed, names are English,
|
|
14
|
+
`[$-x-sysdate]` renders the en-US long date), fonts other than Calibri in Excel mode, conditional formatting,
|
|
15
|
+
right-to-left and East Asian calendar codes (`e`, `g`, `b`), cell styles beyond what the format
|
|
16
|
+
string itself implies.
|
|
17
|
+
|
|
18
|
+
## 2. Pipeline
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
format string ──parse──▶ NumberFormat (cached)
|
|
22
|
+
│ sections: tuple[Section, ...]
|
|
23
|
+
value ──normalize──▶ Value │
|
|
24
|
+
(kind, serial/text)─┴─select section──▶ pieces ──assemble(width, measure)──▶ str | FormattedCell
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
1. **Parse** (`_parser.py`): split into at most four sections on `;` outside quotes and escapes;
|
|
28
|
+
tokenize each section; classify it; compile it into a `Section` dataclass. Parsing is pure,
|
|
29
|
+
raises `FormatError` only when Excel itself has no rendering for the string (section 11), and
|
|
30
|
+
is cached (`functools.lru_cache`, size 1024) keyed on the string alone. Quirks bind at format
|
|
31
|
+
time, not parse time: none of the three quirks affects parsing.
|
|
32
|
+
2. **Normalize the value** (`_values.py`): every input becomes `Value(kind, number, text)` where
|
|
33
|
+
`kind` is `NUMBER`, `TEXT`, `BOOL`, `EMPTY`; numbers are `Decimal`. See section 5.
|
|
34
|
+
3. **Select the section** (section 4).
|
|
35
|
+
4. **Render** (`_number.py`, `_datetime.py`, `_text.py`): the section renderer returns a list of
|
|
36
|
+
pieces: literal text, digit text, and markers (`Fill(char)`, `Pad(char)`).
|
|
37
|
+
5. **Assemble** (`_assemble.py`): compute the unconstrained text, then apply the width decision
|
|
38
|
+
(overflow, General reduction, fill, pad) through a measure function (section 8), produce the
|
|
39
|
+
string and, for `format_cell()`, the `FormattedCell` record with color and alignment.
|
|
40
|
+
|
|
41
|
+
## 3. Format model
|
|
42
|
+
|
|
43
|
+
Tokens per section, produced by one regex pass (the old tokenizer approach, kept):
|
|
44
|
+
|
|
45
|
+
| token | notes |
|
|
46
|
+
|---|---|
|
|
47
|
+
| `"..."`, `\x`, and the always-literal characters `$ - + ( ) : space ! ^ & ~ { } < > =` | literals; `\` and `"` are consumed |
|
|
48
|
+
| `[Red]` ... `[Color56]` | section color; case-insensitive; `[Color 3]` with a space is accepted and kept as `[Color3]` (`CAPTURING.md` §2 item 9) |
|
|
49
|
+
| `[<=100]`, `[<>0]`, `[=1]` | condition, sections 1 and 2 only; a condition in the text section is an error |
|
|
50
|
+
| `[$€-x-euro2]`, `[$-409]`, `[$-F800]` | currency symbol (emitted as a literal) and locale tag (recorded, not applied) |
|
|
51
|
+
| `[h]`, `[mm]`, `[ss]` and longer runs | elapsed time; at most one per section; nothing may precede it except literals |
|
|
52
|
+
| `General` (case-insensitive), `@` | General placeholder (allowed in numeric and text sections, with literals around it); text placeholder |
|
|
53
|
+
| `0 # ?`, `.`, `,`, `%`, `E+ E-`, `/` | numeric codes. Lower-case `e+`/`e-` after digits make Excel refuse the file (`FormatError`, `CAPTURING.md` §2 item 9). A second `.` is a literal inside the decimal digits (`0.0.0` shows `1234.5.7`). `%` between mantissa and `E` is a literal and does not scale (`0%E+0` shows `1%E+3`) |
|
|
54
|
+
| `y m d h s e`, `AM/PM`, `A/P` runs | date/time codes, case-insensitive, normalized (`yyy`→`yyyy`, `mmmmmm`→`mmmm`, `ddddd`→`dddd`, `sss`→`ss`). `e` is a four-digit year in en-US (`e+` shows `1903+` for serial 1234) |
|
|
55
|
+
| `_x`, `*x` | pad (width of `x`, one space in text output) and fill (repeat `x`). Excel accepts two fills in a file and honors the last one (`*-0*-` shows `1235` then dashes); the dialog refuses it |
|
|
56
|
+
| anything else | literal |
|
|
57
|
+
|
|
58
|
+
Classification of a section, in this order: contains a date/time code → **datetime** (numeric
|
|
59
|
+
codes are then errors, except the `0` runs of `s.0`, `s.00`, `s.000`); contains `/` between digit
|
|
60
|
+
runs → **fraction**; contains `E+`/`E-` after a digit run → **scientific**; contains `0 # ? .` →
|
|
61
|
+
**number**; contains `@` → **text**; only `General` and literals → **general**; nothing → **empty**.
|
|
62
|
+
|
|
63
|
+
Compiled `Section` fields (frozen dataclass): `kind`, `color`, `condition` (op, Decimal),
|
|
64
|
+
`locale`, `pieces` (literals and markers), and per kind: integer placeholders with their
|
|
65
|
+
inter-digit literals, decimal placeholders, grouping flag, scale (10^-3 per trailing comma),
|
|
66
|
+
percent count, exponent placeholders and sign style, fraction numerator/denominator placeholders
|
|
67
|
+
or fixed denominator, resolved date fields (`m` already resolved to month or minute, `h` already
|
|
68
|
+
knows whether AM/PM is present, fractional-second digit count).
|
|
69
|
+
|
|
70
|
+
`m` resolution (from the 2023 prototype, verified by the Excel captures): scanning left to right, an `m` run
|
|
71
|
+
is a minute if an `h` run precedes it since the previous `m` run; otherwise a minute if the next
|
|
72
|
+
date/time code is a second; otherwise a month. The general rule is that `m` next to `h` or `s` is
|
|
73
|
+
a minute.
|
|
74
|
+
|
|
75
|
+
Comma rules (from the 2023 prototype's docstring, which the Excel captures confirm): commas between digit
|
|
76
|
+
placeholders before the decimal point turn on grouping; commas immediately after the last digit
|
|
77
|
+
placeholder scale by a thousand each; commas before any placeholder, or after a literal, are
|
|
78
|
+
literals; commas after the decimal point are dropped.
|
|
79
|
+
|
|
80
|
+
## 4. Section selection
|
|
81
|
+
|
|
82
|
+
Given the normalized value and the compiled sections (n = 1..4):
|
|
83
|
+
|
|
84
|
+
- **Text and booleans** use the text section if there is one (the fourth, or the last section if
|
|
85
|
+
it contains `@`); otherwise the text is displayed as is (General). Booleans render as `TRUE` /
|
|
86
|
+
`FALSE` through that path, so `_(@_)` gives `' TRUE '`.
|
|
87
|
+
- **Empty** (`None`) renders as `''`.
|
|
88
|
+
- **Numbers**, conditions present (`_render.py: select`; suites `numeric_core`,
|
|
89
|
+
`conditions_rounding`, `lone_zero`, `selection_fallback`): the condition sees the unrounded
|
|
90
|
+
value (`[=0]"zero";0` shows `0` for 0.001). A conditioned first section applies when it holds
|
|
91
|
+
and keeps the sign (`-1` under `[<=9999999]###-####;...` gives `--1`) unless the condition can
|
|
92
|
+
only hold for negatives (`<` with bound ≤ 0, `<=` with bound < 0), which drops it like the
|
|
93
|
+
implicit negative section (`[<0]0.0` shows `1.0` for -1). When it fails: with one section,
|
|
94
|
+
General (sign dropped when the bound is negative; a `General` body shows `#`); with two, an
|
|
95
|
+
unconditioned second section is "everything else" with the sign kept (`[>100]0.00;0` shows
|
|
96
|
+
`-1`) unless the failing range holds only non-positive values (`[>0]0;"neg"` shows `neg`), and
|
|
97
|
+
a conditioned second section applies when it holds or else the value shows a `#` run
|
|
98
|
+
(`[<=0]0;[>1]0` with 0.3); with three, an unconditioned second section is the negative one
|
|
99
|
+
(`[>1]0;0;0.0` shows `2` for -2) and the third takes the rest (`0.3`, `0.0`), while a failing
|
|
100
|
+
conditioned second section sends the value to the third with its sign. An unconditioned first
|
|
101
|
+
section before a conditioned second takes positives only: `0;[>1]0` shows `#` for 0 and
|
|
102
|
+
negatives, `0;[>1]0;0.0` shows `-0.3` and `0.0`. A negative rendered with its sign whose
|
|
103
|
+
magnitude renders as zero is rendered again as the positive magnitude, from section selection
|
|
104
|
+
onward (`[<=0]0` shows `0.001` for -0.001, `[<=0.1]0` shows `0.3` for -0.3, `[<=0.5]0` shows
|
|
105
|
+
`0`; `[<0]0` shows `0` because its sign was already dropped).
|
|
106
|
+
- **Numbers**, no conditions: 1 section → all values, with an automatic leading `-` for
|
|
107
|
+
negatives placed before the whole section text (`x( General )` gives `-x( 1234 )`); 2 sections
|
|
108
|
+
→ `>= 0` and `< 0`, the negative section renders the absolute value and adds no sign; 3 or 4 →
|
|
109
|
+
`> 0`, `< 0`, `= 0`. The sign test uses the unrounded value: `-0.4` under `0;(0)` gives `(0)`,
|
|
110
|
+
while under the single section `0` it gives `0` (a negative that rounds to zero drops the sign).
|
|
111
|
+
- An empty section renders nothing (this is how `0;;` hides negatives), except that an empty first
|
|
112
|
+
section, or an empty section carrying a color or condition, behaves as General.
|
|
113
|
+
- Values a datetime section cannot show (negative, or `>= 2958466` after rounding to the displayed
|
|
114
|
+
precision) render as overflow (section 8).
|
|
115
|
+
|
|
116
|
+
## 5. Value model
|
|
117
|
+
|
|
118
|
+
Accepted inputs and their normalization:
|
|
119
|
+
|
|
120
|
+
| input | becomes |
|
|
121
|
+
|---|---|
|
|
122
|
+
| `bool` (checked first) | `BOOL`; text `TRUE`/`FALSE` |
|
|
123
|
+
| `int`, `float`, `Decimal`, objects with `__index__` | `NUMBER`, `Decimal`; floats via exact `Decimal(float)` (NaN and infinities raise `ValueError`) |
|
|
124
|
+
| `str` | `TEXT` |
|
|
125
|
+
| `None` | `EMPTY` |
|
|
126
|
+
| `datetime.datetime`, `date` | `NUMBER`: serial under the selected date system (the Lotus shift applies to 1900-01-01..1900-02-28 so that round-tripping agrees with Excel) |
|
|
127
|
+
| `datetime.time` | `NUMBER`: fraction of a day |
|
|
128
|
+
| `datetime.timedelta` | `NUMBER`: days as a fraction (for elapsed formats) |
|
|
129
|
+
| anything else | `TypeError` |
|
|
130
|
+
|
|
131
|
+
**Decimal, not float**, is the working type: Excel's display is a decimal process (15
|
|
132
|
+
significant digits, half-up rounding at the displayed place) applied to a binary double, and
|
|
133
|
+
`Decimal(float)` reproduces the double exactly so the decimal process can be applied faithfully.
|
|
134
|
+
`float` arithmetic would reintroduce the errors the 2023 prototype spent effort avoiding. Performance
|
|
135
|
+
cost is acceptable (a few microseconds per value) and is measured, not assumed.
|
|
136
|
+
|
|
137
|
+
Precision rules applied at normalization, each a quirk (section 9):
|
|
138
|
+
- `fifteen_digit_precision`: round the magnitude to 15 significant digits (tie rule below).
|
|
139
|
+
Evidence: `0.1234512345123456` under thirty decimals shows `0.123451234512346000...`.
|
|
140
|
+
- The tie rule (`CAPTURING.md` §2 items 8, 15 and 16; `QUIRKS.md`): the exact binary value is
|
|
141
|
+
rounded to 15 significant digits with **ties down** (`12345123451234.25` under `0.0` shows
|
|
142
|
+
`….2`, `123451234512345.5` under `0` shows `…345`, `….515625` shows `…346`). Zero failures on
|
|
143
|
+
69,690 numeric captured rows. An earlier extra step at or above 1e14 ("round to 16 digits
|
|
144
|
+
first") fitted the 16-digit number texts openpyxl had written, not Excel; the formula-written
|
|
145
|
+
rows removed it. The 2023 prototype's "exact .5 rounds down at 15 integer digits" was an
|
|
146
|
+
approximation of the same artifact.
|
|
147
|
+
|
|
148
|
+
**Error values.** `#N/A`, `#DIV/0!` and the other error values are not inputs in 0.1. Excel
|
|
149
|
+
displays them regardless of number format, and openpyxl exposes them as strings with
|
|
150
|
+
`cell.data_type == 'e'`, so a renderer bypasses the formatter for those cells. A string such as
|
|
151
|
+
`'#N/A'` passed in is just text.
|
|
152
|
+
|
|
153
|
+
Fraction formats work from the exact double, not the 15-digit value, and run the denominator
|
|
154
|
+
search and the fixed-denominator rounding in double arithmetic, which is what reproduces Excel.
|
|
155
|
+
|
|
156
|
+
## 6. Numbers
|
|
157
|
+
|
|
158
|
+
- **Rounding**: `Decimal.quantize` with `ROUND_HALF_UP` at the number of decimal placeholders
|
|
159
|
+
after percent and comma scaling.
|
|
160
|
+
- **Digit placement**: from the quantized digit tuple, right to left for the integer part (`0`
|
|
161
|
+
pads with zeros, `?` with spaces, `#` with nothing; grouping inserts `,` every three digits
|
|
162
|
+
when on; inter-digit literals are emitted where they sit), left to right for the decimal part
|
|
163
|
+
(trailing `#` positions beyond the value's digits are omitted, `?` become spaces).
|
|
164
|
+
- **General**: integer values print as integers; otherwise up to 11 characters (10 significant
|
|
165
|
+
digits plus the point), trailing zeros stripped; at or above `99,999,999,999.5` or below
|
|
166
|
+
`0.0001` (with more than nine decimals needed) switch to `d.dddddE+ee` with up to five
|
|
167
|
+
mantissa decimals and a two-digit exponent. These thresholds come from the 2023 prototype and the
|
|
168
|
+
Excel captures; the width-dependent form is in section 8.
|
|
169
|
+
- **Scientific**: with `n` integer placeholders the mantissa has `(exponent mod n) + 1` integer
|
|
170
|
+
digits (so `##0.0E+0` is engineering notation); zero renders every integer placeholder as `0`
|
|
171
|
+
(`000.0E+0`, but `#.#E+#` shows `0.E+0`); the exponent is padded to its placeholder count,
|
|
172
|
+
shows at least one digit, and is signed per `E+`/`E-`; `%` is a literal and does not scale.
|
|
173
|
+
1,770 rows of 2023 and the 960-row `scientific` suite pass.
|
|
174
|
+
- **Fraction**: whole part (optional) from the integer digits, numerator and denominator digit
|
|
175
|
+
counts from the placeholders, fixed denominator when digits follow `/`. Fractions work from
|
|
176
|
+
the exact double (a 15-digit rounding step changed nothing and was removed); the
|
|
177
|
+
fixed-denominator numerator is Excel's nudged half-up in double arithmetic: with `f` the
|
|
178
|
+
fraction part, `f' = fl(f · (1 + 2⁻⁵²))`, `t = fl(f' · D)`, numerator `floor(t)` plus one when
|
|
179
|
+
`t − floor(t) ≥ 0.5` (`CAPTURING.md` §2 item 22). Free denominators use a continued-fraction search bounded by
|
|
180
|
+
`10^digits - 1` with the epsilon from ExcelNumberFormat, which the Excel captures confirm for the
|
|
181
|
+
2023 cases; `fraction_denominators` off uses `Fraction.limit_denominator`. Zero fraction: `?`
|
|
182
|
+
numerators show spaces (the bar too), `#` show nothing, `0` show `0/1`; a whole value of zero
|
|
183
|
+
shows `0` even under `#`; `%` scales. A decimal point before the bar is a `FormatError`
|
|
184
|
+
(Excel refuses the file). All 5,310 rows of 2023 pass.
|
|
185
|
+
|
|
186
|
+
**Fixed-denominator numerator** (`fraction_ties`, `fraction_threshold`,
|
|
187
|
+
`fraction_random`; `CAPTURING.md` §2 item 22). An
|
|
188
|
+
empirical tolerance of `5e-18 · D²` had missed 32 rows near half steps; the nudge by one relative
|
|
189
|
+
epsilon on the fraction part, before the product, fits all 38,904 fixed-denominator rows with no
|
|
190
|
+
known deviation left. `strict` rounds the exact product half-up, the closest fraction.
|
|
191
|
+
|
|
192
|
+
## 7. Dates and times
|
|
193
|
+
|
|
194
|
+
In `_datetime.py`; every rule below is pinned by the 2023 suites
|
|
195
|
+
(35,990 date/time rows), `datetime` (3,630 rows) and `date1904` (336 rows).
|
|
196
|
+
|
|
197
|
+
**Excel's clock arithmetic, operation for operation** (`CAPTURING.md` §2 item 15; fitted to the
|
|
198
|
+
formula-written rows, zero misses on 41,266 date and time rows). The serial `x` is the double
|
|
199
|
+
Excel stores, not the 15-digit display value (`29.5` seconds shows `30`, and 23:59:59.5 on the
|
|
200
|
+
last day overflows). With `scale` = 1, 10, 100 or 1000 for the finest displayed unit (a second,
|
|
201
|
+
or a tenth, hundredth or thousandth; never coarser):
|
|
202
|
+
|
|
203
|
+
```
|
|
204
|
+
d = x + (0.5 / scale) / 86400 bias of half the displayed unit, in days
|
|
205
|
+
day = floor(d); h = (d - day) * 24
|
|
206
|
+
hour = floor(h); m = (h - hour) * 60
|
|
207
|
+
minute = floor(m); s = (m - minute) * 60
|
|
208
|
+
second = floor(s); fraction = floor((s - second) * scale)
|
|
209
|
+
elapsed [h], [m], [s] = floor((x / (1/86400) + 0.5 / scale) / unit)
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
Every field is truncated, so the bias rounds half-up and the carry propagates into the day:
|
|
213
|
+
23:59:59.999 under `h:mm` is `0:00` the next day, under `ss.000` it is `59.999`. The
|
|
214
|
+
floating-point noise of the peel is Excel's: a `General` token inside a date section shows `s`
|
|
215
|
+
before truncation (`0.5` for a whole day, `0.499999803` for serial 44927), which is how the
|
|
216
|
+
order of operations was pinned (nine digits per row over 66 serials). The clock and elapsed
|
|
217
|
+
paths differ in the last bit and Excel shows it: 59.5 seconds under `[mm]:ss` is `01:59`, and
|
|
218
|
+
44927 + 59.5 s shows `64694881:59`. The 59.5-second rows separate `x / (1/86400)` from
|
|
219
|
+
`x * 86400` (59.5 against 59.49999999999999); the day-44927 rows separate the bias in days from a
|
|
220
|
+
bias in seconds.
|
|
221
|
+
|
|
222
|
+
- **1900 system** (default): day `d >= 61` → civil date `1899-12-30 + d`; `1 <= d <= 59` →
|
|
223
|
+
`1899-12-31 + d`; `d == 60` → February 29, 1900; `d == 0` → "January 0, 1900". The weekday is
|
|
224
|
+
`(d + 6) mod 7` with Sunday = 0 (serial 1 is a Sunday; it was a Monday). With `leap_year_1900`
|
|
225
|
+
off the mapping is `1899-12-30 + d` for all `d` (LibreOffice's model) and weekdays are true.
|
|
226
|
+
- **1904 system**: day `d` → `1904-01-01 + d`; weekday `(d + 5) mod 7`; no leap quirk. A
|
|
227
|
+
negative value renders as `-` followed by the rendering of its magnitude (`-1` under
|
|
228
|
+
`m/d/yyyy` is `-1/2/1904`, `-0.5` under `h:mm` is `-12:00`).
|
|
229
|
+
- **Negatives in 1900**: a section made only of elapsed codes shows `-` and the magnitude
|
|
230
|
+
(`[h]` with -1 is `-24`) and has no upper limit; any other section shows the `#` run, decided
|
|
231
|
+
on the raw sign (-1e-9 is `#`, not January 0).
|
|
232
|
+
- **Limits**: a clock section whose rounded value reaches day 2958466 (year 10000) shows `#`;
|
|
233
|
+
under 1904 the limit is 1462 days lower. 23:59:59.5 on 9999-12-31 overflows under `ss` and
|
|
234
|
+
shows `59.5` under `ss.0`.
|
|
235
|
+
- Civil conversion is integer arithmetic (days-from-civil and back, proleptic Gregorian), not
|
|
236
|
+
`datetime`, so year 0 to 9999 and the two synthetic 1900 dates need no special objects.
|
|
237
|
+
- `h` shows 1..12 when the section contains `AM/PM` or `A/P`. `AM/PM` always renders upper-case
|
|
238
|
+
whatever its spelling; `A/P` keeps the token's case (`a/p` gives `a`/`p`).
|
|
239
|
+
- `e` is a four-digit year code. `[$-x-sysdate]` and `[$-F800]` render `dddd, mmmm d, yyyy`
|
|
240
|
+
(the system long date in en-US; Excel's canned string says `dd`, the display says `d`);
|
|
241
|
+
`[$-x-systime]` and `[$-F400]` render `h:mm:ss AM/PM`; a bare tag is the whole format.
|
|
242
|
+
- `General` inside a date section shows Excel's biased seconds before truncation (`s` above):
|
|
243
|
+
a whole day shows `0.5`, 23:59:59.999 shows `0.499`, serial 365 shows `0.499999999`. The
|
|
244
|
+
noise is reproduced because the arithmetic is.
|
|
245
|
+
- Names are English; month and weekday names, `mmmmm` (initial) and `ddd` (three letters).
|
|
246
|
+
|
|
247
|
+
## 8. Width model
|
|
248
|
+
|
|
249
|
+
Two ways a caller limits width, one mechanism underneath.
|
|
250
|
+
|
|
251
|
+
**Character mode** (first to ship): `width: int`, a literal character count. Exact for
|
|
252
|
+
monospace and terminal output. It is not an approximation of Excel; it is its own contract.
|
|
253
|
+
|
|
254
|
+
**Excel mode** (second): the caller passes an Excel column width, the number from the Column
|
|
255
|
+
Width dialog (8.43 is the default), and gets what Excel displays: the same overflow decision,
|
|
256
|
+
the same count of `#`, the same General digit reduction, the same `*` fill count. Excel decides
|
|
257
|
+
by glyph widths, not characters: "Tuesday, January 4, 2000" and "Sunday, December 3, 2000"
|
|
258
|
+
are both 24 characters, yet at column width 21.17 only the second shows `####` (verified by
|
|
259
|
+
hand).
|
|
260
|
+
Excel mode therefore needs per-glyph advance tables. Expected outputs come from Excel for Mac, whose text
|
|
261
|
+
renderer differs from Windows, so borderline fits are matched for Mac and the documentation
|
|
262
|
+
says so.
|
|
263
|
+
|
|
264
|
+
**Glyph tables** are measured per font and per point size and bundled as data
|
|
265
|
+
(`_glyphs_calibri.py`, generated by `capture/glyph_fit.py` from the `measure*` suites). The first
|
|
266
|
+
design stored one table per font in em fractions and scaled it at run time; Excel for Mac hints
|
|
267
|
+
advances per size (digits are 6 points at both 11 and 12, the hyphen 3 then 4), and no
|
|
268
|
+
size-independent fraction reproduces that, so the measured tables replaced it (the Excel-mode
|
|
269
|
+
paragraph below). Calibri is the only bundled font: openpyxl writes Calibri 11 as the workbook
|
|
270
|
+
default and Excel for Mac's own default is Calibri 12. Aptos Narrow, Windows Excel's default,
|
|
271
|
+
waits for a Windows capture; reading installed fonts is an optional extra later, never a
|
|
272
|
+
requirement.
|
|
273
|
+
|
|
274
|
+
**The seam**: internally both modes are "a measure function plus a width in its units": `len`
|
|
275
|
+
for character mode, a glyph-advance sum for Excel mode. The same seam is exposed for callers
|
|
276
|
+
with special needs (a measure callable plus a width). The pipeline is built around it from the
|
|
277
|
+
start so that character mode and Excel mode share every line except the measure. The public
|
|
278
|
+
spelling is in section 11: `width` for character mode, `column_width` and `font` for Excel mode.
|
|
279
|
+
|
|
280
|
+
What the width logic does, and why a caller cannot do it afterwards from the plain string:
|
|
281
|
+
- `*x` repeats `x` so the text measures exactly the width (never negative); the last `*`
|
|
282
|
+
in a section is honored (`*-0*-` shows `1235` then dashes).
|
|
283
|
+
- Numbers and dates whose text measures wider than the width become a run of `#` that fills the
|
|
284
|
+
width; text never overflows (clipping or spilling is the renderer's job). The caller cannot
|
|
285
|
+
apply this rule from outside because it depends on the value kind and on the section, not on
|
|
286
|
+
the string.
|
|
287
|
+
- General reduces before it overflows: it drops decimals (rounding) to fit, then tries
|
|
288
|
+
scientific with fewer mantissa digits, then `#`. The exact order is reverse-engineered from the
|
|
289
|
+
`width_general` capture suite before implementation, not assumed.
|
|
290
|
+
- `_x` counts one character in character mode and the advance of `x` in Excel mode.
|
|
291
|
+
|
|
292
|
+
`width=None` is the unconstrained rendering: `*x` emits nothing, `_x` emits one space, General
|
|
293
|
+
uses the 11-character rule, and a value a datetime section cannot show gives 255 `#`. That is
|
|
294
|
+
Excel's clipboard text; `Range.Text` gives as many `#` as the column holds (30 at width 30), and
|
|
295
|
+
255 is the widest column Excel allows, so the two agree at the limit (`CAPTURING.md` §2 items 1
|
|
296
|
+
and 2). sheetpeek always passes a width, so the 255 case is for callers without a layout.
|
|
297
|
+
|
|
298
|
+
Observed in the `width_general` capture (`CAPTURING.md` §2 item 11): General drops decimals one at
|
|
299
|
+
a time, rounding, until the text fits (`999.9999999` becomes `1000` as soon as one decimal goes);
|
|
300
|
+
when the integer part does not fit it switches to scientific with as many mantissa decimals as
|
|
301
|
+
fit, down to `1E+07`; below that, `#`. Values below one reduce to `0` rather than overflow.
|
|
302
|
+
Booleans overflow like numbers; text never does. Fill and overflow counts in Excel are
|
|
303
|
+
glyph-measured (35 dashes and 53 spaces at width 30), so character mode and Excel mode differ
|
|
304
|
+
on them by design.
|
|
305
|
+
|
|
306
|
+
Consequences for the captures: the character-mode suite uses digit-only output (digits are tabular in
|
|
307
|
+
Excel's default fonts, so character and pixel agree); the Excel-mode suite uses everything,
|
|
308
|
+
including dates with month and day names. Both are captured with `string value` at set column
|
|
309
|
+
widths, and `autofit` followed by reading `column width` back gives Excel's own measurement of
|
|
310
|
+
a text, which is the data a glyph table is built or verified from.
|
|
311
|
+
|
|
312
|
+
**Character mode** (`_measure.py`, `_assemble.py`, `general_text_fitting`
|
|
313
|
+
in `_number.py`; suites `width_general`, `width_fill`, `numeric_core_width`; `CAPTURING.md` §2 item
|
|
314
|
+
23). `width: int` is a count of characters, `measure` is `len`. The `#` run is `width` characters
|
|
315
|
+
long by contract; Excel's count is glyph-measured (six at width 5 in Calibri 11), so the capture
|
|
316
|
+
test treats any two `#` runs as equal. Rows where Excel fitted a text longer than the width
|
|
317
|
+
(commas, points, spaces and minus signs are narrower than digits: `1,000.0` fits width 6,
|
|
318
|
+
`-12345678` fits 8.43) or overflowed a text no longer than it (`%` is wider: `10000%` overflows
|
|
319
|
+
width 6) are glyph slack and glyph tightness; character mode cannot reproduce them and the test
|
|
320
|
+
skips them (2,224 of the 32,832 `numeric_core_width` rows, 11 of `width_fill`, 16 of
|
|
321
|
+
`width_general`); they are the evidence Excel mode will be fitted to. Rows at fractional widths
|
|
322
|
+
(8.43) have no character-mode meaning and are skipped. Two refinements of the rules above came
|
|
323
|
+
from the suites: text does overflow to `#` when its section carries a `*` fill (`@*-` with
|
|
324
|
+
`Hello World` at width 6), and a negative whose `General` reduces to zero at the width drops its
|
|
325
|
+
sign when the section has literals (`General"x"` shows `0x`) but keeps it when the section is a
|
|
326
|
+
bare `General` (`-0.05` at width 3 shows `-0`). `FormattedCell.fill` reports the position in
|
|
327
|
+
`text`. Renders with a width measure under 7 µs.
|
|
328
|
+
|
|
329
|
+
**Excel mode** (`_measure.py`, `_glyphs_calibri.py`; suites `measure11`,
|
|
330
|
+
`measure12` and the width suites; `CAPTURING.md` §2 items 24 and 25). Excel for Mac works in whole
|
|
331
|
+
points. A column of `w` units is `round(MDW · w + 5)` points, MDW being the maximum digit width of
|
|
332
|
+
the Normal font: 5 points for Calibri 9 and 10, 6 for 11 and 12 (so 8.43 snaps to 8.5 units, 56
|
|
333
|
+
points), 7 for 14, 8 for 16; text has those points less the 5 of padding: `MDW · w`. A text
|
|
334
|
+
measures the floored sum of its glyph advances in points at the cell's size; the advances are
|
|
335
|
+
hinted per size (digits are 6 at 11 and 12, `-` is 3 at 11 and 4 at 12, `%` 8 and 9.1), so the
|
|
336
|
+
bundled table holds every measured size (9, 10, 11, 12, 14, 16) as measured and scales the
|
|
337
|
+
nearest measured table with per-glyph rounding for other sizes; glyphs outside the table measure
|
|
338
|
+
as a digit. The autofit width of a text is that measure plus 7 points at every size, which is how
|
|
339
|
+
the tables were fitted (`capture/glyph_fit.py`, 515 of 515 space-less texts exact per size). The
|
|
340
|
+
space (2, 2, 2, 3, 3, 4 points from 9 to 16) comes from the `space_fill` suites, rendered through
|
|
341
|
+
the package with every candidate advance (`CAPTURING.md` §2 item 26); `_x` pads and `?` blanks
|
|
342
|
+
measure as spaces. A `#` run holds `floor(budget / 5)` characters at 11 points (six at width 5),
|
|
343
|
+
a `*` fill `floor((budget − text) / advance)` repeats (35 dashes at width 30 in Calibri 12). Fits
|
|
344
|
+
are `measure ≤ budget`: `1,000.0` (36 points) fits width 6 and `10000%` (38) does not. `General`
|
|
345
|
+
alone reduces by characters, not points: one unit per character and half for a leading minus
|
|
346
|
+
against the column width in units (`-12345678` fits 8.5, `-1234.6` does not fit 6, `-2E-07` needs
|
|
347
|
+
6); among literals the General token gets the units less the literals' and the sign's advances in
|
|
348
|
+
digit units (`( 1234 )` shows at width 6, `( 0.125 )` becomes `( 0.13 )`), and the scientific form
|
|
349
|
+
of a value whose integer part does not fit is admitted without charging the sign (`-1E+05x` at
|
|
350
|
+
width 6) while a value that rounds to zero still pays for it (`0x`). Text overflows only through a
|
|
351
|
+
section whose `*` fill follows it (`@*-` shows `#`, `*-@` shows the text). Every width row of
|
|
352
|
+
every suite passes in Excel mode, the 2,251 glyph-slack rows included; character mode is
|
|
353
|
+
unchanged. Renders in Excel mode measure 3.6 to 8.7 µs. `width_general14` passes
|
|
354
|
+
at Calibri 14 with no change to the model.
|
|
355
|
+
|
|
356
|
+
## 9. Quirks
|
|
357
|
+
|
|
358
|
+
```python
|
|
359
|
+
@dataclass(frozen=True, slots=True)
|
|
360
|
+
class Quirks:
|
|
361
|
+
leap_year_1900: bool = True
|
|
362
|
+
fifteen_digit_precision: bool = True # includes the large-value tie rule, section 5
|
|
363
|
+
fraction_denominators: bool = True
|
|
364
|
+
|
|
365
|
+
EXCEL: ClassVar[Quirks] # all True (the default everywhere)
|
|
366
|
+
STRICT: ClassVar[Quirks] # all False
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
Names are shared with `xlformula` where a quirk exists in both packages; an early candidate,
|
|
370
|
+
`half_down_above_15_digits`, is folded into `fifteen_digit_precision` (section 5).
|
|
371
|
+
Quirks bind at format
|
|
372
|
+
time: `format_value`, `format_cell` and the `NumberFormat` methods take
|
|
373
|
+
`quirks: Quirks | None = None` (None means `Quirks.EXCEL`); `NumberFormat.parse` does not, and
|
|
374
|
+
the parse cache is keyed on the string alone. If a parse-affecting quirk ever appears, revisit.
|
|
375
|
+
`QUIRKS.md` holds, per quirk, the Excel evidence (captured rows), what `strict` does instead, and
|
|
376
|
+
the first version it appeared in. Candidates that need evidence before they are added:
|
|
377
|
+
the `[$-x-sysdate]` `dd` versus `d` discrepancy. Scientific zero rendering (`000.0E+0`), the
|
|
378
|
+
section-selection sign rules, the last `*` fill winning and `General` inside a date section are
|
|
379
|
+
Excel semantics matched unconditionally, not quirks (`QUIRKS.md`).
|
|
380
|
+
|
|
381
|
+
The full set of Excel captures runs under `EXCEL`; `STRICT` gets unit tests that pin the alternative behavior
|
|
382
|
+
on a handful of values.
|
|
383
|
+
|
|
384
|
+
## 10. Output types: plain versus rich
|
|
385
|
+
|
|
386
|
+
Design principle: the plain call returns a plain `str`, and a caller who wants more than the
|
|
387
|
+
string asks for it explicitly.
|
|
388
|
+
|
|
389
|
+
What Excel shows beyond the characters: the section color (eight names or `Color1..56`), the
|
|
390
|
+
default horizontal alignment (numbers and dates right, text left, booleans centered, derived from
|
|
391
|
+
the value kind, not the format), the position of a `*` fill, and whether the cell overflowed.
|
|
392
|
+
|
|
393
|
+
Options considered, with precedent:
|
|
394
|
+
|
|
395
|
+
**A. `str` subclass with attributes** (`xlfmt.Formatted`; `markupsafe.Markup`,
|
|
396
|
+
`bs4.NavigableString`, lxml's smart strings). One function, zero friction, `isinstance(x, str)`.
|
|
397
|
+
Against: attributes vanish silently on `.strip()`, `+`, f-strings and `json`; `type(x) is str`
|
|
398
|
+
is false; every caller pays for the subclass whether they want it or not; and it breaks the
|
|
399
|
+
principle above, since every caller gets more than a string without asking. The lxml and
|
|
400
|
+
BeautifulSoup experience is that string subclasses carrying context are a recurring source of
|
|
401
|
+
confusion.
|
|
402
|
+
|
|
403
|
+
**B. Two entry points: plain function returns `str`, rich function returns a result object**
|
|
404
|
+
(`subprocess.check_output` versus `subprocess.run` → `CompletedProcess`; `os.listdir` versus
|
|
405
|
+
`os.scandir`; `re.search` → `Match`). Explicit, the plain path stays plain and fast, the record
|
|
406
|
+
can grow fields without breaking anyone, and it prints readably. Against: two names to learn.
|
|
407
|
+
A variant is a `details=True` flag with `@overload` (as `open()` and `Path.read_text` do by
|
|
408
|
+
mode); workable but flag-selected return types are the less idiomatic form.
|
|
409
|
+
|
|
410
|
+
**C. Query functions on the compiled format** (`numfmt.formatColor(pattern, value)`,
|
|
411
|
+
`numfmt.getFormatInfo(pattern)`, `isDateFormat`; ExcelNumberFormat's `NumberFormat` object).
|
|
412
|
+
Pattern-level facts (`is_date`, `is_text`, has colors) belong here. Against, for value-level
|
|
413
|
+
facts: color needs section selection, so `format_value` plus `color_for(value)` does that work
|
|
414
|
+
twice, and fill position is a property of the rendered text, not the pattern.
|
|
415
|
+
|
|
416
|
+
**Chosen: B plus the pattern-level part of C.** `format_value()`
|
|
417
|
+
returns `str`; `format_cell()` returns `FormattedCell`; `NumberFormat` (the compiled object, as
|
|
418
|
+
`re.compile` returns a `Pattern`) exposes `is_date`, `is_text`, `is_general`, `sections` and
|
|
419
|
+
both methods. Not A. The rich function is not called `render`: in sheetpeek, which imports it
|
|
420
|
+
next to its own functions, rendering means producing HTML or terminal output from a sheet.
|
|
421
|
+
`format_cell` takes a value and a format string, not an openpyxl cell; the name describes what
|
|
422
|
+
comes back, the display of one cell.
|
|
423
|
+
|
|
424
|
+
```python
|
|
425
|
+
@dataclass(frozen=True, slots=True)
|
|
426
|
+
class FormattedCell:
|
|
427
|
+
text: str # what the cell shows under the given width
|
|
428
|
+
full_text: str # the width=None rendering; always set, never None
|
|
429
|
+
color: str | None # 'Red', 'Blue', ..., 'Color12'; canonical spelling
|
|
430
|
+
align: Literal["left", "right", "center"]
|
|
431
|
+
fill: tuple[int, str] | None # index in text and character of a `*` fill
|
|
432
|
+
overflow: bool # text is a run of '#'
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
`full_text` is what copy-and-paste gives a user and what the 2023 capture holds; it is computed
|
|
436
|
+
before the width decision, so it costs nothing. `overflow` means only "`text` is a `#` run";
|
|
437
|
+
General digit reduction and `*` fill also make `text` differ from `full_text` without being
|
|
438
|
+
overflow, and a caller who needs to know compares the two fields. `xlformat.DEFAULT_PALETTE` maps the
|
|
439
|
+
canonical color names to `RRGGBB` in the default palette (the eight names and `Color1` to
|
|
440
|
+
`Color56`, with the palette's duplicates), confirmed value by value by the `colors` suite.
|
|
441
|
+
|
|
442
|
+
## 11. Public API
|
|
443
|
+
|
|
444
|
+
```python
|
|
445
|
+
from xlformat import format_value, format_cell, NumberFormat, FormattedCell, Quirks, FormatError
|
|
446
|
+
|
|
447
|
+
def format_value(value, format_string="General", *, width=None, column_width=None, font=None,
|
|
448
|
+
measure=None, date1904=False, quirks=None) -> str
|
|
449
|
+
def format_cell(value, format_string="General", *, width=None, column_width=None, font=None,
|
|
450
|
+
measure=None, date1904=False, quirks=None) -> FormattedCell
|
|
451
|
+
|
|
452
|
+
class NumberFormat:
|
|
453
|
+
@classmethod
|
|
454
|
+
def parse(cls, format_string: str) -> "NumberFormat" # cached; raises FormatError
|
|
455
|
+
def format(self, value, *, width=None, column_width=None, font=None, measure=None,
|
|
456
|
+
date1904=False, quirks=None) -> str
|
|
457
|
+
def format_cell(self, value, *, width=None, column_width=None, font=None, measure=None,
|
|
458
|
+
date1904=False, quirks=None) -> FormattedCell
|
|
459
|
+
is_date: bool; is_text: bool; is_general: bool; sections: tuple[Section, ...]
|
|
460
|
+
|
|
461
|
+
class FormatError(ValueError): ...
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
Width parameters: `width: int | None` is character mode, a count of
|
|
465
|
+
characters; `column_width: float | None` is Excel mode in Column Width dialog units, measured with
|
|
466
|
+
the glyph table of `font`; passing both raises `ValueError`. `font: str | tuple[str, float] | None`
|
|
467
|
+
names the font and size, default `("Calibri", 11)` (openpyxl's workbook default; sheetpeek passes
|
|
468
|
+
the workbook's Normal style); a font without a bundled table raises `LookupError` naming the
|
|
469
|
+
bundled fonts (Calibri only, measured at 9, 10, 11, 12, 14 and 16 points and scaled from the
|
|
470
|
+
nearest measured size elsewhere; Aptos Narrow waits for a Windows machine). `measure:
|
|
471
|
+
Callable[[str], float] | None` is the hook for special cases and is used with `width` as the budget
|
|
472
|
+
in the measure's own units. `DEFAULT_PALETTE` maps color names to `RRGGBB`.
|
|
473
|
+
|
|
474
|
+
Behavioral contract:
|
|
475
|
+
- `FormatError` is raised only when Excel itself has no rendering for the format string **as it
|
|
476
|
+
appears in a file**. "What the Format Cells dialog refuses" is the wrong test for a library
|
|
477
|
+
that mostly reads files: of 21 dialog-rejected strings written with openpyxl, Excel refused to
|
|
478
|
+
open the file for 16 (lower-case `e+` after digits, five sections, unclosed `[` or `"`, two
|
|
479
|
+
colors, two conditions, `@` in two sections or a middle section, date and digit codes mixed,
|
|
480
|
+
`E+` without digits, `/` without denominator, two elapsed codes, two `General`) and rendered
|
|
481
|
+
the other five (`*-0*-`, `e+`, `0.0.0`, `0%E+0`; `CAPTURING.md` §2 item 9; the refusal is Excel's
|
|
482
|
+
repair dialog, confirmed by hand). The first group is `FormatError`; the second is behavior to
|
|
483
|
+
match. Consumers catch `FormatError` and fall back to `General`, which is what Excel's recovery
|
|
484
|
+
does to the cell. Invalid-format strings are captured rows.
|
|
485
|
+
- Invalid values for a valid format never raise; they render as `#`.
|
|
486
|
+
- Unsupported types raise `TypeError`; `None` renders as `''`; an empty format string means
|
|
487
|
+
`General`.
|
|
488
|
+
- Thread-safe (immutable compiled objects, `lru_cache`).
|
|
489
|
+
|
|
490
|
+
This signature is the formatter contract the sibling packages `sheetpeek` and `xlformula` rely
|
|
491
|
+
on, with `format_cell` / `FormattedCell` as the rich pair.
|
|
492
|
+
|
|
493
|
+
## 12. Module layout
|
|
494
|
+
|
|
495
|
+
```
|
|
496
|
+
src/xlformat/
|
|
497
|
+
__init__.py public names, __version__
|
|
498
|
+
_parser.py tokenizer, section split, classification, Section/NumberFormat
|
|
499
|
+
_values.py input normalization, date serial conversion both ways
|
|
500
|
+
_number.py number and scientific rendering
|
|
501
|
+
_fraction.py fraction rendering: denominator search, fixed denominators
|
|
502
|
+
_datetime.py civil date arithmetic, time rounding, date/time rendering
|
|
503
|
+
_text.py text and General sections
|
|
504
|
+
_render.py section selection and dispatch to the renderers
|
|
505
|
+
_assemble.py width decision through a measure function; fill, pad, overflow; FormattedCell
|
|
506
|
+
_measure.py measure functions: len (character mode); glyph measure and column model (Excel mode)
|
|
507
|
+
_glyphs_calibri.py measured Calibri advances per size (generated by capture/glyph_fit.py)
|
|
508
|
+
_palette.py DEFAULT_PALETTE
|
|
509
|
+
_quirks.py Quirks
|
|
510
|
+
_errors.py FormatError
|
|
511
|
+
tests/
|
|
512
|
+
capture/ TSV suites and loader (see CAPTURING.md)
|
|
513
|
+
test_*.py unit tests per module, strict-preset tests, API tests
|
|
514
|
+
capture/ generator, capture scripts (not part of the wheel)
|
|
515
|
+
```
|
|
516
|
+
|
|
517
|
+
## 13. Performance
|
|
518
|
+
|
|
519
|
+
Targets: parse under 50 µs for a typical format; format under 10 µs for `#,##0.00`, under 20 µs
|
|
520
|
+
for dates; every captured row under 3 s. Techniques: parse once and cache, precompute everything
|
|
521
|
+
derivable from the format, no regex at render time, no `datetime` objects, Decimal only where
|
|
522
|
+
precision needs it.
|
|
523
|
+
|
|
524
|
+
Measured 2026-10-24 with every section kind implemented (Python 3.11, Apple Silicon):
|
|
525
|
+
|
|
526
|
+
| operation | time |
|
|
527
|
+
|---|---|
|
|
528
|
+
| parse `#,##0.00` (cache cleared) | 16.5 µs |
|
|
529
|
+
| parse `General` | 4.4 µs |
|
|
530
|
+
| parse the four-section accounting format | 61 µs (over target) |
|
|
531
|
+
| format `#,##0.00` with 1234.5 | 4.9 µs |
|
|
532
|
+
| format `General` with 1234567.891 | 3.2 µs |
|
|
533
|
+
| format `m/d/yy` | 5.7 µs |
|
|
534
|
+
| format `yyyy-mm-dd hh:mm:ss.000` | 8.0 µs |
|
|
535
|
+
| format `0.00E+00` | 8.9 µs |
|
|
536
|
+
| format `# ?/?` and `# ??/??` | 7.1 µs and 7.5 µs |
|
|
537
|
+
| full capture run, 25 suites, 268,305 rows, both width modes (2026-10-25) | about 3 s |
|
|
538
|
+
|
|
539
|
+
## 13a. What the code taught
|
|
540
|
+
|
|
541
|
+
- A bare `[$-x-systime]` or `[$-x-sysdate]` tag is the whole format: the section has no date
|
|
542
|
+
codes, yet Excel shows the system time or long date. Classification treats a section whose
|
|
543
|
+
locale is one of these as date/time.
|
|
544
|
+
- Excel honors the **last** `*` fill in a section, not the first (`*-0*-` shows `1235` then
|
|
545
|
+
dashes), so `FormattedCell.fill` records the last one.
|
|
546
|
+
- The 2023 prototype stripped trailing `#` placeholders from the decimal part, which makes `0.0#`
|
|
547
|
+
behave like `0.0`; the 2023 capture never had such a format so it passed. The renderer keeps
|
|
548
|
+
them and drops trailing zero digits only over `#` and `?` positions (`1.55` → `1.55`, `1` →
|
|
549
|
+
`1.0` under `0.0#`, `1.` under `0.##`); the `numeric_core` suite covers this.
|
|
550
|
+
- `-0.5` under `0` renders `-1` (half-up on the magnitude, sign kept); under `0.00` a value that
|
|
551
|
+
rounds to zero drops its sign. Both follow from "round the magnitude, then decide the sign".
|
|
552
|
+
- Grouping separators are decided per digit place from what sits to their left: a digit gives
|
|
553
|
+
`,`, a `?` pad gives a space, an unfilled `#` gives nothing. This reproduces `0,000` → `0,001`,
|
|
554
|
+
`#,###` → `` for zero and `#,##0` for every magnitude without special cases.
|
|
555
|
+
|
|
556
|
+
- An empty first section hides numbers (`;` shows nothing for every number; `;;;` for text and
|
|
557
|
+
booleans too), while `[Red]` or `[>1]` alone is kept by Excel as `[Red]General` / `[>1]General`.
|
|
558
|
+
- Sign rules with conditions, from 14 formats: a section whose condition can only hold for
|
|
559
|
+
negatives (`<` with bound ≤ 0, `<=` with bound < 0) drops the sign like the implicit negative
|
|
560
|
+
section; the "everything else" second section keeps it; a lone failing condition falls back to
|
|
561
|
+
General, dropping the sign when the bound is negative, and shows `#` when the body is
|
|
562
|
+
`General`. Four `[<=0]0` rows (negatives that round to zero show General of the magnitude)
|
|
563
|
+
were known deviations until the re-render rule (`CAPTURING.md` §2 item 17) explained them.
|
|
564
|
+
- An empty-string value renders nothing, literals included (`@" units"` with `""` is empty).
|
|
565
|
+
- The clock arithmetic needed the double, not the 15-digit value, and two different paths for
|
|
566
|
+
clock and elapsed fields (section 7). The first attempt rounded date-only formats to the
|
|
567
|
+
nearest day and broke 4,116 rows; Excel always rounds to the second.
|
|
568
|
+
- The epoch constants were first typed by hand and were two days off; they are now derived
|
|
569
|
+
from `days_from_civil`, and a round-trip test guards them.
|
|
570
|
+
|
|
571
|
+
- **openpyxl writes floats with 16 significant digits** (`"%.16g"`), so the captures' constants
|
|
572
|
+
denoted a neighboring double for about half of all floats, and three rules had been fitted
|
|
573
|
+
to the wrong doubles: the 16-digit step of the tie rule, the fraction-first clock nesting and
|
|
574
|
+
the millisecond-first elapsed path. Formula cells (`=44927+(6*3600+30*60+30.5)/86400`) give
|
|
575
|
+
Excel the double Python holds, and reading the significand back through `INT(B*2^P/2^30)`
|
|
576
|
+
proved Excel's parser correctly rounded. Floats are now written as `repr` text
|
|
577
|
+
(`CAPTURING.md` §2 item 16). Lesson: before fitting a rule to boundary rows, make sure the
|
|
578
|
+
capture's input is the double you think it is.
|
|
579
|
+
- **Nine digits per row beat a thousand rows.** The leaked `General` seconds (`0.499999803`)
|
|
580
|
+
pinned the order of Excel's floating-point operations where half-second rows, which only say
|
|
581
|
+
"up" or "down", could not.
|
|
582
|
+
|
|
583
|
+
## 14. Open questions
|
|
584
|
+
|
|
585
|
+
1. Negative serials under 1904 are captured (`date1904`: a minus sign and the magnitude's
|
|
586
|
+
rendering); `strict` does the same for lack of a stated alternative.
|
|
587
|
+
|
|
588
|
+
Settled by probes: `FormattedCell.fill` reports the position in `text`, `None` without a `*`;
|
|
589
|
+
width-less overflow is 255 `#`; en-US only for 0.1
|
|
590
|
+
with locale tags parsed and exposed on `Section`; error values are the caller's responsibility;
|
|
591
|
+
the fraction rules ship with zero deviations (`QUIRKS.md`); lower-case
|
|
592
|
+
`e+` after digits is a `FormatError`; `e` alone is a year code; a condition in section 3 or 4, or on the text section, is a `FormatError` because Excel refuses the file (`CAPTURING.md` §2 item 9, second run).
|