ruff-format: PR #2198 fully green, add gotcha 559 (pure-Rust maturin __file__ shim)

Replicates PR #2264's bookkeeping directly to main (renumbered 558->559 to
avoid colliding with ifcopenshell's concurrently-landed 558) since that PR's
own agent hit a permission wall pushing to main directly.

Author: luhenry

.queue.yml

@@ -8427,9 +8427,9 @@ packages:
   version: 0.5.4
   home: https://github.com/reflex-dev/ruff-format
   repo: https://github.com/reflex-dev/ruff-format
-  status: ci-running
+  status: ci-green
   pr: https://github.com/riseproject-dev/python-wheels/pull/2198
-  notes: '20 Linux wheels upstream (abi: cp314,cp38); no riscv64 on PyPI or pypi.riseproject.dev. FEASIBLE and ported: a PyO3/maturin extension (pyo3 abi3-py38 unconditional in Cargo.toml) that vendors ruff_python_parser/ruff_python_formatter from astral-sh/ruff.git as Cargo git dependencies -- it has no runtime Python dependency on the `ruff` PyPI package, so the initial concern about ruff''s own riscv64 status was a non-issue (same shape as complexipy/chalkpy-rs, already ported). Local cargo check --locked --target riscv64gc-unknown-linux-gnu passes clean. Matrix: cp38-abi3 (built on cp39, image floor) + cp314t. Upstream ships no test suite; CIBW_TEST_COMMAND exercises is_valid_syntax/parse_code/format_string against outputs verified with the real ruff CLI locally. PR #2198 open, CI dispatched.'
+  notes: '20 Linux wheels upstream (abi: cp314,cp38); no riscv64 on PyPI or pypi.riseproject.dev. FEASIBLE and ported: a PyO3/maturin extension (pyo3 abi3-py38 unconditional in Cargo.toml) that vendors ruff_python_parser/ruff_python_formatter from astral-sh/ruff.git as Cargo git dependencies -- it has no runtime Python dependency on the `ruff` PyPI package, so the initial concern about ruff''s own riscv64 status was a non-issue (same shape as complexipy/chalkpy-rs, already ported). Local cargo check --locked --target riscv64gc-unknown-linux-gnu passes clean. Matrix: cp38-abi3 (built on cp39, image floor) + cp314t. First CI run only produced a cp314t job and failed there: the include-only tag/build keys collapsed the matrix onto one combination (gotcha 402 shape) and the smoke test probed the maturin package shim''s __file__ instead of the compiled submodule (gotcha 308 shape, generalized in new gotcha 559 to apply unconditionally to any pure-Rust maturin project, not only on a name collision). Fixed both: tag: [cp38-abi3, cp314t] added as a real matrix dimension, and the probe rewritten as sys.modules[''ruff_format.ruff_format''].__file__. Run 35941432233 green on both build legs plus the publish dry run. PR #2198 ready for review.'
 - pkg: arro3-io
   version: 0.8.2
   home: https://kylebarron.dev/arro3

skills/python-project-porting/references/gotchas-index.md

