Skip to content

docs: fix tensor shapes setup instructions - #4559

Open
ting-hong-shieh wants to merge 1 commit into
facebook:mainfrom
ting-hong-shieh:docs-tensor-shapes-setup
Open

docs: fix tensor shapes setup instructions#4559
ting-hong-shieh wants to merge 1 commit into
facebook:mainfrom
ting-hong-shieh:docs-tensor-shapes-setup

Conversation

@ting-hong-shieh

Copy link
Copy Markdown
Contributor

Summary

Fixes #3322.

The invalid-syntax error in #3322 follows from the setup that the tensor shapes
Getting Started page describes. The page says to copy tensor-shapes/ into your
project and point search_path at that directory, which has two consequences:

  • search_path pointing at tensor-shapes/ resolves neither torch nor
    shape_extensions. The stub packages sit one level down, in
    tensor-shapes/pyrefly-torch-stubs and tensor-shapes/pyrefly-shape-extensions.
  • A copy inside the project is checked as project code, so the PEP 696 type
    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-stubs and pyrefly-shape-extensions are on PyPI and versioned in
lockstep with Pyrefly, so this rewrites the section to install them instead of
copying them. That path needs no search-path entries and no python-version
change. 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 via project-excludes).

Two smaller fixes on the same page:

  • The "Hello world" example doesn't check clean against the current stubs. Shape
    type parameters need IntVar bounds, and Tensor takes 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.
  • Config keys use kebab-case (search-path) to match configuration.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/ at
7b32d64. hello_shapes.py is the example from the page.

Before — the setup exactly as the page describes it. pyrefly.toml with
search_path = ["tensor-shapes"], and the page's example verbatim:

ERROR Cannot find module `torch` [missing-import]
ERROR Cannot find module `torch.nn` [missing-import]
ERROR Cannot find module `torch` [missing-import]
ERROR Cannot find module `shape_extensions` [missing-import]
 INFO 4 errors

The python-version error in #3322. With the two search paths corrected so
that the stubs resolve, checking a stub file under python-version = "3.12":

$ pyrefly check tensor-shapes/pyrefly-torch-stubs/torch-stubs/nn/__init__.pyi
ERROR Cannot set default type for a type parameter on Python 3.12 (syntax was added in Python 3.13) [invalid-syntax]
...

The same command under python-version = "3.13" reports no invalid-syntax
errors.

After — the installed path. pip install pyrefly-torch-stubs into a Python
3.12 venv, pyrefly.toml containing only python-interpreter-path, no
search-path and no python-version, with the updated example:

$ pyrefly check hello_shapes.py
 INFO 0 errors

After — the local-copy path. Stubs copied into the project, both search paths
set, python-version = "3.12" and project-excludes = ["tensor-shapes/**"]:

$ pyrefly check hello_shapes.py
 INFO 0 errors

Same result with python-version = "3.13" and no project-excludes.

Stub precedence. To check that the installed path still works when the
runtime package is present, I put a py.typed torch package with no shape
information in the same site-packages and re-ran the check: still 0 errors, so
torch-stubs wins. 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 and
the 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.mdx writes Tensor[B, T, NEmbedding] and unbounded type
parameters), 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.

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.
@meta-codesync

meta-codesync Bot commented Aug 16, 2026

Copy link
Copy Markdown
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.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

mention torch stub version in doc

3 participants