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.

I've restored this section for now, although it's really vague and ambiguous. That makes it sound as if Final works like C's #define. Maybe the best idea would be to have a dedicated "Interaction with NamedTuple" section, since this seems to be a special case.

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-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.

Update conformance tests accordingly Restore the `NamedTuple` section

srittau · 2026-09-01T10:53:55Z

I've now completely rewritten the inference rules section (except the part finals in class bodies). I think I captured the intent of the various bits and pieces previously scattered around the specs. I'm using concrete language better suited for a spec than the previous "PEP" language that was more explanatory.

Personally, I'd prefer the "explicit type" section to just read "Type checkers should use an explicit type if one is provided.", but that would be a direct contradiction to the previous example that type checkers may accept:

    bar1: Final[int] = 3
    expects_three(bar1)  # May or may not be accepted by type checkers

I've gone with the old vague language for now, but I think there is very much room for improvement here in the future.

I've also restored the NamedTuple section in a dedicated "Interaction with NamedTuple" section and reworded it to apply to NamedTuples only for now, since the previous language was extremely vague. Please let me know if there are cases missing that should be added.

Finally, I've reworked the conformance tests to follow the reworked section. I've introduced a new way to mark result groups as requiring at least one success (as pyrefly accepts both assert_type(X, float) and assert_type(X, float | int). I will extract that into a separate PR. The reworked conformance tests reveal a few instances of type checkers being more liberal in what type of literals they support (especially Literal[3.14], but pycroscope also accepts Literal[range(0, 3)]. I'm not sure what the best approach here is.

davidhalter · 2026-09-01T12:14:27Z

+
+    bare2: Final = 1 + 2  # may infer bare2 as Final[Literal[3]] or Final[int]
+
+* In all other cases, type checkers should use standard inference rules.


This is technically not correct, because immutable containers are just fine inferring literals, e.g.

x: Final = (1,)

should IMO infer tuple[Literal[1]]. It's at least what Mypy and Pyright do. I haven't checked the other type checkers.

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

Comment thread docs/spec/qualifiers.rst Outdated

Comment thread conformance/tests/qualifiers_final_annotation.py Outdated

Rework Inference Rules section

eba639e

Update conformance tests accordingly Restore the `NamedTuple` section

Fix key names

7e6e1c3

srittau mentioned this pull request Sep 1, 2026

New conformance tag '# E[tag!]' to require at least one success #2354

Open

Remove unnecessary function

eb3b496

davidhalter 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 16 commits into
python:mainfrom
srittau:final-literal

srittau commented Aug 31, 2026

srittau Aug 31, 2026

srittau Aug 31, 2026

carljm Aug 31, 2026

srittau Sep 1, 2026

srittau Aug 31, 2026 •

edited

Loading

srittau commented Aug 31, 2026

srittau commented Aug 31, 2026

carljm left a comment

carljm Aug 31, 2026

Uh oh!

carljm Aug 31, 2026

Uh oh!

Uh oh!

Uh oh!

srittau commented Sep 1, 2026

davidhalter Sep 1, 2026

Labels

4 participants


		bare2: Final = 1 + 2 # may infer bare2 as Final[Literal[3]] or Final[int]

		* In all other cases, type checkers should use standard inference rules.

Uh oh!

Conversation

srittau commented Aug 31, 2026

srittau Aug 31, 2026

Choose a reason for hiding this comment

srittau Aug 31, 2026

Choose a reason for hiding this comment

carljm Aug 31, 2026

Choose a reason for hiding this comment

srittau Sep 1, 2026

Choose a reason for hiding this comment

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

srittau commented Aug 31, 2026

srittau commented Aug 31, 2026

carljm left a comment

Choose a reason for hiding this comment

carljm Aug 31, 2026

Choose a reason for hiding this comment

Uh oh!

carljm Aug 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

srittau commented Sep 1, 2026

davidhalter Sep 1, 2026

Choose a reason for hiding this comment

Labels

4 participants

srittau Aug 31, 2026 •

edited

Loading