From 9277e1aba3e283bae47c4c8de7fa492b81f1ac0f Mon Sep 17 00:00:00 2001 From: anujrmohite Date: Fri, 24 Nov 2023 02:05:16 +0530 Subject: [PATCH 1/6] Added Improvements for future module #110893 --- Doc/library/__future__.rst | 69 ++++++++++++++++++++------------------ 1 file changed, 37 insertions(+), 32 deletions(-) diff --git a/Doc/library/__future__.rst b/Doc/library/__future__.rst index d261e4a4f338a5..fd55678d9dd2e6 100644 --- a/Doc/library/__future__.rst +++ b/Doc/library/__future__.rst @@ -8,19 +8,25 @@ -------------- -:mod:`__future__` is a real module, and serves three purposes: +* To use a specific feature, import it from the :mod:`__future__` module using the + syntax `from __future__ import `. It is important to note that the + `__future__ import` statement must be placed as the first statement in the + source file, except for a module docstring. + +* If a feature has been imported, the `__future__ import` remains valid even + after the *MandatoryRelease* version. However, it has no behavioural effect. + code will be compatible with multiple versions during the transition phase of + a feature. If code only supports versions greater than or equal to the + *MandatoryRelease* version, then no longer need to include the `__future__ + import` for that specific feature. + +* Once a feature has been imported, :ref:`future` import remains valid + even after the *MandatoryRelease* version. However, it has no behavioural effect. + So this code will be compatible with multiple versions during the transition + phase of a feature. If code only supports versions greater than or equal to + the *MandatoryRelease* version, then no longer need to include the + :mod:`__future__` import for that specific feature. -* To avoid confusing existing tools that analyze import statements and expect to - find the modules they're importing. - -* To ensure that :ref:`future statements ` run under releases prior to - 2.1 at least yield runtime exceptions (the import of :mod:`__future__` will - fail, because there was no module of that name prior to 2.1). - -* To document when incompatible changes were introduced, and when they will be - --- or were --- made mandatory. This is a form of executable documentation, and - can be inspected programmatically via importing :mod:`__future__` and examining - its contents. .. _future-classes: @@ -34,36 +40,35 @@ where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are 5-tuples of the same form as :data:`sys.version_info`:: - (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int - PY_MINOR_VERSION, # the 1; an int - PY_MICRO_VERSION, # the 0; an int - PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string - PY_RELEASE_SERIAL # the 3; an int + (PY_MAJOR_VERSION, # the major version number,"2" in "2.1.0a3"; an integer + PY_MINOR_VERSION, # the minor version number,"1" in "2.1.0a3"; an integer + PY_MICRO_VERSION, # the micro version number,"0" in "2.1.0a3"; an integer + PY_RELEASE_LEVEL, # "alpha", "beta", "candidate", or "final"; a string + PY_RELEASE_SERIAL, # the release serial number,"3" in "2.1.0a3"; an integer ) +The release information for features is captured through *OptionalRelease* and *MandatoryRelease*. +The *OptionalRelease* records the first release in which the feature was accepted, and +*MandatoryRelease* records when the feature became part of the language. Once a feature is included +in a *MandatoryRelease*, modules no longer need a future statement to use the feature, but they may +continue to use such imports if needed. + .. method:: _Feature.getOptionalRelease() - *OptionalRelease* records the first release in which the feature was accepted. + 'getOptionalRelease()': This method returns the release information for the + *OptionalRelease* of a specific feature. .. method:: _Feature.getMandatoryRelease() - In the case of a *MandatoryRelease* that has not yet occurred, - *MandatoryRelease* predicts the release in which the feature will become part of - the language. - - Else *MandatoryRelease* records when the feature became part of the language; in - releases at or after that, modules no longer need a future statement to use the - feature in question, but may continue to use such imports. - - *MandatoryRelease* may also be ``None``, meaning that a planned feature got - dropped or that it is not yet decided. + 'getMandatoryRelease()': This method returns the release information for the + *MandatoryRelease* of a specific feature. .. attribute:: _Feature.compiler_flag - *CompilerFlag* is the (bitfield) flag that should be passed in the fourth - argument to the built-in function :func:`compile` to enable the feature in - dynamically compiled code. This flag is stored in the :attr:`_Feature.compiler_flag` - attribute on :class:`_Feature` instances. + The *CompilerFlag* is a bitfield flag that should be passed in the fourth argument to the + built-in function :func:`compile` in order to enable the feature in dynamically compiled code. + This flag is stored in the :attr:`_Feature.compiler_flag` attribute on :class:`_Feature` + instances. No feature description will ever be deleted from :mod:`__future__`. Since its introduction in Python 2.1 the following features have found their way into the From 5a3910c4dab34c5d1ec8e6f66d081e8bd554fd52 Mon Sep 17 00:00:00 2001 From: anujrmohite Date: Fri, 24 Nov 2023 02:33:00 +0530 Subject: [PATCH 2/6] Fix spaces --- Doc/library/__future__.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/__future__.rst b/Doc/library/__future__.rst index fd55678d9dd2e6..a971b1f3469193 100644 --- a/Doc/library/__future__.rst +++ b/Doc/library/__future__.rst @@ -40,10 +40,10 @@ where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are 5-tuples of the same form as :data:`sys.version_info`:: - (PY_MAJOR_VERSION, # the major version number,"2" in "2.1.0a3"; an integer - PY_MINOR_VERSION, # the minor version number,"1" in "2.1.0a3"; an integer - PY_MICRO_VERSION, # the micro version number,"0" in "2.1.0a3"; an integer - PY_RELEASE_LEVEL, # "alpha", "beta", "candidate", or "final"; a string + (PY_MAJOR_VERSION, # the major version number,"2" in "2.1.0a3"; an integer + PY_MINOR_VERSION, # the minor version number,"1" in "2.1.0a3"; an integer + PY_MICRO_VERSION, # the micro version number,"0" in "2.1.0a3"; an integer + PY_RELEASE_LEVEL, # "alpha", "beta", "candidate", or "final"; a string PY_RELEASE_SERIAL, # the release serial number,"3" in "2.1.0a3"; an integer ) From 8371486f3778526d04afb1926140ef11d093c7a5 Mon Sep 17 00:00:00 2001 From: anujrmohite Date: Fri, 24 Nov 2023 12:47:08 +0530 Subject: [PATCH 3/6] for inline literals used double backticks --- Doc/library/__future__.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/__future__.rst b/Doc/library/__future__.rst index a971b1f3469193..35df3913bddbc6 100644 --- a/Doc/library/__future__.rst +++ b/Doc/library/__future__.rst @@ -9,11 +9,11 @@ -------------- * To use a specific feature, import it from the :mod:`__future__` module using the - syntax `from __future__ import `. It is important to note that the - `__future__ import` statement must be placed as the first statement in the + syntax ``from __future__ import ``. It is important to note that the + ``__future__ import`` statement must be placed as the first statement in the source file, except for a module docstring. -* If a feature has been imported, the `__future__ import` remains valid even +* If a feature has been imported, the ``__future__ import`` remains valid even after the *MandatoryRelease* version. However, it has no behavioural effect. code will be compatible with multiple versions during the transition phase of a feature. If code only supports versions greater than or equal to the From 69f39dd23dc5ebdf681a30848b98f88712ef3401 Mon Sep 17 00:00:00 2001 From: anujrmohite Date: Sat, 2 Dec 2023 00:54:13 +0530 Subject: [PATCH 4/6] Improved future doc formatting --- Doc/library/__future__.rst | 72 ++++++++++++++++++-------------------- 1 file changed, 35 insertions(+), 37 deletions(-) diff --git a/Doc/library/__future__.rst b/Doc/library/__future__.rst index 35df3913bddbc6..4de26da175a831 100644 --- a/Doc/library/__future__.rst +++ b/Doc/library/__future__.rst @@ -8,25 +8,24 @@ -------------- -* To use a specific feature, import it from the :mod:`__future__` module using the - syntax ``from __future__ import ``. It is important to note that the - ``__future__ import`` statement must be placed as the first statement in the - source file, except for a module docstring. - -* If a feature has been imported, the ``__future__ import`` remains valid even - after the *MandatoryRelease* version. However, it has no behavioural effect. - code will be compatible with multiple versions during the transition phase of - a feature. If code only supports versions greater than or equal to the - *MandatoryRelease* version, then no longer need to include the `__future__ - import` for that specific feature. - -* Once a feature has been imported, :ref:`future` import remains valid - even after the *MandatoryRelease* version. However, it has no behavioural effect. - So this code will be compatible with multiple versions during the transition - phase of a feature. If code only supports versions greater than or equal to - the *MandatoryRelease* version, then no longer need to include the - :mod:`__future__` import for that specific feature. - +To use a specific feature, import it from the :mod:`__future__` module using +the syntax ``from __future__ import ``. It is important to note that +the ``__future__ import`` statement must be placed as the first statement in +the source file, except for a module docstring. + +If a feature has been imported, the ``__future__ import`` remains valid even +after the *MandatoryRelease* version. However, it has no behavioural effect. +code will be compatible with multiple versions during the transition phase of +a feature. If code only supports versions greater than or equal to the +*MandatoryRelease* version, then no longer need the `__future__ import` for +that specific feature. + +Once a feature has been imported, :ref:`future` import remains valid +even after the *MandatoryRelease* version. However, it has no behavioral effect. +So this code will be compatible with multiple versions during the transition +phase of a feature. If code only supports versions greater than or equal to +the *MandatoryRelease* version, then no longer need to include the +:mod:`__future__` import for that specific feature. .. _future-classes: @@ -40,35 +39,34 @@ where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are 5-tuples of the same form as :data:`sys.version_info`:: - (PY_MAJOR_VERSION, # the major version number,"2" in "2.1.0a3"; an integer - PY_MINOR_VERSION, # the minor version number,"1" in "2.1.0a3"; an integer - PY_MICRO_VERSION, # the micro version number,"0" in "2.1.0a3"; an integer - PY_RELEASE_LEVEL, # "alpha", "beta", "candidate", or "final"; a string - PY_RELEASE_SERIAL, # the release serial number,"3" in "2.1.0a3"; an integer + (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int + PY_MINOR_VERSION, # the 1; an int + PY_MICRO_VERSION, # the 0; an int + PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string + PY_RELEASE_SERIAL # the 3; an int ) -The release information for features is captured through *OptionalRelease* and *MandatoryRelease*. -The *OptionalRelease* records the first release in which the feature was accepted, and -*MandatoryRelease* records when the feature became part of the language. Once a feature is included -in a *MandatoryRelease*, modules no longer need a future statement to use the feature, but they may -continue to use such imports if needed. +The release information for features is captured through *OptionalRelease* and +*MandatoryRelease*. The *OptionalRelease* records the first release in which the +feature was accepted, *MandatoryRelease* records when the feature became part +of the language. Once a feature is included in a *MandatoryRelease*, modules no +longer need a future statement to use the feature, but they may continue to use +such imports if needed. .. method:: _Feature.getOptionalRelease() - 'getOptionalRelease()': This method returns the release information for the - *OptionalRelease* of a specific feature. + This method returns the release information for the OptionalRelease of a feature. .. method:: _Feature.getMandatoryRelease() - 'getMandatoryRelease()': This method returns the release information for the - *MandatoryRelease* of a specific feature. + This method returns the release information for the MandatoryRelease of a feature. .. attribute:: _Feature.compiler_flag - The *CompilerFlag* is a bitfield flag that should be passed in the fourth argument to the - built-in function :func:`compile` in order to enable the feature in dynamically compiled code. - This flag is stored in the :attr:`_Feature.compiler_flag` attribute on :class:`_Feature` - instances. + The *CompilerFlag* is a bitfield flag that should be passed in the fourth + argument to the built-in function :func:`compile` in order to enable the + feature in dynamically compiled code. This flag is stored in the + :attr:`_Feature.compiler_flag` attribute on :class:`_Feature` instances. No feature description will ever be deleted from :mod:`__future__`. Since its introduction in Python 2.1 the following features have found their way into the From 6c3f7418c3d18b6c5a57d3bf55e9084baaf37d12 Mon Sep 17 00:00:00 2001 From: anujrmohite Date: Sat, 2 Dec 2023 01:08:41 +0530 Subject: [PATCH 5/6] Lint fix --- Doc/library/__future__.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/__future__.rst b/Doc/library/__future__.rst index 4de26da175a831..a1d8d15fae4d17 100644 --- a/Doc/library/__future__.rst +++ b/Doc/library/__future__.rst @@ -17,7 +17,7 @@ If a feature has been imported, the ``__future__ import`` remains valid even after the *MandatoryRelease* version. However, it has no behavioural effect. code will be compatible with multiple versions during the transition phase of a feature. If code only supports versions greater than or equal to the -*MandatoryRelease* version, then no longer need the `__future__ import` for +*MandatoryRelease* version, then no longer need the ``__future__ import`` for that specific feature. Once a feature has been imported, :ref:`future` import remains valid From ee7b9e2976058d9eabe8f58ba4d2b1ad9be1f5c6 Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Sun, 25 Feb 2024 00:02:52 -0500 Subject: [PATCH 6/6] Fix version tuple. Deleting initial spaces was a mistake. PEP 8 comments are sentences. --- Doc/library/__future__.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/__future__.rst b/Doc/library/__future__.rst index a1d8d15fae4d17..7f1130cea54532 100644 --- a/Doc/library/__future__.rst +++ b/Doc/library/__future__.rst @@ -39,11 +39,11 @@ the *MandatoryRelease* version, then no longer need to include the where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are 5-tuples of the same form as :data:`sys.version_info`:: - (PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int - PY_MINOR_VERSION, # the 1; an int - PY_MICRO_VERSION, # the 0; an int - PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string - PY_RELEASE_SERIAL # the 3; an int + (PY_MAJOR_VERSION, # The 2 in 2.1.0a3; an int. + PY_MINOR_VERSION, # The 1; an int. + PY_MICRO_VERSION, # The 0; an int. + PY_RELEASE_LEVEL, # One of "alpha", "beta", "candidate" or "final"; string. + PY_RELEASE_SERIAL # The 3; an int. ) The release information for features is captured through *OptionalRelease* and