xtl-py 0.1.0a0__tar.gz

xtl_py-0.1.0a0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+.DS_Store

xtl_py-0.1.0a0/.python-version

@@ -0,0 +1 @@
+3.12

xtl_py-0.1.0a0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: xtl-py
+Version: 0.1.0a0
+Summary: XTL (Excel Template Language) 0.1 — Python reference implementation
+Project-URL: Spec, https://github.com/jinyoung4478/xl3
+Author-email: jinyoung4478 <skswls0@daum.net>
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: openpyxl<4,>=3.1
+Requires-Dist: pyyaml<7,>=6

xtl_py-0.1.0a0/PORTING_NOTES.md

@@ -0,0 +1,160 @@
+# Porting Notes — XTL TS → Python
+
+A running log of points where the spec is genuinely underspecified,
+internally inconsistent, or where the Python port had to make a non-obvious
+call. Format per entry:
+
+- **Where**: spec section / ADR / fixture number
+- **Question**: the ambiguity in one sentence
+- **TS impl behavior**: what the JS reference implementation does today
+- **Other reasonable interpretations**: alternatives we considered
+- **Our choice**: what the Python port does, and why
+- **Severity**: spec/impl/test (does it block conformance? does it block
+  cross-impl portability?)
+
+When this file accumulates 5+ entries, batch them into an issue against
+`xl3` and propose ADR amendments.
+
+---
+
+## #1. ECMA-262 scientific-notation cutoff is `1e-6`, not `1e-4`
+
+**Where**: `spec/language.md` "Canonical String Form"; `spec/decisions/0009-comparison-and-string-coercion.md` §"Canonical string form".
+
+**Question**: ADR-0009 says the canonical-string form of a finite number uses
+"no scientific notation for magnitudes between `1e-4` and `1e21`," and claims
+this matches `Number.prototype.toString`. But ECMA-262 §6.1.6.1.13 actually
+uses a **`-6`** cutoff, not `-4`. So `(0.00005).toString()` is `"0.00005"` in
+JS — decimal, not scientific. The spec text and the cited authority disagree.
+
+**TS impl behavior**: uses the host `Number.prototype.toString`, so follows
+ECMA-262 (`-6` cutoff). The fixture corpus was authored against this
+behavior.
+
+**Other reasonable interpretations**:
+- Take the spec text literally: scientific for `0 < |x| < 1e-4`. Diverges
+  from JS impl + corpus.
+- Take ECMA-262 literally: `-6` cutoff. Matches impl + corpus, contradicts
+  spec text.
+
+**Our choice**: ECMA-262 cutoff (`-6`). Implementing the literal spec
+text would fail any fixture exercising values in `[1e-6, 1e-4)`. Our
+`canonical_number` re-implements ECMA-262 §6.1.6.1.13 directly so the
+behavior is JS-compatible regardless of host language quirks.
+
+**Severity**: spec — propose an ADR amendment that replaces "1e-4" with
+"1e-6" and either drops the redundant `Number.prototype.toString` cite or
+keeps it now that the text matches.
+
+---
+
+## #2. ECMA `String.prototype.trim` historically includes U+FEFF; ADR-0007 excludes it
+
+**Where**: `spec/decisions/0007-empty-value-definition.md`.
+
+**Question**: ADR-0007 says whitespace "matches the set recognized by
+ECMAScript `String.prototype.trim` — equivalent to the Unicode-mode `\s`
+character class," but then explicitly excludes U+FEFF (zero-width no-break
+space / BOM) and other zero-width characters. ECMAScript's `WhiteSpace`
+production has historically *included* U+FEFF, and most engines implement
+`trim()` accordingly. So a string of bare U+FEFF is empty per native JS
+trim but **non-empty** per ADR-0007.
+
+**TS impl behavior**: uses native `String.prototype.trim`, which strips
+U+FEFF on V8/JSC/SM. So a bare-U+FEFF source cell is empty per the impl,
+non-empty per the spec.
+
+**Other reasonable interpretations**:
+- Follow Unicode `White_Space` property strictly (what the ADR text says).
+- Follow ECMA-262 `WhiteSpace` production (what the impl actually does).
+
+**Our choice**: Unicode `White_Space` (Python `str.isspace()`), per the
+ADR's normative bullet. No fixture currently asserts this edge case, so the
+divergence is silent for the bootstrap corpus, but we follow the spec.
+
+**Severity**: impl — TS impl deviates from spec on a technicality. Worth a
+fixture (`empty-zwnbsp-not-whitespace`) to pin behavior either way.
+
+---
+
+## #3. Python `repr(float)` exponent padding differs from ECMA `Number.prototype.toString`
+
+**Where**: implementation detail; affects every numeric `&` concat and every
+single-expression cell coercion fallback.
+
+**Question**: Python `repr(1e-7)` is `"1e-07"` (two-digit padded exponent);
+JS `(1e-7).toString()` is `"1e-7"`. Python `repr(-0.0)` is `"-0.0"`; JS
+`(-0).toString()` is `"0"`.
+
+**TS impl behavior**: matches ECMA-262 by virtue of being JS.
+
+**Our choice**: re-implement ECMA-262 §6.1.6.1.13 directly in
+`canonical_number`. Don't trust `repr(float)` to format identically — we
+extract digits + decimal exponent from `repr` and re-render using the
+ECMA format selection rules (decimal in [1e-6, 1e21), scientific outside).
+Negative zero returns `"0"`.
+
+**Severity**: impl — just a thing the port has to handle.
+
+---
+
+## #4. Excel serial dates are timezone-naive; ADR-0017 mandates UTC
+
+**Where**: ADR-0017 §"Timezone (normative)".
+
+**Question**: ADR-0017 says Date components MUST be read in UTC.
+ExcelJS exposes Excel's timezone-naive serial dates as `Date` objects
+*anchored at UTC midnight*, and the impl uses `getUTCFullYear` etc.
+openpyxl returns Python `datetime.datetime` objects with `tzinfo=None`
+(naive); calling `.year`/`.month`/`.date()` on them yields the serial's
+naked components, which is what ADR-0017 wants — but only if you don't
+"localize" them first.
+
+**TS impl behavior**: explicit `getUTC*` calls.
+
+**Our choice**: never call `.astimezone()` on a naive datetime; treat
+naive openpyxl datetimes as already-UTC. `canonical_date` strips
+`tzinfo` defensively if present.
+
+**Severity**: impl — easy to get wrong subtly. Worth a Stage 1 timezone
+matrix fixture run (CI matrix per `STABILITY.md`).
+
+---
+
+## #5. TS IF-condition normalizer recognizes `==` but NOT `=` — spec uses `=`
+
+**Where**: `xl3/src/normalizer.ts` lines ~215-225; fixture
+`048-if-and-comparison-boundaries`.
+
+**Question**: `language.md` §"Comparison Operators" lists `=` (single equal)
+as the equality operator. The TS normalizer's IF-condition op list is
+`[['!=', 'ne'], ['>=', 'ge'], ['<=', 'le'], ['==', 'eq'], ['>', 'gt'],
+['<', 'lt']]` — it has `==` but NOT `=`. So
+`IF([Amount] = 0, "zero", "non-zero")` is normalized as a function call
+where the condition is the *raw string* `"[Amount] = 0"`. At eval time
+it falls through to "bare string literal" which is non-empty → truthy →
+IF always takes the THEN branch regardless of Amount.
+
+Fixture 048 was authored against this buggy behavior. Its
+`expected.xlsx` has `D3='zero'` for an Amount=1 row, even though
+spec-correct evaluation of `IF(1 = 0, "zero", "non-zero")` is
+`"non-zero"`.
+
+**TS impl behavior**: bug — `=` not recognized in IF condition; treated
+as literal string (always truthy).
+
+**Other reasonable interpretations**: this is unambiguously a TS impl
+bug under the spec.
+
+**Our choice**: follow the spec — `=` is the equality operator
+everywhere, including IF conditions. We FAIL fixture 048.
+
+**Severity**: impl + test — `xl3/src/normalizer.ts` should add `=` to
+the ops list before `==`; and fixture 048's `expected.xlsx` should be
+re-authored to reflect spec-correct evaluation. Note that `@filter [col]
+= value` works correctly in TS (different parser). Other fixtures using
+`=` (063, 064, 079, 080, 081, 088, 092) are inside @filter / @join
+clauses that TS parses with a separate code path that does handle `=`.
+Fixture 048 is the only one currently affected.
+
+## #6. (placeholder — append future ambiguities below)

