fancy-dark-slide 0.1.0__tar.gz

fancy_dark_slide-0.1.0/.gitattributes

@@ -0,0 +1,23 @@
+# Line endings are part of the contract here, so they are pinned rather than
+# left to a clone's `core.autocrlf`.
+#
+# Two reasons, both concrete:
+#
+#  1. The writers are string builders and the OOXML they emit is compared
+#     byte-for-byte against the PHP reference. A source file checked out with
+#     CRLF changes the bytes of any multi-line literal in it.
+#  2. `holy-sheet`'s tool-definition JSON is pinned by a cross-repo SHA-256
+#     that is taken over CRLF-NORMALISED text. A Windows checkout hashes
+#     differently from the same file on Linux, which reads as a drifted schema
+#     when nothing has drifted at all. It has already cost one investigation.
+#
+# The markdown fixtures matter for the same reason: `last-word`'s markdown
+# bridge is asserted byte-exact with LF newlines.
+* text=auto eol=lf
+
+*.docx binary
+*.xlsx binary
+*.pptx binary
+*.png  binary
+*.jpg  binary
+*.jpeg binary

fancy_dark_slide-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Least-privilege: CI only reads the repo.
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      # Third-party dependency allowlist. Cheap, and failing here is cheap --
+      # the same check gates the release, so a PR that adds an unapproved or
+      # abandoned dependency finds out now rather than at tag time.
+      # The allowlist is FETCHED, never vendored: one source, no copies to drift.
+      - name: Fetch the third-party allowlist
+        uses: actions/checkout@v4
+        with:
+          repository: Particle-Academy/.github
+          path: .third-party-allowlist
+          persist-credentials: false
+
+      - name: Third-party dependency allowlist
+        run: |
+          node .third-party-allowlist/third-party/check.mjs --repo .
+          # Delete it. A fetched checkout left lying in the workspace is not
+          # inert: vitest globbed the checker's own tests out of it and failed
+          # a package whose code was fine. Removed with node, not rm -rf,
+          # because some of these matrices run on windows-latest where a
+          # multi-line run: block is PowerShell and rm -rf is not a command.
+          node -e "require('node:fs').rmSync('.third-party-allowlist',{recursive:true,force:true})"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # PHP is REQUIRED, not optional. tests/test_parity_php.py is the
+      # cross-runtime writer guarantee and it FAILS when php is absent rather
+      # than skipping - a skip here is a green build with zero parity coverage,
+      # which is exactly how two suites in this org reported success over
+      # nothing for months.
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.4"
+          coverage: none
+          extensions: mbstring, zip
+
+      - name: Check out the PHP dark-slide
+        uses: actions/checkout@v4
+        with:
+          repository: Particle-Academy/dark-slide
+          path: .php-dark-slide
+
+      - name: Check out fancy-conformance
+        uses: actions/checkout@v4
+        with:
+          repository: Particle-Academy/fancy-conformance
+          path: .fancy-conformance
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Test
+        run: python -m pytest
+        env:
+          DARK_SLIDE_PHP_SRC: ${{ github.workspace }}/.php-dark-slide/src
+          FANCY_CONFORMANCE_ROOT: ${{ github.workspace }}/.fancy-conformance

fancy_dark_slide-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,87 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions: {}
+
+jobs:
+  # Build and publish are separate jobs so `id-token: write` is never held by
+  # the job that executes build code.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      # The one documentation failure that cannot be repaired later: once the
+      # sdist is on PyPI, whoever upgraded into it has no way to learn what
+      # changed. Checked before anything is built.
+      - name: Require a CHANGELOG entry for this tag
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          grep -q "^## \[${version}\]" CHANGELOG.md || {
+            echo "No CHANGELOG.md entry for ${version}."
+            exit 1
+          }
+
+      # Release gate: third-party dependencies must be approved and still
+      # maintained BEFORE the tarball reaches the registry. Once it is
+      # published, an unapproved or abandoned dependency has already shipped
+      # to everyone who upgrades -- the same reason the changelog gate sits
+      # here. The allowlist is FETCHED, never vendored: one source of truth,
+      # so there is no per-repo copy that can drift out of agreement with it.
+      - name: Fetch the third-party allowlist
+        uses: actions/checkout@v4
+        with:
+          repository: Particle-Academy/.github
+          path: .third-party-allowlist
+          persist-credentials: false
+
+      - name: Third-party dependency allowlist
+        run: |
+          node .third-party-allowlist/third-party/check.mjs --repo .
+          # Delete it. A fetched checkout left lying in the workspace is not
+          # inert: vitest globbed the checker's own tests out of it and failed
+          # a package whose code was fine. Removed with node, not rm -rf,
+          # because some of these matrices run on windows-latest where a
+          # multi-line run: block is PowerShell and rm -rf is not a command.
+          node -e "require('node:fs').rmSync('.third-party-allowlist',{recursive:true,force:true})"
+
+      - name: Require the version to match the tag
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          grep -q "^version = \"${version}\"$" pyproject.toml || {
+            echo "pyproject.toml version does not match tag ${GITHUB_REF_NAME}."
+            exit 1
+          }
+
+      - run: python -m pip install --upgrade build && python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dists
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fancy-flow
+    permissions:
+      id-token: write        # mandatory for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dists
+          path: dist/
+      # Pinned by SHA, not by tag: a mutable reference in exactly this position
+      # is what the April 2026 supply-chain compromises exploited.
+      # v1.14.2 -- no `password:` (that is the point) and attestations default
+      # to true.
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33

