Unify and fix`Literal`/`Final` interaction by srittau · Pull Request #2353 · python/typing

srittau · 2026-08-31T17:02:02Z

Add an "Inference Rules" subsection to the Final section.
Move the inference rules for class vars there.
Remove contradictory paragraph about literal handling from Final section.
Merge the "Interactions with Final" section from literals into the new "Inference Rules" section, add a link, and trim slightly.

I've decided to move the interaction section to the "qualifiers" chapters,
since Literal seems much closer linked to Final than vice versa.

Closes: #2351

- Add an "Inference Rules" subsection to the `Final` section. - Move the inference rules for class vars there. - Remove contradictory paragraph about literal handling from `Final` section. - Merge the "Interactions with Final" section from literals into the new "Inference Rules" section, add a link, and trim slightly.

srittau · 2026-08-31T17:03:08Z

-Type checkers should infer a final attribute that is initialized in a class
-body as being a class variable, except in the case of :doc:`dataclasses`, where
-``x: Final[int] = 3`` creates a dataclass field and instance-level final
-attribute ``x`` with default value ``3``; ``x: ClassVar[Final[int]] = 3`` is
-necessary to create a final class variable with value ``3``. In
-non-dataclasses, combining ``ClassVar`` and ``Final`` is redundant, and type
-checkers may choose to warn or error on the redundancy.


This got moved to the "Inference Rules" section.

srittau · 2026-08-31T17:03:25Z

-Type checkers should treat uses of a final name that was initialized
-with a literal as if it was replaced by the literal. For example, the
-following should be allowed::
-
-   from typing import NamedTuple, Final
-
-   X: Final = "x"
-   Y: Final = "y"
-   N = NamedTuple("N", [(X, int), (Y, int)])


This got removed completely as it's redundant.

I don't think this is redundant or should be removed. The position of X and Y in this NamedTuple declaration is not an ordinary "call expects a literal type" position; it's syntax-sensitive type-factory metadata that is special-cased by type checkers; they must be able to understand as describing a specific field name. I don't think the rules below are sufficient to clarify that this example must work.

Also the conformance tests still quote this deleted paragraph.

srittau · 2026-08-31T17:04:22Z

+In the example below, we know that ``foo`` will always be equal to
+exactly ``3``. A type checker can use this information to deduce that ``foo``
+is valid to use in any context that expects a ``Literal[3]``::
+
+    def expects_three(x: Literal[3]) -> None: ...
+
+    foo: Final = 3
+    expects_three(foo)  # Type checks, since 'foo' is Final and equal to 3


The introductory part was reshuffled a bit from the original section to be a better fit here. The rest is identical.

srittau · 2026-08-31T17:52:20Z

I just noticed that the introductory sentence about "normal inference" is actually important. I will change the PR when I get home.

…teral

srittau · 2026-08-31T18:48:27Z

The spec used to say:

The typechecker should apply its usual type inference mechanisms to determine the type of ID (here, likely, int)"

before I replaced that sentence with a link to the new inference rules section. The problem is that this contradicts the explicit guidance in the section I copied over from the literals spec:

Type checkers are not obligated to understand any other uses of Final. For
example, whether or not the following program type checks is left unspecified: [...]

My suggestion: We leave this original sentence out for now, reverting back to "left unspecified" for now. But I did plan to open a discuss thread anyway to define a few more supported cases, like X: Final = cls(), Y: Final = 3.2, and remove the ambiguity surrounding Z: Final[int] = 3.

carljm

I think combining these sections makes sense. Left some inline comments.

I think this is a clarification, not a substantive spec change, so I don't know that we need the full process including DPO post here. But it's a hefty enough rewording / rearrangement that I do think we should try to get at least most of the typing council to approve it.

carljm · 2026-08-31T22:50:07Z


-  The typechecker should apply its usual type inference mechanisms to
-  determine the type of ``ID`` (here, likely, ``int``). Note that unlike for
+  The typechecker should apply the inference mechanisms


The rules below don't attempt to cover every possible right-hand-side of an assignment to a Final annotated attribute; they are specific to valid literal values. So I think we still need the "typechecker should apply its usual type inference mechanisms" default fallback language here, with the literal rules below as additional constraints. I don't think we can just refer to the rules below as though they fully specify inference of all Final assignments.

Currently this seems to drop any requirement for type checkers to support e.g. x: Final = C() or x: Final = ['a', 'b'], because those right-hand-sides are not valid Literal values.

carljm · 2026-08-31T22:50:07Z

+expects_one(ID4)  # E?: May or may not be accepted by type checkers
+
+ID5: Final = range(1)
+assert_type(ID5, range)  # E?: May or may not be inferred by type checkers


