docs: fix tensor shapes setup instructions - #4559
Open
ting-hong-shieh wants to merge 1 commit into
Open
Conversation
The Getting Started page told users to copy the stub tree into their project and point search-path at it. That resolves neither torch nor shape_extensions, and it makes Pyrefly check the stubs as project code, where their PEP 696 type parameter defaults fail to parse below python-version 3.13 (facebook#3322). The stubs are published on PyPI in lockstep with Pyrefly, so document installing them as the main path; it needs no search-path and no python-version change. Keep the local-copy setup for people modifying the stubs, with the search paths it actually needs and both ways to keep the copy out of checking. Also update the Hello world example, which no longer checked clean against the stubs.
Contributor
|
This pull request has been imported. If you are a Meta employee, you can view this in D116223386. (Because this pull request was imported automatically, there will not be any future comments.) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #3322.
The
invalid-syntaxerror in #3322 follows from the setup that the tensor shapesGetting Started page describes. The page says to copy
tensor-shapes/into yourproject and point
search_pathat that directory, which has two consequences:search_pathpointing attensor-shapes/resolves neithertorchnorshape_extensions. The stub packages sit one level down, intensor-shapes/pyrefly-torch-stubsandtensor-shapes/pyrefly-shape-extensions.parameter defaults in the stubs are parsed under the project's
python-version.Below 3.13 that produces the error in mention torch stub version in doc #3322.
pyrefly-torch-stubsandpyrefly-shape-extensionsare on PyPI and versioned inlockstep with Pyrefly, so this rewrites the section to install them instead of
copying them. That path needs no
search-pathentries and nopython-versionchange. The copy-based setup stays for people who want to read or modify the
stubs, now under its own heading, with the two search paths it actually needs and
with both ways to stop the stubs being checked under an older
python-version(raise
python-version, or exclude the copy viaproject-excludes).Two smaller fixes on the same page:
type parameters need
IntVarbounds, andTensortakes a single shape list.It now matches the style in
tensor-shapes/pyrefly-torch-stubs/examples/nanogpt.py,so the page's "You should see no errors" holds.
search-path) to matchconfiguration.mdx.snake_case still works as an alias, but the rest of the docs use kebab-case.
Test Plan
pyrefly 1.2.0 (PyPI), Linux, project stubs copied from
tensor-shapes/at7b32d64.hello_shapes.pyis the example from the page.Before — the setup exactly as the page describes it.
pyrefly.tomlwithsearch_path = ["tensor-shapes"], and the page's example verbatim:The
python-versionerror in #3322. With the two search paths corrected sothat the stubs resolve, checking a stub file under
python-version = "3.12":The same command under
python-version = "3.13"reports noinvalid-syntaxerrors.
After — the installed path.
pip install pyrefly-torch-stubsinto a Python3.12 venv,
pyrefly.tomlcontaining onlypython-interpreter-path, nosearch-pathand nopython-version, with the updated example:After — the local-copy path. Stubs copied into the project, both search paths
set,
python-version = "3.12"andproject-excludes = ["tensor-shapes/**"]:Same result with
python-version = "3.13"and noproject-excludes.Stub precedence. To check that the installed path still works when the
runtime package is present, I put a
py.typedtorchpackage with no shapeinformation in the same
site-packagesand re-ran the check: still 0 errors, sotorch-stubswins. That was a stand-in package, not a real PyTorch install.Not covered: I did not run
test.py, since this change is documentation only andthe formatting step it runs is
cargo fmt. The website build runs in CI.AI usage disclosure
Per the AI Usage section of CONTRIBUTING.md: the documentation rewrite, the
reproductions in the test plan, and this description were produced by an AI agent
(Claude Code) working in my checkout. I reviewed them before submitting. Any
replies I make on this PR will carry the same disclosure if an agent drafts them.
Remaining, not in this PR
The old shape syntax is still used elsewhere in the tensor shapes docs
(
tensor-shapes.mdxwritesTensor[B, T, NEmbedding]and unbounded typeparameters), and the inlay-hint screenshots on this page show it too. That looks
related to #4153. Happy to open a separate issue or PR for it.