Skip to content

gh-115881: Document feature_version limitations #115980

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 29, 2024
Merged

gh-115881: Document feature_version limitations #115980

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3ee0c93
gh-115881: Document feature_version limitations
hauntsaninja Feb 26, 2024
5973a92
Be more explicit
hauntsaninja Feb 28, 2024
fbfd4ee
.
hauntsaninja Feb 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions Doc/library/ast.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2180,12 +2180,15 @@ and classes for traversing abstract syntax trees:
modified to correspond to :pep:`484` "signature type comments",
e.g. ``(str, int) -> List[str]``.

Also, setting ``feature_version`` to a tuple ``(major, minor)``
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest adding maybe a modal box to highlight this a bit more?

will attempt to parse using that Python version's grammar.
Currently ``major`` must equal to ``3``. For example, setting
``feature_version=(3, 4)`` will allow the use of ``async`` and
``await`` as variable names. The lowest supported version is
``(3, 7)``; the highest is ``sys.version_info[0:2]``.
Setting ``feature_version`` to a tuple ``(major, minor)`` will result in
a "best-effort" attempt to parse using that Python version's grammar.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe also explicitly state that it's not guaranteed to disallow all constructs that weren't possible in a specific version?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would even mention some of them:

  • with (current issue)
  • relaxed grammar for decorators
  • maybe something else?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I pushed a commit that expands what "best-effort" means, lysnikolaou let me know if that improves the explicitness!

I think I'd prefer not to get into details. I don't want users to expect that we list all divergences in behaviour here, nor do I think listing all divergences would be particularly useful for current users of feature_version.

For example, setting ``feature_version=(3, 9)`` will attempt to disallow
parsing of :keyword:`match` statements.
Currently ``major`` must equal to ``3``. The lowest supported version is
``(3, 7)`` (and this may increase in future Python versions);
the highest is ``sys.version_info[0:2]``. "Best-effort" attempt means there
is no guarantee that the parse (or success of the parse) is the same as
when run on the Python version corresponding to ``feature_version``.

If source contains a null character ('\0'), :exc:`ValueError` is raised.

Expand Down