From a188aeb7b51ca561fcaa11dbc00661c8306145f2 Mon Sep 17 00:00:00 2001 From: David Peter Date: Tue, 13 May 2025 09:33:35 +0200 Subject: [PATCH] Minor clarifications in Python version docs (#344) ## Summary This is unfortunately longer than what we had, but I thought that this section could use some clarification. In particular, newer syntactic features can not appear in `sys.version_info` branches, they will always lead to errors. --- docs/README.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/README.md b/docs/README.md index 2606131..0b43636 100644 --- a/docs/README.md +++ b/docs/README.md @@ -111,17 +111,26 @@ The Python version affects allowed syntax, type definitions of the standard libr definitions of first- and third-party modules that are conditional on the Python version. For example, Python 3.10 introduced support for `match` statements and added the -`sys.stdlib_module_names` symbol to the standard library. However, if your project also supports -Python 3.9, you cannot use these new features unless they are used in a `sys.version_info` -conditional branch: +`sys.stdlib_module_names` symbol to the standard library. Syntactic features always +need to be available in the lowest supported Python version, but symbols may be used +in a `sys.version_info` conditional branch: ```python import sys +# `invalid-syntax` error if `python-version` is set to 3.9 or lower: +match "echo hello".split(): + case ["echo", message]: + print(message) + case _: + print("unknown command") + +# `unresolved-attribute` error if `python-version` is set to 3.9 or lower: +print(sys.stdlib_module_names) + if sys.version_info >= (3, 10): - print(sys.stdlib_module_names) # ok -else: - print(sys.stdlib_module_names) # error if `python-version` is set to 3.9 or lower + # ok, because the usage is guarded by a version check: + print(sys.stdlib_module_names) ``` By default, the lower bound of the project's [`requires-python`](<(https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#python-requires)>) field (from the `pyproject.toml`) is