fancy_dark_slide-0.1.0/.gitignore

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

fancy_dark_slide-0.1.0/AGENTS.md

@@ -0,0 +1,170 @@
+# AGENTS.md — dark-slide (Python)
+
+This file describes **this repository's code**: its API, its invariants, and the
+traps in it. Process rules — release lifecycle, publishing, version policy,
+backports — live in the envelope's `AGENTS.md` and must never be copied here; a
+copy on a maintenance branch would freeze a rule that has since changed, with
+nothing to flag it.
+
+## What this is
+
+A `.pptx` writer + reader with **no runtime dependencies, permanently**. It is
+one of three engines that must produce the same document from the same deck:
+
+| | |
+|---|---|
+| PHP | `particle-academy/dark-slide` — **the reference** |
+| Node | `@particle-academy/dark-slide` |
+| Python | this repo |
+
+The deck model is plain `dict`s and the `Validator` is the gate. `schema/types.py`
+holds `TypedDict`s for editor support only; nothing enforces them at runtime, and
+nothing should. Loose agent JSON is the *input format*, and
+`validate_and_repair()` exists to rescue it.
+
+## The invariant everything else serves
+
+> **`to_bytes()` must emit byte-identical OOXML parts to the PHP engine.**
+
+`tests/test_parity_php.py` runs the PHP writer as a subprocess and diffs every
+part for every fixture. That is the definition of done for any writer change.
+It follows that:
+
+- **Never build XML with `ElementTree` on the write side.** Attribute order,
+  self-closing style, and the absence of inter-element whitespace are all part
+  of the output. `helpers/xml.py` is an escaper, not a serialiser, and the
+  writer concatenates strings.
+- **`helpers/xml.text` and `helpers/xml.attr` escape different sets**, and the
+  asymmetry is load-bearing: `text` leaves the apostrophe alone, `attr` writes
+  `'` (the `ENT_XML1` entity — *not* `'`, whatever a spec says;
+  the parity suite checks it against the engine).
+- **Which parts exist is contract.** No `notesMasters/`, no `presProps.xml`, no
+  `tableStyles.xml`. All eight `slideLayout` parts always ship. Notes parts are
+  numbered by SLIDE, so the sequence has gaps.
+- **The zip container is NOT compared and never can be.** PHP writes DEFLATE
+  with real mtimes through `ZipArchive`; this writes STORE with a fixed
+  1980-01-01 DOS date. The comparison unzips both and diffs parts, which is the
+  real contract anyway — a reader sees parts, never the compression.
+
+## Traps
+
+### 1. `round()` is the wrong function here. Always.
+
+Python rounds half to **even**; PHP rounds half **away from zero**. Every
+coordinate in every deck is `round(fraction * 9144000)`, so this is not a corner
+case — it is a one-EMU shift in thousands of attributes.
+
+Use `helpers.emu.php_round`. Nothing in the package may call the builtin, and
+`test_no_module_in_the_package_calls_the_builtin_round` parses the AST to prove
+it. The `roundingTies` fixture pins two real ties (`3/128 × 9144000` and
+`3/8 × 5143500`, both exactly `.5` over an even integer) against the oracle.
+
+The one exception is documented at its site: `_num_str`'s `"%.6f"` is safe
+because **no IEEE-754 double is an exact tie at six decimal places** — that
+would require `5·10⁻⁷` to be a dyadic rational, and it is not — so the rounding
+mode cannot matter there.
+
+### 2. PHP's loose types are reproduced on purpose (`util.py`)
+
+Five of them change emitted bytes, and Python's instincts are wrong on all five:
+
+- `php_string(True)` is `"1"`, `php_string(12.0)` is `"12"`, and
+  `php_string(1/3)` is `"0.33333333333333"` (precision 14, not `repr`).
+- `php_truthy("0")` is **False**. A slide whose `notes` is `"0"` gets no notes
+  part; `bool("0")` would give it one.
+- `is_numeric` follows PHP: `"1e5"` is numeric and worth 100000, `" 12 "` is
+  numeric with whitespace on both ends.
+- `php_float("12abc")` is `12.0`, not an error.
+- `php_json_encode` uses compact separators and escapes `/` as `\/`.
+
+### 3. String indexing is a THIRD scheme, and it agrees by accident
+
+PHP indexes the markdown tokenizer and the syntax highlighter by **byte**; the
+Node port by **UTF-16 code unit**; Python by **codepoint**. All three agree, and
+the reason is worth keeping in mind before any "tidy": every cut is at an ASCII
+marker, and no UTF-8 continuation byte or UTF-16 surrogate half can equal an
+ASCII byte. The `unicodeText` fixture and the `fancy-conformance`
+`shared/strings` suite pin it. Changing either tokenizer to slice differently
+would be invisible in every existing test but this one.
+
+### 4. Read XML with a parser — but reject DOCTYPE first
+
+`reader/pptx_reader.py` uses `xml.etree.ElementTree` and matches on LOCAL names,
+ignoring namespace binding. That is fine: nothing is serialised on the read
+side, so no byte contract exists to protect.
+
+`_parse_xml` refuses any input containing `<!DOCTYPE` **before the parser sees
+it**. A `.pptx` never legitimately carries one, and the input is a file someone
+uploaded.
+
+### 5. `allow_http_images` defaults to `False`, and stays that way
+
+Fetching a URL named inside a document is an SSRF surface. `data:` URIs,
+`file://` and local paths work unconditionally; `http(s)` needs
+`{"allow_http_images": True}` from the caller. The `imageFallback` fixture
+asserts the default emits an `[image: …]` placeholder and makes no request.
+
+### 6. Determinism is required, so the clock is an INPUT
+
+`test_determinism.py` asserts byte stability, and `fancy-conformance` treats a
+determinism flag as a precondition for a writer suite. PHP stamps
+`docProps/core.xml` with `gmdate()` at write time and offers no way to pin it,
+so this port reads `metadata.created` / `metadata.modified` when the deck
+supplies them and falls back to `EPOCH_TIMESTAMP` otherwise. That is the ONE
+entry in `KNOWN_DIVERGENT_PARTS`, and it names the reason.
+
+### 7. The rel-id collision is reproduced, not fixed
+
+Image relationship ids come from a **global** media counter, while a slide's
+own rels start at `rId1` = layout and `rId2` = notesSlide. So one image on one
+slide already emits two `<Relationship Id="rId1">` entries. Relationship ids
+must be unique within a part, so the package is malformed — and every `.pptx`
+with an image that any of the three engines has ever written carries it.
+
+**Do not fix it here.** Fixing one engine alone breaks part-level parity, which
+is the only cross-runtime guarantee the trio has; the ruling is one coordinated
+release across every engine. The allocation site carries a `RULING PENDING:`
+comment, the `imageRelIds` fixture pins the current bytes, and
+`tests/test_relationship_id_collision.py` asserts the defect is still present —
+so the day the engines are fixed together, it fails and gets deleted.
+
+### 8. Python never casts a deciding vote on an open ruling
+
+Where the PHP and Node engines already disagree, **this port follows PHP**, so
+the tally stays 2-1 in the direction already recorded rather than becoming a
+three-way split. The live ones, all with tests:
+
+| Behaviour | PHP (and this port) | Node |
+|---|---|---|
+| `chart.mode` default | `"png"` — a pre-rendered `data:` image wins over a translatable `option` | always tries native translation first |
+| `{"id": null}` in the validator | no error (`isset()` is false for null) | flagged as a type error |
+| non-base64 `data:` URIs | percent-decoded to **bytes** | re-encoded as UTF-8, corrupting binary |
+| intrinsic size of a WebP / BMP | read, so `fit: cover` crops correctly | unread, so it stretches |
+| `option.categories` with no `xAxis` | ignored (a shared wart, pinned) | same |
+
+## Layout
+
+```
+src/dark_slide/
+  __init__.py            the public façade
+  agent.py               the Agent surface as module-level functions
+  exceptions.py          SchemaException (carries the structured error list)
+  util.py                PHP loose-typing semantics, written down once
+  schema/                schema.py · validator.py · repairer.py · types.py
+  writer/pptx_writer.py  string building; the byte contract lives here
+  reader/pptx_reader.py  ElementTree; best-effort, degrades rather than raises
+  helpers/               xml · color · emu (php_round) · markdown_inline
+                         · syntax_highlighter · chart_translator
+```
+
+## Running the suite
+
+```
+PHP_BIN='/path/to/php' python -m pytest
+```
+
+`pythonpath = ["src"]` is set, so a bare checkout with nothing but pytest runs
+it. **A missing PHP is a skip locally and a hard failure under `CI`** — a
+parity suite that quietly stops comparing anything reads exactly like one that
+compares everything, which is how two sibling suites reported green over zero
+coverage for months.

