queue: pytype 2024.10.11 - CI green on PR #2168; skills: gotchas 512-514

CI green on PR #2168: the cp312 riscv64 wheel builds from the upstream
checkout with cibuildwheel and the wheel's own unit suite passes (1746
passed, 22 skipped), with the publish job dry-running cleanly.

Three reusable findings from the port:

512 - pytest's --ignore/--ignore-glob are silently inert under
      --pyargs <pkg>; --deselect works and its nodeids are relative to
      the package directory, not the rootdir pytest prints.
513 - a wheel can carry the test modules but not the helper package
      they import; stage the helpers with test-sources and copy them
      into the installed package from test-command.
514 - a tool that models a target Python version caps the matrix by
      itself, invisibly to a build-and-import check.

Author: luhenry

.queue.yml

@@ -4052,9 +4052,9 @@ packages:
   version: 2024.10.11
   home: https://google.github.io/pytype
   repo: https://github.com/google/pytype
-  status: ci-running
+  status: in-review
   pr: https://github.com/riseproject-dev/python-wheels/pull/2168
-  notes: '6 Linux wheels upstream (abi: cp310,cp311,cp312); no riscv64 on PyPI or pypi.riseproject.dev.'
+  notes: 'PR #2168 open (branch pytype), CI green. Build-from-checkout with cibuildwheel, mirroring the manylinux_wheels job of upstream build.yml (which is just `pip wheel . --no-deps` + `auditwheel repair` inside the manylinux image); setup.py builds one pybind11 extension, pytype.typegraph.cfg, from six .cc files at cxx_std=20, no arch-specific code anywhere and no CMake/ninja involvement in the wheel build (ninja is only a runtime dep and has riscv64 wheels on PyPI). No patches needed. Matrix is cp312 only: pytype refuses to run under an interpreter past 3.12 (validate_version: "Python versions > 3.12 are not yet supported"), which is why upstream ships cp310-cp312; the extension itself compiles and imports fine on cp313, so this only shows up when the tool actually runs (new gotcha 514). Dependency closure resolves binary-only for riscv64 at cp312 with our registry in play - libcst 1.8.6 and msgspec 0.21.1 come from pypi.riseproject.dev, the rest from PyPI. First CI run failed in the test phase only: pip picked libcst 1.9.0, whose riscv64 form is an sdist needing Rust, over our registry''s 1.8.6 wheel; fixed with CIBW_TEST_ENVIRONMENT PIP_ONLY_BINARY=:all: (gotchas 12/67). Testing runs the wheel''s own 96 *_test.py modules via `pytest --pyargs pytype -n auto` plus a one-file `pytype` CLI run; the pytype.tests helpers those modules import are excluded from the wheel, so three of them are staged with CIBW_TEST_SOURCES and copied into the installed package (new gotcha 513), and nine nodeids are deselected - source-tree-only tests (main_test.py, test_error_doc, two typeshed ones), a root-only one (test_die), two serialize_ast tests that fail identically on a pristine x86 checkout of the same tag, and the two staged helpers themselves. --ignore-glob turned out to be a no-op under --pyargs, which cost the first CI cycle''s triage (new gotcha 512). Rehearsed end to end on x86_64 before pushing (same 1746 passed / 22 skipped as CI). riscv64 CI: wheel built and auditwheel-repaired to manylinux_2_39_riscv64 in ~7 min, 1746 passed / 22 skipped in 8 min, publish job dry-ran cleanly. Left as a draft for the maintainer; not merged, not published.'
 - pkg: pytorch-tokenizers
   version: 1.4.1
   home: https://pytorch.org/executorch/

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

@@ -409,6 +409,9 @@ The porting gotchas (500 of them) live in [`references/gotchas/`](gotchas/), spl
   matrix: `false` means one `py3-none-<platform>` wheel and a single cibuildwheel job,
   bindings mean a real per-interpreter matrix; the queue note's `abi: 0` cannot tell them
   apart.
+- **514** — A tool that models a *target* Python version caps the matrix itself — the extension
+  compiles and imports on every interpreter, so run the tool's CLI, not `import`, to find the
+  ceiling (the pytype case).
 
 ### Rust, maturin & PyO3 — [`gotchas/rust-maturin-and-pyo3.md`](gotchas/rust-maturin-and-pyo3.md)
 
@@ -846,6 +849,9 @@ The porting gotchas (500 of them) live in [`references/gotchas/`](gotchas/), spl
 - **501** — A separate test job checks the upstream tree out again and needs the same
   `git apply` the build job has; the tell is a failure returning byte-for-byte after you
   fixed it (the austin-dist case).
