Skip to content

Commit bddb733

Browse files
committed
Improvements
1 parent b1c4442 commit bddb733

6 files changed

Lines changed: 33 additions & 31 deletions

File tree

‎docs/guides/writing_stubs.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -349,8 +349,8 @@ still recommended to separately define known attributes.
349349
Constants
350350
---------
351351

352-
When the value of a constant is important, mark it as ``Final`` and assign it
353-
to its value.
352+
When the value of a constant is important, mark it as a :term:`bare Final` and
353+
assign it to its value.
354354

355355
Yes::
356356

‎docs/spec/dataclasses.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -526,8 +526,8 @@ This includes, but is not limited to, the following semantics:
526526
* ClassVar attributes are not considered dataclass fields and are
527527
`ignored by dataclass mechanisms <https://docs.python.org/3/library/dataclasses.html#class-variables>`_.
528528

529-
* A dataclass field may be annotated with an :term:`explicitly typed Final`.
530-
For example, ``x: Final[int]``
529+
* A dataclass field may be annotated with an :term:`explicitly typed Final`
530+
:term:`type qualifier`. For example, ``x: Final[int]``
531531
in a dataclass body specifies a dataclass field ``x``, which
532532
will be initialized in the generated ``__init__`` and cannot be assigned to
533533
thereafter. A ``Final`` dataclass field initialized in the class body is not

‎docs/spec/glossary.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,8 @@ This section defines a few terms that may be used elsewhere in the specification
2828
:ref:`type-system-concepts`.
2929

3030
bare ``Final``
31-
A :ref:`Final <uppercase-final>` annotation without an explicit type,
32-
e.g. ``x: Final``.
31+
A :ref:`Final <uppercase-final>` :term:`type qualifier` without an
32+
explicit type, e.g. ``x: Final``.
3333

3434
closed
3535
A :ref:`TypedDict <typeddict>` type is closed if it may not contain any
@@ -64,8 +64,8 @@ This section defines a few terms that may be used elsewhere in the specification
6464
also materializations of ``A``.
6565

6666
explicitly typed ``Final``
67-
A :ref:`Final <uppercase-final>` annotation used as a :term:`type qualifier`,
68-
i.e. with an explicit type: ``x: Final[int]``.
67+
A :ref:`Final <uppercase-final>` :term:`type qualifier` with an explicit
68+
type, e.g. ``x: Final[int]``.
6969

7070
extra items
7171
A :ref:`TypedDict <typeddict>` type with extra items may contain arbitrary

