Add ability to use Final in a field type annotation

[uriyyo]

Add ability to use Final in a field type annotation

Implementation is based on a PEP 591:

Type checkers should infer a final attribute that is initialized in a class body as being a class variable.

A final attribute declared in a class body without an initializer must be initialized in the init method

So in this case field name will be treated as a ClassVar:

from typing import Final
from pydantic import BaseModel

class Model(BaseModel):
    name: Final[str] = 'Yurii'

assert 'name' in Model.__class_vars__
assert 'name' not in Model.__fields__

But in a case when a default value is not present than field will be treated as an init-only required field:

from typing import Final
from pydantic import BaseModel

class Model(BaseModel):
    name: Final[str]

assert 'name' not in Model.__class_vars__
assert 'name' in Model.__fields__

_ = Model()  # will fail because name is missed

obj = Model(name='Yurri')
obj.name = 'New Value'  # will fail because final field has been already inited

Related issue number

#2766

Checklist

• Unit tests for the changes exist
• Tests pass on CI and coverage remains at 100%
• Documentation reflects the changes where applicable
• changes/<pull request or issue id>-<github username>.md file added describing change
  (see changes/README.md for details)
• My PR is ready to review, please add a comment including the phrase "please review" to assign reviewers

[uriyyo]

@samuelcolvin @PrettyWood Could you please review this PR?

I want to hear your opinion regarding this feature.

[nuno-andre]

IMHO, this implementation adds an unexpected behavior from the pydanticish perspective (a default value turns what would otherwise be an instance field into a class var) without a clear benefit.

from pydantic import BaseModel

class Model(BaseModel):
    var: Final[str] = Field(max_length=3)

I presume that in a case like this no one would expect to have an immutable class var of the type FieldInfo.

The aim of a final name is not to be reassigned after initialization, but there's no such initialization in a Model declaration. As with dataclass, it's needed to annotate the attribute as a ClassVar to be treated as such and excluded from fields/__fields__.

from pydantic import BaseModel

class A:
    var = 1

class B(BaseModel):
    var = 1

>>> A.var
1
>>> B.var
...
AttributeError: type object 'B' has no attribute 'var'

I think Final could be more useful as an allow_mutation = False synonym that would also prevent the attribute redefinition in subclasses. The problem here would be that Final and ClassVar should not be together...

The behavior of Final for cases such as dataclass or TypedDict is not defined in the PEP. And, in fact, mypy doesn't seem to know how to deal with it.

from dataclasses import dataclass
from typing import Final, TypedDict

@dataclass
class A:
    var: Final[str]
#> error: Final name must be initialized with a value

class B(TypedDict):
    var: Final[str]
#> error: Final can be only used as an outermost qualifier in a variable annotation

# this also raises a TypeError
#> TypeError: typing.Final[str] is not valid as type argument

But mypy's Var AST node has a final_set_in_init attribute that seems a fine approach for Pydantic to mimic in a case like this.

[PrettyWood]

Honestly I'm against it. I feel like it's really confusing and the different behaviour with or without a default value goes against pydantic one (required vs optional more or less).
I feel like people should stick with plain ClassVar or directly the type, which is explicit

Edit: I like the "synonym for immutable" (to me this is what seems the most reasonable) hence setting allow_mutation = False behind the scenes but what about class vars if it goes against the PEP?

[uriyyo]

@nuno-andre @PrettyWood Thanks for your comments.

@nuno-andre Thanks for pointing out case when the field declared as a Field call. I have updated the implementation and now it will be resolved correctly.

Regarding the mypy. Currently, pydantic mypy plugin handles a lot of cases and for instance, it generates __init__ method with the correct type decl for a model. From my perspective, we can update plugin to handle special cases for Final.

@PrettyWood Currently pydantic has a lot of ways to decl fields:

class Model(BaseModel):
    a: int  # required
    b: int = 10  # optional
    c: int = Field()  # required
    d: int = Field(default=10)  # optional
    e: int = Field(default_factory=lambda: 10)  # optional

To simplify things we can always use Final type annotation as for instance fields.

class Model(BaseModel):
    a: Final[int] = 10 # instance field with default value 10 same as Field(default=10)

Another feature of this PR is that we can have init-only fields.
So we can disable mutation for a specific set of fields.

class Model(BaseModel):
    a: Final[int]
    b: int


obj = Model(a=10, b=20)
obj.a = 100  # will fail because final field can't be changed outside of init method
obj.b = 100  # totally okay

As far as implementation follows PEP 591 it's pretty easy to predict the behavior of this feature.

[PrettyWood]

@uriyyo My point was just about class var / field. By setting a default value, we change a field in a class var, which is what the PEP says but feels anti-pydantic to me.
The use of a: Final[int] to make a value immutable (since it's only settable once in the init) feels good.
Discard: It's just my opinion ;)

[uriyyo]

@PrettyWood Thanks for your opinion, it's really important for me🙂

I totally agree with you that we can use Final to make a value immutable and it will be more explicit rather than have a behavior when Final makes field as a class var.

[PrettyWood]

I think we should get more feedback on this before adding anything or reviewing.
@samuelcolvin what's your opinion on the rationale? others?

[uriyyo]

@PrettyWood @samuelcolvin Any chance to review this one? It would be great to hear your opinion. I would like to use this feature in my projects)

[samuelcolvin]

otherwise LGTM.

[samuelcolvin]

This can be moved into the module scope of fields.py.

[samuelcolvin]

pydantic/pydantic-core#219

[samuelcolvin]

can you add a docstring explaining what this is doing.

[samuelcolvin]

we we add a check somewhere else that final is normally false.

[samuelcolvin]

please update.

[samuelcolvin]

you'll also need to rebase/merge master to get tests passing.

[uriyyo]

please review

[samuelcolvin]

thanks so much.

[bzoracler]

A PR has just been opened to change the Python typing specifications that will propagate to any use of dataclass-likes in the Python ecosystem, such as with @dataclass_transform.

python/typing#1669

The above typing PR specifies behaviour which is incompatible with the Final = <value> (in Pydantic , treated as a ClassVar in BaseModel subclasses based on a consistent reading of PEP 591) made in this Pydantic PR. The relevant behaviour still exists in Pydantic here:

pydantic/pydantic/_internal/_fields.py

Lines 169 to 171 in 8128821

	if _is_finalvar_with_default_val(ann_type, getattr(cls, ann_name, PydanticUndefined)):
	class_vars.add(ann_name)
	continue

The typing PR will mean that Final = <value> become instance fields with a default value of <value> instead, in dataclass-like class bodies.

---

As @dataclass_transform was created with Pydantic in mind, I think it'd be valuable if anyone would like to weigh in with explicit support or rejection of this change to the typing spec.