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.
Files changed (110) hide show
  1. xlformat-0.1.0/.gitignore +23 -0
  2. xlformat-0.1.0/ARCHITECTURE.md +592 -0
  3. xlformat-0.1.0/CAPTURING.md +514 -0
  4. xlformat-0.1.0/CHANGELOG.md +46 -0
  5. xlformat-0.1.0/CONTRIBUTING.md +81 -0
  6. xlformat-0.1.0/LICENSE +21 -0
  7. xlformat-0.1.0/PKG-INFO +201 -0
  8. xlformat-0.1.0/QUIRKS.md +124 -0
  9. xlformat-0.1.0/README.md +174 -0
  10. xlformat-0.1.0/capture/__init__.py +4 -0
  11. xlformat-0.1.0/capture/__main__.py +8 -0
  12. xlformat-0.1.0/capture/build.py +129 -0
  13. xlformat-0.1.0/capture/build_probe_workbook.py +120 -0
  14. xlformat-0.1.0/capture/capture.py +276 -0
  15. xlformat-0.1.0/capture/capture_template.applescript +105 -0
  16. xlformat-0.1.0/capture/cases.py +1569 -0
  17. xlformat-0.1.0/capture/convert_2023.py +58 -0
  18. xlformat-0.1.0/capture/diff_captures.py +83 -0
  19. xlformat-0.1.0/capture/formula_diff.py +64 -0
  20. xlformat-0.1.0/capture/glyph_fit.py +151 -0
  21. xlformat-0.1.0/capture/invalid.py +99 -0
  22. xlformat-0.1.0/capture/probe_behavior.applescript +125 -0
  23. xlformat-0.1.0/capture/probe_color_bulk.applescript +57 -0
  24. xlformat-0.1.0/capture/probe_file.applescript +34 -0
  25. xlformat-0.1.0/capture/probe_file_many.applescript +44 -0
  26. xlformat-0.1.0/capture/probe_timing.applescript +55 -0
  27. xlformat-0.1.0/capture/retier.py +63 -0
  28. xlformat-0.1.0/capture/rounding_models.py +103 -0
  29. xlformat-0.1.0/capture/schema.py +113 -0
  30. xlformat-0.1.0/capture/tiers.py +45 -0
  31. xlformat-0.1.0/docs/_templates/page.html +15 -0
  32. xlformat-0.1.0/docs/_templates/search.html +96 -0
  33. xlformat-0.1.0/docs/api.md +39 -0
  34. xlformat-0.1.0/docs/changelog.md +2 -0
  35. xlformat-0.1.0/docs/conf.py +52 -0
  36. xlformat-0.1.0/docs/index.md +38 -0
  37. xlformat-0.1.0/docs/quirks.md +21 -0
  38. xlformat-0.1.0/docs/testing.md +84 -0
  39. xlformat-0.1.0/docs/usage.md +99 -0
  40. xlformat-0.1.0/docs/width.md +78 -0
  41. xlformat-0.1.0/pagefind.yml +7 -0
  42. xlformat-0.1.0/pyproject.toml +111 -0
  43. xlformat-0.1.0/src/xlformat/__init__.py +100 -0
  44. xlformat-0.1.0/src/xlformat/_assemble.py +134 -0
  45. xlformat-0.1.0/src/xlformat/_datetime.py +253 -0
  46. xlformat-0.1.0/src/xlformat/_errors.py +12 -0
  47. xlformat-0.1.0/src/xlformat/_fraction.py +186 -0
  48. xlformat-0.1.0/src/xlformat/_glyphs_calibri.py +595 -0
  49. xlformat-0.1.0/src/xlformat/_measure.py +100 -0
  50. xlformat-0.1.0/src/xlformat/_number.py +300 -0
  51. xlformat-0.1.0/src/xlformat/_palette.py +36 -0
  52. xlformat-0.1.0/src/xlformat/_parser.py +818 -0
  53. xlformat-0.1.0/src/xlformat/_quirks.py +39 -0
  54. xlformat-0.1.0/src/xlformat/_render.py +281 -0
  55. xlformat-0.1.0/src/xlformat/_text.py +33 -0
  56. xlformat-0.1.0/src/xlformat/_values.py +151 -0
  57. xlformat-0.1.0/src/xlformat/py.typed +0 -0
  58. xlformat-0.1.0/tests/captures/capture2023.tsv.gz +0 -0
  59. xlformat-0.1.0/tests/captures/capture2023_sample.tsv.gz +0 -0
  60. xlformat-0.1.0/tests/captures/capture2026.tsv.gz +0 -0
  61. xlformat-0.1.0/tests/captures/clock_boundaries.tsv +198 -0
  62. xlformat-0.1.0/tests/captures/clock_formulas.tsv.gz +0 -0
  63. xlformat-0.1.0/tests/captures/colors.tsv +182 -0
  64. xlformat-0.1.0/tests/captures/conditions_rounding.tsv +199 -0
  65. xlformat-0.1.0/tests/captures/date1904.tsv +348 -0
  66. xlformat-0.1.0/tests/captures/datetime.tsv.gz +0 -0
  67. xlformat-0.1.0/tests/captures/fraction.tsv.gz +0 -0
  68. xlformat-0.1.0/tests/captures/fraction_random.tsv.gz +0 -0
  69. xlformat-0.1.0/tests/captures/fraction_threshold.tsv.gz +0 -0
  70. xlformat-0.1.0/tests/captures/fraction_ties.tsv +249 -0
  71. xlformat-0.1.0/tests/captures/lone_zero.tsv +108 -0
  72. xlformat-0.1.0/tests/captures/measure10.measure.tsv +525 -0
  73. xlformat-0.1.0/tests/captures/measure10.tsv +13 -0
  74. xlformat-0.1.0/tests/captures/measure11.measure.tsv +525 -0
  75. xlformat-0.1.0/tests/captures/measure11.tsv +13 -0
  76. xlformat-0.1.0/tests/captures/measure12.measure.tsv +525 -0
  77. xlformat-0.1.0/tests/captures/measure12.tsv +13 -0
  78. xlformat-0.1.0/tests/captures/measure14.measure.tsv +525 -0
  79. xlformat-0.1.0/tests/captures/measure14.tsv +13 -0
  80. xlformat-0.1.0/tests/captures/measure16.measure.tsv +525 -0
  81. xlformat-0.1.0/tests/captures/measure16.tsv +13 -0
  82. xlformat-0.1.0/tests/captures/measure9.measure.tsv +525 -0
  83. xlformat-0.1.0/tests/captures/measure9.tsv +13 -0
  84. xlformat-0.1.0/tests/captures/numeric_core.tsv.gz +0 -0
  85. xlformat-0.1.0/tests/captures/numeric_core_width.tsv.gz +0 -0
  86. xlformat-0.1.0/tests/captures/parser_check.tsv.gz +0 -0
  87. xlformat-0.1.0/tests/captures/rounding_15digit.tsv +147 -0
  88. xlformat-0.1.0/tests/captures/scientific.tsv.gz +0 -0
  89. xlformat-0.1.0/tests/captures/selection_fallback.tsv +52 -0
  90. xlformat-0.1.0/tests/captures/space_fill10.tsv +213 -0
  91. xlformat-0.1.0/tests/captures/space_fill11.tsv +213 -0
  92. xlformat-0.1.0/tests/captures/space_fill12.tsv +213 -0
  93. xlformat-0.1.0/tests/captures/space_fill14.tsv +213 -0
  94. xlformat-0.1.0/tests/captures/space_fill16.tsv +213 -0
  95. xlformat-0.1.0/tests/captures/space_fill9.tsv +213 -0
  96. xlformat-0.1.0/tests/captures/text_overflow.tsv +61 -0
  97. xlformat-0.1.0/tests/captures/width_fill.tsv.gz +0 -0
  98. xlformat-0.1.0/tests/captures/width_general.measure.tsv +60 -0
  99. xlformat-0.1.0/tests/captures/width_general.tsv.gz +0 -0
  100. xlformat-0.1.0/tests/captures/width_general14.measure.tsv +60 -0
  101. xlformat-0.1.0/tests/captures/width_general14.tsv.gz +0 -0
  102. xlformat-0.1.0/tests/conftest.py +20 -0
  103. xlformat-0.1.0/tests/test_captures.py +205 -0
  104. xlformat-0.1.0/tests/test_cell.py +49 -0
  105. xlformat-0.1.0/tests/test_datetime.py +58 -0
  106. xlformat-0.1.0/tests/test_examples.py +24 -0
  107. xlformat-0.1.0/tests/test_measure.py +57 -0
  108. xlformat-0.1.0/tests/test_package.py +5 -0
  109. xlformat-0.1.0/tests/test_parser.py +237 -0
  110. 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).