All three of these tests are kind of useless as conformance tests, but the first two I don't mind, since I think they still provide useful clarification that this behavior is not specified either way. But this third one is a really strange test, since we assert that range(1) may or may not be inferred as range -- which is not even a literal type anyway. So it really feels like this test is saying nothing at all. I would just remove it.

carljm · 2026-08-31T23:52:10Z

-Type checkers should treat uses of a final name that was initialized
-with a literal as if it was replaced by the literal. For example, the
-following should be allowed::
-
-   from typing import NamedTuple, Final
-
-   X: Final = "x"
-   Y: Final = "y"
-   N = NamedTuple("N", [(X, int), (Y, int)])


I don't think this is redundant or should be removed. The position of X and Y in this NamedTuple declaration is not an ordinary "call expects a literal type" position; it's syntax-sensitive type-factory metadata that is special-cased by type checkers; they must be able to understand as describing a specific field name. I don't think the rules below are sufficient to clarify that this example must work.

Also the conformance tests still quote this deleted paragraph.

carljm · 2026-08-31T23:56:01Z

+``Literal[...]``, type checkers should understand that ``var`` may be used in
+any context that expects a ``Literal[value]``.
+
+Type checkers are not obligated to understand any other uses of Final. For


I find this sentence confusing, so if we're clarifying here, I think we should clarify it. Obviously type checkers are generally expected to understand any use of Final as requiring finality (i.e. not accepting later reassignments). So why would we say they are "not obligated to understand any other uses of Final"? It seems like what we really mean is more like this:

Suggested change

Type checkers are not obligated to understand any other uses of Final. For

Type checkers are not obligated to understand any other uses of Final as implying a Literal type. For

JelleZijlstra · 2026-09-01T02:38:51Z

+Type checkers are expected to
+support this shortcut. Specifically, given a variable or attribute assignment
+of the form ``var: Final = value`` where ``value`` is a valid parameter for
+``Literal[...]``, type checkers should understand that ``var`` may be used in


This wording is a bit vague. Should we just say that type checkers must infer Literal[...]?

JelleZijlstra · 2026-09-01T02:39:40Z

+
+ID1: Final = 1
+assert_type(ID1, Literal[1])
+expects_one(ID1)


This seems redundant with the assert_type.

srittau added 6 commits August 31, 2026 17:08

Add tests for Final/Literal interaction

d52de49

Fix type assertions

4276314

Reshuffle, fix, comment

b214de4

Finagle tests more

c61cb1c

Update results

d42d2fd

srittau added the topic: typing spec For improving the typing spec label Aug 31, 2026

srittau commented Aug 31, 2026

View reviewed changes

srittau added 3 commits August 31, 2026 19:05

Update a link

e8ec2bf

One case is optional per the spec, add another case

5b3a1bb

Update results

ae58134

carljm mentioned this pull request Aug 31, 2026

Add tests for Final/Literal interaction #2352

Closed

srittau added 3 commits August 31, 2026 20:30

Merge remote-tracking branch 'origin/conformance-final' into final-li…

f56623b

…teral

Update spec link

0872a87

Move tests from literals_interactions to qualifiers

9ae5733

Re-run conformance tests

d764ec3

carljm reviewed Sep 1, 2026

View reviewed changes

JelleZijlstra reviewed Sep 1, 2026

View reviewed changes

Navigation Menu

Uh oh!

Unify and fix`Literal`/`Final` interaction - #2353

Unify and fix`Literal`/`Final` interaction#2353
srittau wants to merge 13 commits into
python:mainfrom
srittau:final-literal

srittau commented Aug 31, 2026

Uh oh!

srittau Aug 31, 2026

Uh oh!

srittau Aug 31, 2026

Uh oh!

carljm Aug 31, 2026

Uh oh!

srittau Aug 31, 2026 •

edited

Loading

Uh oh!

srittau commented Aug 31, 2026

Uh oh!

srittau commented Aug 31, 2026

Uh oh!

carljm left a comment

Uh oh!

carljm Aug 31, 2026

Uh oh!

carljm Aug 31, 2026

Uh oh!

carljm Aug 31, 2026

Uh oh!

carljm Aug 31, 2026

Uh oh!

JelleZijlstra Sep 1, 2026

Uh oh!

JelleZijlstra Sep 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	Type checkers are not obligated to understand any other uses of Final. For
	Type checkers are not obligated to understand any other uses of Final as implying a Literal type. For

Uh oh!

Conversation

srittau commented Aug 31, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

srittau Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

srittau commented Aug 31, 2026

Uh oh!

srittau commented Aug 31, 2026

Uh oh!

carljm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

srittau Aug 31, 2026 •

edited

Loading