An Implementation of Annotated Types

When does this value checking happen?

I'm glad you asked.

Use of annotated types is not part of the Python run-time. Annotated type arguments are essentially ignored. The origin type is used by tools like mypy.

Any further use of annotations is a thing your application or tool-chain will need to do.

An application can see the annotations for an object using the __annotations__ special attribute number, or use the typing.get_type_hints() function.

>>> from typing import Annotated, get_type_hints
>>> class MustBePrime:
...     pass
...

>>> class SomeApp:
...     x: Annotated[int, MustBePrime()]
...

>>> get_type_hints(SomeApp)
{'x': <class 'int'>}
>>> get_type_hints(SomeApp, include_extras=True)
{'x': typing.Annotated[int, <__main__.MustBePrime object at 0x7fde259a7be0>]}
>>> get_type_hints(SomeApp, include_extras=True)['x']
typing.Annotated[int, <__main__.MustBePrime object at 0x7fde259a7be0>]

We can see the annotated type hint for x.

This means, our application is free to "apply" the annotation in some way.

"Whoa! That's vague," you say. "There are no specific rules for annotated types?"

I agree.

The details are up to your app. Seriously. Define them in a way that makes sense.

Maybe you want your app looks like this:

>>> class SomeApp:
....    x: Annotated[int, MustBePrime()]
...     def __init__(self, arg_value: int) -> None:
...         self.x = arg_value
...

And you've got a use case in mind...

>>> sa = SomeApp(42)
Traceback (most recent call last):
   ...
ValueError: value 42 is not prime

The idea is that this specific app has an associated collection of annotations that are used during __init__() processing to further validate the supplied values.

The code to this is clearly part of SomeApp -- maybe a metaclass, maybe a superclass -- but clearly part of the app.

And the app will use the annotation as a kind of "plug-in" or "extension" or Strategy design pattern to do some additional processing at some point.

Our use case was part of __init__() processing. What does this look like?

An example app

We'll avoid metaclasses, and pretend that Annotated types are checked by an explict call to a method of the class. Let's say a superclass, named RuleCheck has a method that must be called at the end of __init__() to check compliance with annotations.

class SomeApp(RuleCheck):
    x: Annotated[int, MustBePrime()]

    def __init__(self, arg_value: int) -> None:
        self.x = arg_value
        self.check()

The idea here is that the class-level hints are carefully defined.

The __init__() merely slaps any old value in there.

And the self.check() then assures that all hints are actually true for the supplied values.

This means it will "apply" the annotation to the given value. In this case, it will either allow the value silently or raise an exception if there's a problem.

Here's the RuleCheck class.

from typing import Annotated, get_type_hints, get_args

class RuleCheck:
    def check(self) -> None:
        vars = get_type_hints(self.__class__, include_extras=True)
        for name in vars:
            match vars[name]:
                case Annotated:
                   base, *rules = get_args(vars[name])
                   for rule in rules:
                       rule(getattr(self, name))

Each annotated variable has the arguments to the annotation retrieved with typing.get_args(). Each of these annotations must be a callable object of some kind that can be applied to the attribute's value.

We leave the implementation of MustBePrime as an exercise for the reader.

Building a type definition

Maybe we want this.

PosInt: TypeAlias = Annotated[int, MustBePositive()]
PrimePosInt: TypeAlias = Annotated[PosInt, MustBePrime()]

We've built a complicated type on top of another complicated type.

This permits us to -- for example -- improve the performance of MustBePositive with an attendant speedup of other, related objects.

File Parsing

This is an edge case. But. It applies to the vast number of files processed by COBOL programs.

x: Annotated[str, Start(0), Length(5)]
y: Annotated[str, Start(5), Length(10)]
z: Annotated[Decimal, Start(15), Length(10), Scale(2)]

We've provided the metadata for positions of the source data in a text document. A file with a line like "ABCDEZYXWVUTSRQ0000001299" could be parsed by a class that leveraged the annotations to pluck values out of the source string. It could apply conversion from mainframe encodings ("EBCDIC") and do decimal conversion.