xtl_py-0.1.0a0/conformance-report.json

@@ -0,0 +1,485 @@
+{
+  "implementation": "xl3-py",
+  "version": "0.1.0a0",
+  "spec_version": "0.1",
+  "comparison_stage": 1,
+  "results": [
+    {
+      "fixture": "001-bracket-substitution",
+      "status": "pass",
+      "duration_ms": 12
+    },
+    {
+      "fixture": "002-if-function",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "003-list-sheet-filter",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "004-repeat-right-default",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "005-round-half-away-from-zero",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "006-filename-forbidden-chars",
+      "status": "pass",
+      "duration_ms": 4
+    },
+    {
+      "fixture": "007-filename-reserved-name",
+      "status": "pass",
+      "duration_ms": 4
+    },
+    {
+      "fixture": "008-numfmt-numeric-string-coercion",
+      "status": "pass",
+      "duration_ms": 4
+    },
+    {
+      "fixture": "009-numfmt-date-string-coercion",
+      "status": "pass",
+      "duration_ms": 4
+    },
+    {
+      "fixture": "010-numfmt-text-format-coercion",
+      "status": "pass",
+      "duration_ms": 4
+    },
+    {
+      "fixture": "011-text-date-format",
+      "status": "pass",
+      "duration_ms": 4
+    },
+    {
+      "fixture": "012-text-number-format",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "013-rich-text-template-expression",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "014-source-formula-cached-result",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "015-source-sheet-prefix-first-match",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "016-text-number-negative-rounding",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "017-source-sheet-prefix-no-match-error",
+      "status": "pass",
+      "duration_ms": 2
+    },
+    {
+      "fixture": "018-source-formula-missing-cached-result-error",
+      "status": "pass",
+      "duration_ms": 2
+    },
+    {
+      "fixture": "019-filename-empty-basename-error",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "020-filename-length-overflow-error",
+      "status": "pass",
+      "duration_ms": 8
+    },
+    {
+      "fixture": "021-numfmt-number-coercion-error",
+      "status": "pass",
+      "duration_ms": 3
+    },
+    {
+      "fixture": "022-numfmt-date-coercion-error",
+      "status": "pass",
+      "duration_ms": 3
+    },
+    {
+      "fixture": "023-today-utc-dynamic",
+      "status": "pass",
+      "duration_ms": 4
+    },
+    {
+      "fixture": "024-stage2-merge-preservation",
+      "status": "skip",
+      "reason": "requires comparison_stage 2"
+    },
+    {
+      "fixture": "025-stage2-style-numfmt-preservation",
+      "status": "skip",
+      "reason": "requires comparison_stage 2"
+    },
+    {
+      "fixture": "026-stage2-splice-merge-style-preservation",
+      "status": "skip",
+      "reason": "requires comparison_stage 2"
+    },
+    {
+      "fixture": "027-stage2-cross-writer-canonicalization",
+      "status": "skip",
+      "reason": "requires comparison_stage 2"
+    },
+    {
+      "fixture": "028-source-table-row-shorthand",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "029-source-table-open-range",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "030-source-table-finite-range",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "031-source-table-zero-data-range",
+      "status": "pass",
+      "duration_ms": 3
+    },
+    {
+      "fixture": "032-source-table-empty-column-name-error",
+      "status": "pass",
+      "duration_ms": 2
+    },
+    {
+      "fixture": "033-source-table-duplicate-column-name-error",
+      "status": "pass",
+      "duration_ms": 2
+    },
+    {
+      "fixture": "034-source-table-invalid-selector-error",
+      "status": "pass",
+      "duration_ms": 2
+    },
+    {
+      "fixture": "035-source-table-rich-text-header",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "036-source-table-formula-header",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "037-source-table-formula-header-missing-cache-error",
+      "status": "pass",
+      "duration_ms": 2
+    },
+    {
+      "fixture": "038-source-sheet-exact-match-beats-prefix",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "039-source-sheet-default-first-worksheet",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "040-list-sheet-hidden-states-removed",
+      "status": "pass",
+      "duration_ms": 6
+    },
+    {
+      "fixture": "041-row-function-inside-repeat-block",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "042-row-function-outside-repeat-block-error",
+      "status": "pass",
+      "duration_ms": 3
+    },
+    {
+      "fixture": "043-ifempty-function",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "044-sort-and-top-order",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "045-list-sheet-not-in-filter",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "046-count-field-non-empty",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "047-aggregate-functions",
+      "status": "pass",
+      "duration_ms": 6
+    },
+    {
+      "fixture": "048-if-and-comparison-boundaries",
+      "status": "fail",
+      "duration_ms": 6,
+      "diff": "Report!D3: expected 'zero', got 'non-zero'"
+    },
+    {
+      "fixture": "049-filename-sanitization-warning",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "050-empty-ifempty-whitespace-only",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "051-empty-ifempty-zero-not-empty",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "052-empty-count-field-whitespace-zero-false",
+      "status": "pass",
+      "duration_ms": 6
+    },
+    {
+      "fixture": "053-empty-row-skip-whitespace-only",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "054-empty-list-membership",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "055-if-truthy-zero-and-empty",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "056-if-truthy-string-zero-not-special",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "057-if-truthy-boolean",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "058-if-comparison-result",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "059-compare-numeric-string-vs-number",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "060-compare-string-codepoint-order",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "061-concat-canonical-form",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "062-concat-empty-stringifies-to-empty",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "063-compare-empty-vs-value",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "064-compare-unicode-minus-not-numeric",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "065-input-text-default-applied",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "066-input-text-host-supplied",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "067-input-missing-required-error",
+      "status": "pass",
+      "duration_ms": 1
+    },
+    {
+      "fixture": "068-input-select-host-supplied",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "069-source-multi-declaration",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "070-source-aggregate-cross-source",
+      "status": "pass",
+      "duration_ms": 6
+    },
+    {
+      "fixture": "071-source-directive-active",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "072-source-undeclared-error",
+      "status": "pass",
+      "duration_ms": 3
+    },
+    {
+      "fixture": "073-source-row-cross-error",
+      "status": "pass",
+      "duration_ms": 4
+    },
+    {
+      "fixture": "074-xlookup-basic",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "075-xlookup-fallback",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "076-xlookup-no-match-error",
+      "status": "pass",
+      "duration_ms": 8
+    },
+    {
+      "fixture": "077-xlookup-source-mismatch-error",
+      "status": "pass",
+      "duration_ms": 4
+    },
+    {
+      "fixture": "078-xlookup-bare-bracket-error",
+      "status": "pass",
+      "duration_ms": 4
+    },
+    {
+      "fixture": "079-join-basic-inner",
+      "status": "pass",
+      "duration_ms": 6
+    },
+    {
+      "fixture": "080-join-no-match-dropped",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "081-join-undeclared-source-error",
+      "status": "pass",
+      "duration_ms": 3
+    },
+    {
+      "fixture": "082-join-bad-on-clause-error",
+      "status": "pass",
+      "duration_ms": 4
+    },
+    {
+      "fixture": "083-sort-stable-equal-keys",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "084-sort-multi-stable-priority",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "085-file-group-first-seen-order",
+      "status": "pass",
+      "duration_ms": 10
+    },
+    {
+      "fixture": "086-sheet-group-first-seen-order",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "087-date-canonical-string-concat",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "088-date-comparison-equality",
+      "status": "pass",
+      "duration_ms": 4
+    },
+    {
+      "fixture": "089-error-sentinel-empty",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "090-percentage-numeric-flow",
+      "status": "pass",
+      "duration_ms": 5
+    },
+    {
+      "fixture": "091-source-unknown-column-error",
+      "status": "pass",
+      "duration_ms": 4
+    },
+    {
+      "fixture": "092-composed-multi-source-join-filter-sort",
+      "status": "pass",
+      "duration_ms": 7
+    },
+    {
+      "fixture": "093-stage2-excel-authored-expected",
+      "status": "skip",
+      "reason": "requires comparison_stage 2"
+    },
+    {
+      "fixture": "094-reserved-sheet-name-error",
+      "status": "pass",
+      "duration_ms": 1
+    }
+  ],
+  "summary": {
+    "total": 89,
+    "passed": 88,
+    "failed": 1,
+    "skipped": 5
+  }
+}