fancy_dark_slide-0.1.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+**Pre-1.0: breaking changes land in MINOR releases.** Until `1.0.0` a bumped
+minor may change an API, so read the entry before upgrading — the version
+number cannot make a promise the 0.x range does not allow it to keep.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-18
+
+### Added
+
+- **Initial release: the Python member of the `dark-slide` trio.** A
+  zero-dependency `.pptx` writer and reader, mirroring PHP
+  `particle-academy/dark-slide` and Node `@particle-academy/dark-slide`. The
+  same deck goes in and the same document comes out, whichever backend runs it.
+
+- **Byte-level writer parity with the PHP engine, as a test result.** The suite
+  drives the PHP writer as a subprocess and diffs every OOXML part for every
+  fixture. One part is excused, with the reason recorded in
+  `KNOWN_DIVERGENT_PARTS`: `docProps/core.xml` carries a write-time timestamp
+  PHP offers no way to pin, so this port takes the document date from
+  `metadata.created` / `metadata.modified` and is byte-stable instead. Every
+  other byte of that part matches.
+
+- **Structural reader parity with the PHP engine.** The same `.pptx` handed to
+  both readers recovers the same deck — compared structurally, with only the
+  volatile import `id` and the PHP empty-array/empty-object ambiguity
+  normalised away.
+
+- **The Agent surface** as module-level functions: `validate`,
+  `validate_and_repair`, `to_bytes`, `write`, `read`, `from_bytes`, `describe`,
+  `json_schema`, `version`. `write` is synchronous (PHP's is; Node's is async
+  only because browsers have no synchronous filesystem) and `read` accepts
+  **both bytes and a path**, resolving a real PHP↔Node divergence rather than
+  picking a side.
+
+- **`php_round`, and a test that forbids the builtin.** Python rounds half to
+  even and PHP rounds half away from zero, and every coordinate in a deck is a
+  `round(fraction × 9144000)`. An AST walk over the package fails the build if
+  `round()` is called anywhere, and the `roundingTies` fixture pins two real
+  ties against the PHP oracle.
+
+- **The image-header sniffer covers PNG, JPEG, GIF, WebP and BMP**, and is held
+  to PHP's `getimagesizefromstring` by a cross-runtime test. That is wider than
+  the Node port, which reads PNG/GIF/JPEG only — so a WebP with `fit: cover`
+  gets a real centre-crop here and in PHP, and a stretched fill in Node.
+
+- **The `imageRelIds` fixture**, pinning a defect rather than hiding it. Image
+  relationship ids come from a global media counter while a slide's own rels
+  start at `rId1`, so a single image on a single slide emits two
+  `<Relationship Id="rId1">` entries — a malformed OPC package that every
+  engine has always written. It is reproduced here deliberately: fixing one
+  engine alone would break part-level parity, so the fix has to land in all
+  three at once, and this fixture is what will prove it did.
+
+### Security
+
+- **`allow_http_images` defaults to `False`.** A document naming an `http(s)`
+  image does not cause a request; the caller opts in. A fixture asserts the
+  default emits a placeholder and fetches nothing.
+- **The reader refuses a DOCTYPE before parsing.** A `.pptx` never legitimately
+  contains one, and the input is a file someone uploaded.
+
+[Unreleased]: https://github.com/Particle-Academy/dark-slide-py/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Particle-Academy/dark-slide-py/releases/tag/v0.1.0

fancy_dark_slide-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

fancy_dark_slide-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.