+- **513** — The wheel ships the tests but not the `<pkg>.tests` helpers they import: stage the
+  helper modules with `test-sources` and copy them into the installed package from
+  `test-command` (the pytype case).
 
 ### Testing: pytest config, servers & test selection — [`gotchas/pytest-config-servers-and-selection.md`](gotchas/pytest-config-servers-and-selection.md)
 
@@ -883,6 +889,9 @@ The porting gotchas (500 of them) live in [`references/gotchas/`](gotchas/), spl
 - **489** — A hundreds-of-MB upstream test-data tree can be left out of the checkout with
   non-cone sparse-checkout (which also switches `actions/checkout` to a `blob:none` clone),
   and the suite selected as the complement of the modules that grep for the data constant.
+- **512** — `--ignore`/`--ignore-glob` are silently inert under `pytest --pyargs <pkg>`; cut
+  tests with `--deselect`, whose nodeids are relative to the package directory rather than the
+  rootdir pytest prints, and confirm the count with `--co -q`.
 
 ### Test failures, flakes & arch-specific bugs — [`gotchas/test-failures-and-flakes.md`](gotchas/test-failures-and-flakes.md)
 

skills/python-project-porting/references/gotchas/cibuildwheel-matrix-and-abi3.md

@@ -54,6 +54,8 @@ To pull up one entry: `grep -n '^N\. ' references/gotchas/cibuildwheel-matrix-an
   newer-Python-only API fails our CI while upstream's own CI stays green.
 - **487** — `[tool.cmeel] has-sitelib` decides whether a cmeel port needs an interpreter
   matrix at all.
+- **514** — A tool that models a *target* Python version caps the matrix itself; its extension
+  compiles on every interpreter, so only running the tool shows it.
 
 ---
 
@@ -1033,3 +1035,17 @@ To pull up one entry: `grep -n '^N\. ' references/gotchas/cibuildwheel-matrix-an
     - `CIBW_REPAIR_WHEEL_COMMAND: ""` still applies to both: cmeel links its libraries with
       an `$ORIGIN` RUNPATH into the shared cmeel prefix, and auditwheel would only re-tag
       them, which is why upstream's own release workflow disables repair.
+
+
+514. **A tool that models a *target* Python version caps the matrix by itself — its extension
+    still compiles everywhere, so only running the tool shows it (the pytype case).** pytype
+    2024.10.11 builds and installs cleanly on cp313: its pybind11 typegraph extension uses no
+    version-specific C API, and `pytype --version` prints. The first real analysis then raises
+    `UsageError: Python versions > 3.12 are not yet supported` from `validate_version` in
+    `pytype/utils.py`, because the target version defaults to the host's and the opcode tables
+    stop at 3.12. Upstream's cp310-cp312-only wheel set is the tell, and the matrix has to
+    follow it (`python: ["cp312"]` here) even though cp313/cp314 wheels would build and pass
+    an import check. Exercise the tool's front door — the CLI on a two-line file, not
+    `import <pkg>` — on the newest interpreter of the default matrix before committing to it.
+    Applies to anything that consumes the bytecode or AST details of the interpreter it runs
+    on: type checkers, bytecode rewriters, coverage/debug tooling.

skills/python-project-porting/references/gotchas/pytest-config-servers-and-selection.md

@@ -39,6 +39,8 @@ To pull up one entry: `grep -n '^N\. ' references/gotchas/pytest-config-servers-
   the whole package invents failures; run each file as its own absltest script.
 - **489** — An upstream test-data tree of hundreds of MB can be left out of the checkout
   entirely, and the suite selected as the complement of the modules that read it.
+- **512** — `--ignore`/`--ignore-glob` do nothing under `pytest --pyargs <pkg>`; cut tests with
+  `--deselect`, whose nodeids are relative to the package dir, not the printed rootdir.
 
 ---
 
@@ -760,3 +762,27 @@ To pull up one entry: `grep -n '^N\. ' references/gotchas/pytest-config-servers-
     - Rehearse the complement off-target first (gotcha 52): the two modules that needed the
       tree failed identically on x86_64, which is how the split was found without spending a
       riscv64 cycle on it.