‎docs/spec/literal.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -504,8 +504,8 @@ involving Literal bools. For example, we can combine ``Literal[True]``,
504504
Interactions with Final
505505
"""""""""""""""""""""""
506506

507-
A :term:`bare Final` can be used to declare that some variable or
508-
attribute cannot be reassigned::
507+
A :term:`bare Final` type qualifier can be used to declare that some variable
508+
or attribute cannot be reassigned::
509509

510510
foo: Final = 3
511511
foo = 4 # Error: 'foo' is declared to be Final
@@ -518,8 +518,8 @@ is valid to use in any context that expects a ``Literal[3]``::
518518

519519
expects_three(foo) # Type checks, since 'foo' is Final and equal to 3
520520

521-
The ``Final`` qualifier serves as a shorthand for declaring that a variable
522-
is *effectively Literal*.
521+
A :term:`bare Final` type qualifier serves as a shorthand for declaring that a
522+
variable is *effectively Literal*.
523523

524524
Type checkers are expected to
525525
support this shortcut. Specifically, given a variable or attribute assignment
@@ -530,7 +530,7 @@ any context that expects a ``Literal[value]``.
530530
Type checkers are not obligated to understand any other uses of Final. For
531531
example, whether or not the following program type checks is left unspecified::
532532

533-
# Note: explicitly typed Final qualifiers have unspecified behavior.
533+
# Note: Literal inference is unspecified for explicitly typed Final.
534534
bar1: Final[int] = 3
535535
expects_three(bar1) # May or may not be accepted by type checkers
536536

‎docs/spec/qualifiers.rst‎

Lines changed: 18 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ Syntax
8383

8484
``Final`` may be used in one of two forms:
8585

86-
* As :term:`explicitly typed Final`, using the syntax ``Final[<type>]``.
86+
* As an :term:`explicitly typed Final`, using the syntax ``Final[<type>]``.
8787
Example::
8888

8989
ID: Final[float] = 1
@@ -92,10 +92,12 @@ Syntax
9292

9393
ID: Final[float]
9494

95-
* As :term:`bare Final`, with no type annotation. Example::
95+
* As a :term:`bare Final`, without a type argument. Example::
9696

9797
ID: Final = 1
9898

99+
Bare ``Final`` annotations must have an assigned value.
100+
99101
The typechecker should apply its usual type inference mechanisms to
100102
determine the type of ``ID`` (here, likely, ``int``). Note that unlike for
101103
generic classes this is *not* the same as ``Final[Any]``.
@@ -150,18 +152,9 @@ be initialized in the ``__init__`` method (except in stub files)::
150152
def __init__(self) -> None:
151153
self.x = 1 # Good
152154

153-
Alternatively, ``Final`` attributes can be assigned in and *only* in
154-
``__init__`` methods, so that the final instance attribute is assigned only
155-
once when an instance is created::
156-
157-
class ImmutableAttributes:
158-
def __init__(self) -> None:
159-
self.x: Final = 3
160-
self.y: Final[str] = "knight"
161-
162155
The generated ``__init__`` method of :doc:`dataclasses` qualifies for this
163-
requirement: a ``x: Final[int]`` without right side is permitted in a dataclass
164-
body, because the generated ``__init__`` will initialize ``x``.
156+
requirement: an ``x: Final[int]`` without an initializer is permitted in a
157+
dataclass body, because the generated ``__init__`` will initialize ``x``.
165158

166159
Type checkers should infer a final attribute that is initialized in a class
167160
body as being a class variable, except in the case of :doc:`dataclasses`, where
@@ -171,6 +164,15 @@ necessary to create a final class variable with value ``3``. In
171164
non-dataclasses, combining ``ClassVar`` and ``Final`` is redundant, and type
172165
checkers may choose to warn or error on the redundancy.
173166

167+
``Final`` attributes can also be declared in and *only* in ``__init__``
168+
methods, so that the final instance attribute is assigned only once when an
169+
instance is created::
170+
171+
class ImmutableAttributes:
172+
def __init__(self) -> None:
173+
self.x: Final = 3
174+
self.y: Final[str] = "knight"
175+
174176
``Final`` may only be used in assignments or variable annotations. Using it in
175177
any other position is an error. In particular, ``Final`` can't be used in
176178
annotations for function arguments::
@@ -197,9 +199,9 @@ with ``Final`` to prevent mutating such values::
197199
z: Final = ('a', 'b') # Also works
198200

199201

200-
Type checkers should treat uses of a final name that was initialized
201-
with a literal as if it was replaced by the literal. For example, the
202-
following should be allowed::
202+
Type checkers should treat uses of name declared with a :term:`bare Final`
203+
that was initialized with a literal as if it was replaced by the literal. For
204+
example, the following should be allowed::
203205

204206
from typing import NamedTuple, Final
205207

‎docs/spec/typeddict.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -732,8 +732,8 @@ certain items. For example, ``d['x'] = 1`` should generate a type check error
732732
if ``'x'`` is not a valid key for ``d`` (which is assumed to be a TypedDict
733733
type), unless ``d`` has mutable :term:`extra items` of a compatible type.
734734

735-
Type checkers should allow :ref:`final names <uppercase-final>` with
736-
string values to be used instead of string literals in operations on
735+
Type checkers should allow names declared with a :term:`bare Final` and a
736+
string value to be used instead of string literals in operations on
737737
TypedDict objects. For example, this is valid::
738738

739739
YEAR: Final = 'year'

0 commit comments

Comments
 (0)