Support typing.Final annotations

[jcrist]

This adds support for typing.Final annotations. Final can be used to wrap an existing field annotation, marking it as a field that can't be modified once it's initialized. This has the same semantics as frozen=True, but only for a single field, and not enforced at runtime.

The Frozen annotation may be used to wrap field annotations on any object-like type we support (msgspec.Struct, attrs, or dataclasses).

import msgspec

class Test(msgspec.Struct):
    x: Final[int] = 0

t = Test(1)
t.x = 2  # mypy and pyright will complain here

---

Note that currently mypy has a bug (python/mypy#5608) where Final annotations in dataclass-like things require a default value (the bug seems to be early on in mypy's type processing pipeline). This is to enforce some vague wording in the Final PEP that indicates it should be an error to not have a value when defining a Final annotation on a class where that value isn't set in the __init__. Since dataclass-like-types don't have a visible __init__, this error is triggered. However! If you add # type: ignore on that line then the rest works fine, including all the normal dataclass type annotation validation.

class Test(msgspec.Struct):
    # Without the type: ignore below, mypy will complain about Final needing an initialized value.
    # pyright works fine either way.
    x: Final[int]  # type: ignore

t = Test(1)  # mypy still knows the dataclass-like-thing's signature though, so no harm to the type: ignore
t2 = Test("bad")  # this means that mypy will still error here

---

Adding this since it was asked for in cattrs, and it's nice to have compatibility across these kinds of libraries.

I'm also happy to see that the refactor needed to our type parsing routine also leads to a measurable speedup when processing type annotations into our own internal format. Nice when a new feature also leads to faster code.

[jcrist]

A quick benchmarks trying to measure just the type annotation parsing overhead. For most usage patterns the type annotation parsing happens only once and is cached for subsequent usage, so I wouldn't expect this perf increase to matter to most users. Still, speeding this up can decrease startup times.

Main Branch

In [1]: import msgspec

In [2]: typ = dict[str, list[int]]

In [3]: msg = b'{"x":[1]}'

In [4]: %timeit msgspec.json.decode(msg, type=typ)
1.78 µs ± 18.2 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)

This PR

In [1]: import msgspec

In [2]: typ = dict[str, list[int]]

In [3]: msg = b'{"x":[1]}'

In [4]: %timeit msgspec.json.decode(msg, type=typ)
653 ns ± 5.72 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)

In both cases the call overhead without parsing type annotations is:

In [5]: %timeit msgspec.json.decode(msg)
128 ns ± 0.343 ns per loop (mean ± std. dev. of 7 runs, 10,000,000 loops each)

Given this, this is roughly a 3x speedup (1650 ns down to 525 ns) in type annotation parsing.