+
+
+512. **`--ignore`/`--ignore-glob` do nothing under `pytest --pyargs <pkg>` — cut tests with
+    `--deselect`, and count what it removed (the pytype case).** When the test command runs an
+    installed package's own tests with `--pyargs <pkg>`, the usual "don't collect this file"
+    knobs are silently inert: pytest applies `--ignore`/`--ignore-glob` while recursing into
+    *directory* arguments, and a `--pyargs` argument is resolved straight to the imported
+    package's path instead. It fails quietly — the collection count is identical with and
+    without the flag (`--co -q` printed `1820 tests collected` for
+    `--ignore-glob='*/pytype/main_test.py'`, `'*main_test.py'` and
+    `'*site-packages/pytype/main_test.py'` alike) — and you find out when the tests you thought
+    you had removed fail in CI.
+    - **`--deselect` does work, and takes a plain file path as well as a
+      `file.py::Class::test` nodeid**, so dropping a whole module is one flag.
+    - **Its paths are relative to the collected package's own directory, not to the `rootdir`
+      pytest prints.** Running `--pyargs pytype` from a `test-sources` staging dir, pytest
+      reports `rootdir: <staging dir>` while the nodeids are `main_test.py` and
+      `pytd/serialize_ast_test.py::SerializeAstTest::test_unrestorable_child` — relative to
+      `site-packages/pytype`. An absolute `--deselect /…/site-packages/pytype/main_test.py`
+      matches nothing, and site-packages sits at a different absolute path in the container
+      anyway, so the relative form is also the portable one.
+    - **Verify with `--co -q` before pushing.** It prints `1768/1820 tests collected (52
+      deselected)`; a typo'd nodeid is ignored without a warning, so that count is the only
+      proof the deselection did anything.

skills/python-project-porting/references/gotchas/testing-and-shadowing.md

@@ -31,6 +31,8 @@ To pull up one entry: `grep -n '^N\. ' references/gotchas/testing-and-shadowing.
   portion and does not shadow the wheel.
 - **501** — A separate test job checks the upstream tree out again, so it needs the same
   `git apply` the build job has, or the failure you just fixed comes back unchanged.
+- **513** — The wheel ships the tests but not the test *helpers* they import — copy the helper
+  package into the installed package from `test-command`.
 
 ---
 
@@ -559,3 +561,36 @@ To pull up one entry: `grep -n '^N\. ' references/gotchas/testing-and-shadowing.
       log. Check which job the failing step is in before re-reading the patch.
     - Keep the two steps identical (checkout with `path: python-wheels`, then the same glob)
       so the next person sees one pattern rather than two.
+
+
+513. **The wheel ships the tests but not the test *helpers* they import — copy the helper
+    package into the installed package from `test-command` (the pytype case).** pytype's
+    `setup.cfg` excludes `pytype.tests` from `packages.find`, yet 36 of the 96 `*_test.py`
+    modules that *are* in the wheel open with `from pytype.tests import test_base`, so
+    `pytest --pyargs pytype` dies at collection with `ModuleNotFoundError: No module named
+    'pytype.tests'`. This is the mirror image of gotcha 148: there the suite sits inside the
+    importable package and shadows it, here the suite is inside the *wheel* and its helpers
+    are missing. Staging them in the test cwd cannot fix it — they have to be importable as a
+    subpackage of the *installed* package:
+    ```yaml
+    CIBW_TEST_SOURCES: pytype/tests/__init__.py pytype/tests/test_base.py pytype/tests/test_utils.py
+    CIBW_TEST_COMMAND: >-
+      cp -r pytype/tests "$(python -c 'import pytype, os; print(os.path.dirname(pytype.__file__))')"
+      && python -m pytest --pyargs pytype ...
+    ```
+    - **Stage the helper modules only, never the whole suite directory.** Copying upstream's
+      full `<pkg>/tests/` in makes `--pyargs` collect the entire integration suite as well
+      (142 files for pytype, hours on a riscv64 runner) on top of the unit tests you wanted.
+    - **The helpers are themselves named `test_*.py`, so pytest collects them as tests**
+      (`tests/test_utils.py::test_data_file` then errors on a missing fixture); deselect them
+      (gotcha 512) rather than renaming, since the imports name them.
+    - **Diff against a source checkout before blaming the wheel or the arch.** Of the failures
+      left under `--pyargs`, `test_error_doc` and two typeshed ones read `docs/errors.md` and
+      `typeshed/tests/`, which are in neither the wheel nor the sdist, while two
+      `serialize_ast` tests fail identically in a pristine x86 `git clone --branch <tag>`
+      under plain `unittest`. Cloning the tag and dropping the built `.so` into it separates
+      "not in the wheel", "broken upstream" and "riscv64" in five minutes.
+    - **A test that asserts an operation *fails* for lack of privilege only passes as a
+      non-root user.** `tool_utils_test.TestMakeDirsOrDie.test_die` expects
+      `makedirs_or_die('/nonexistent/path')` to raise `SystemExit`; the build container runs
+      as root, where it simply creates the directory.