@@ -917,6 +917,7 @@ The porting gotchas (546 of them) live in [`references/gotchas/`](gotchas/), spl
 - **292** — Gotcha 81's "diff the wheel `size` field" test can pass on a real per-arch binary
 - **295** — A require-extension knob that reaches the container correctly (gotcha 129's
 - **308** — A maturin shim whose star-import name collides with the compiled submodule's
+- **559** — A pure-Rust maturin project's top-level `__file__` never points at the `.so` —
 - **398** — Reproducing a `py3-none-<platform>` wheel takes an explicit retag — setuptools'
 - **457** — On cp314t our registry can hand a package a *compiled* dependency wheel where
 - **510** — A cffi *ABI-mode* payload keeps its `py3-none` tag through `auditwheel repair` —

skills/python-project-porting/references/gotchas/compiled-vs-pure-detection.md

@@ -20,6 +20,7 @@ To pull up one entry: `grep -n '^N\. ' references/gotchas/compiled-vs-pure-detec
 - **292** — Gotcha 81's "diff the wheel `size` field" test can pass on a real per-arch binary
 - **295** — A require-extension knob that reaches the container correctly (gotcha 129's
 - **308** — A maturin shim whose star-import name collides with the compiled submodule's
+- **559** — A pure-Rust maturin project's top-level `__file__` never points at the `.so` —
 - **398** — Reproducing a `py3-none-<platform>` wheel takes an explicit retag — setuptools'
 - **457** — On cp314t our registry can hand a package a *compiled* dependency wheel where
 - **510** — A cffi *ABI-mode* payload keeps its `py3-none` tag through `auditwheel repair` —
@@ -395,6 +396,38 @@ To pull up one entry: `grep -n '^N\. ' references/gotchas/compiled-vs-pure-detec
       `murmurhash2/murmurhash2.abi3.so` next to each other names both the shim and the
       real extension before a single CI cycle is spent on the wrong probe.
 
+559. **A pure-Rust maturin project's top-level `__file__` never points at the `.so` — not
+    just when a name collides with gotcha 308's shim (the ruff-format case; see
+    `build-ruff-format.yml`).** Gotcha 308 covers a *collision*: the generated
+    `__init__.py`'s `from .<mod> import *` overwriting the submodule attribute with a
+    same-named exported function, which raises `AttributeError` on `.__file__`. A pure-Rust
+    maturin crate with no such collision fails the same probe more quietly: `import
+    ruff_format as m; m.__file__` resolves fine, but to the generated
+    `ruff_format/__init__.py` (a `.py` file) — `m.__file__.endswith('.so')` is just `False`,
+    no exception, easy to mistake for "the wheel shipped pure Python". maturin makes this
+    call from the checked-out file layout alone (`project_layout.rs`'s `determine()`: no
+    `<module>/__init__.py` next to `Cargo.toml` and no `[tool.maturin] python-source` means
+    "pure Rust", and `module_dir()`'s own doc comment says outright that the module dir it
+    returns *is* the generated package around the extension) — before it ever knows which
+    interpreter it's building for, so the same shim ships identically on an abi3 leg and a
+    free-threaded leg of the same crate. The build log's "Found type stub file at
+    `<mod>.pyi`" line is a red herring here too: it means a `.pyi` rides along inside that
+    generated package, not that the layout is somehow different because of it.
+    - **Use gotcha 308's `sys.modules` fix unconditionally for any pure-Rust maturin
+      project**, not only after a collision bites: `python -c "import <mod>, sys; assert
+      sys.modules['<mod>.<mod>'].__file__.endswith('.so')"`. Cheaper still, `unzip -l` on
+      the wheel shows the shim/extension pair (gotcha 9/56/308's standing advice) before
+      writing the probe at all.
+    - **Don't blame the interpreter for a per-leg failure until the sibling leg has
+      actually run.** `build-ruff-format.yml`'s first CI run showed the failure on
+      `cp314t` only — but that was gotcha 402's matrix collapse (the `include:`-only
+      `tag`/`build` keys folded both legs into one job), not evidence the smoke test was
+      somehow free-threading-specific: `cp38-abi3` had not run at all (absent from the job
+      list, not merely queued) and failed identically once the matrix fix let it run.
+      Check the run's job list against the declared legs before a diagnosis that starts
+      "only cp314t" — gotcha 402's own advice, worth repeating here because the two bugs
+      compounded in one PR.
+
 398. **Reproducing a `py3-none-<platform>` wheel takes an explicit retag — setuptools'
     `bdist_wheel` ignores `--python-tag` the moment `ext_modules` is non-empty (the
     mediapipe case; see `build-mediapipe.yml`).** Gotchas 81/145/292 settle how to *read*