defining a `typing.Protocol` with `__annotate__` method raises `TypeError` since Python 3.14

[jorenham]

Bug report

Bug description:

from annotationlib import Format
from collections.abc import Mapping
from typing import Any, Protocol


class CanAnnotate(Protocol):
    def __annotate__(self, format: Format, /) -> Mapping[str, Any]: ...

On Python 3.14.3 and 3.15.0a7 this results in a TypeError:

Traceback (most recent call last):
  File "/home/joren/.local/share/uv/python/cpython-3.14.3-linux-x86_64-gnu/lib/python3.14/typing.py", line 1853, in _get_protocol_attrs
    annotations = base.__annotations__
                  ^^^^^^^^^^^^^^^^^^^^
TypeError: CanAnnotate.__annotate__() missing 1 required positional argument: 'format'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/joren/Workspace/optype/repro.py", line 6, in <module>
    class CanAnnotate(Protocol):
        def __annotate__(self, format: Format, /) -> Mapping[str, Any]: ...
  File "/home/joren/.local/share/uv/python/cpython-3.14.3-linux-x86_64-gnu/lib/python3.14/typing.py", line 1999, in __init__
    cls.__protocol_attrs__ = _get_protocol_attrs(cls)
                             ~~~~~~~~~~~~~~~~~~~^^^^^
  File "/home/joren/.local/share/uv/python/cpython-3.14.3-linux-x86_64-gnu/lib/python3.14/typing.py", line 1856, in _get_protocol_attrs
    annotations = _lazy_annotationlib.get_annotations(
        base, format=_lazy_annotationlib.Format.FORWARDREF
    )
  File "/home/joren/.local/share/uv/python/cpython-3.14.3-linux-x86_64-gnu/lib/python3.14/annotationlib.py", line 982, in get_annotations
    ann = _get_and_call_annotate(obj, format)
  File "/home/joren/.local/share/uv/python/cpython-3.14.3-linux-x86_64-gnu/lib/python3.14/annotationlib.py", line 1121, in _get_and_call_annotate
    ann = call_annotate_function(annotate, format, owner=obj)
  File "/home/joren/.local/share/uv/python/cpython-3.14.3-linux-x86_64-gnu/lib/python3.14/annotationlib.py", line 720, in call_annotate_function
    return annotate(format)
TypeError: CanAnnotate.__annotate__() missing 1 required positional argument: 'format'

On Python 3.13 (when you replace the annotationlib.Format with Any), there is no error.

CPython versions tested on:

3.14

Operating systems tested on:

Linux

[brianschubert]

cc @JelleZijlstra

[JelleZijlstra]

__annotate__ is now special to the language, so it's not surprising that a custom definition may cause errors. We can try to get something to work here, but I'm not sure we can make any guarantees.

[DavidCEllis]

This isn't really something that 'worked' before that has been broken as __annotate__ had no specific meaning to Python before 3.14.

If you're going for an equivalent, the problem is that CanAnnotate puts a value in for __annotate__ that overrides the annotations Protocol is trying to get. This breaks just as surely as putting in an invalid value for __annotations__ in earlier Python if something tries to use it:

class CanAnnotate:
    __annotations__: dict[str, object] = ...  # TypeError in 3.13

---

I'm not sure what cases CanAnnotate is intended for but it may also be worth noting that __annotate__ does not usually behave like a bound method. It's not normally even accessible from instances of user classes.

Is annotating __annotate__ as a callable (or callable protocol) not sufficient?

[jorenham]

This isn't really something that 'worked' before that has been broken as __annotate__ had no specific meaning to Python before 3.14.

All I'm saying is that this did not raise an error. I'm not making any claims about how utility.

This breaks just as surely as putting in an invalid value for __annotations__ in earlier Python if something tries to use it:

class CanAnnotate:
    __annotations__: dict[str, object] = ...  # TypeError in 3.13

It seems to work fine though?

>>> from typing import Protocol
>>> class HasAnnotations(Protocol):
...     __annotations__: dict[str, Any]
...     
>>> HasAnnotations
<class '__main__.HasAnnotations'>

In optype there even is a variant of this protocol, which has, and still is, not triggering any errors on import: https://github.com/jorenham/optype/blob/8af400a2fe652eacd4563cc0d3a7c3c8e67e66e1/optype/_core/_has.py#L170-L172

I'm not sure what cases CanAnnotate is intended for but it may also be worth noting that __annotate__ does not usually behave like a bound method. It's not normally even accessible from instances of user classes.

Ah now that you mention it, in the docs it is described as object.__annotate__(format), so there's no self there. And luck would have it that if I instead of a method specify __annotate__ as a @property returning Callable[[Format], Mapping[str, Any]], then there is no error.
As far as I'm aware, this makes no difference for structural typing purposes, so I can live with that.

But even so, the TypeError raised in the orignal exampple doesn't look right to me. At the very least, the error message isn't very helpful in this context.

And if there are in fact certain dunder methods like __annotate__ that are not allowed in Protocol, then maybe that should be documented?

[DavidCEllis]

You missed the load bearing ellipsis in the example.

The purpose was to demonstrate the issue is that it was setting a value for __annotate__ that caused the issue in the same way that setting a value for __annotations__ wouldn't work in earlier Python.

[jorenham]

You missed the load bearing ellipsis in the example.

The purpose was to demonstrate the issue is that it was setting a value for __annotate__ that caused the issue in the same way that setting a value for __annotations__ wouldn't work in earlier Python.

I saw it, and I understand it. But it's not a Protocol, and at runtime the ... assignment does not mean the same thing as it does in .pyi stubs, so I'm not surprised that this causes issues.
Also, it's not a Protocol, so I don't see the purpose either. I you'd make it a protocol (like I did), then you wouldn't need the ..., so then there's no issue.

[DavidCEllis]

It's not that __annotate__ is specifically 'not allowed in Protocol' it's that by defining __annotate__ in the class body you've broken the class annotations. Protocol can't get the annotations because you've replaced them with your function.

The closest equivalent in older Python is putting something invalid as a value in __annotations__.

Ignoring any of the other Protocol features, the issue you have is this:

class Example:
    def __annotate__(self, format): ...

Example.__annotations__

Traceback (most recent call last):
  File "<python-input-0>", line 4, in <module>
    Example.__annotations__
TypeError: Example.__annotate__() missing 1 required positional argument: 'format'

---

Does something like this make sense?

from annotationlib import Format
from collections.abc import Mapping
from typing import Any, Protocol

class AnnotateCallable(Protocol):
    def __call__(self, format: Format, /) -> Mapping[str, Any]: ...

class CanAnnotate(Protocol):
    __annotate__: AnnotateCallable

[jorenham]

Does something like this make sense?

I was actually thinking of going with something this:

class CanAnnotate(Protocol):
    @property
    def __annotate__(self, /) -> Callable[[Format], Mapping[str, Any]]: ...

The @property ensures that it doesn't enforce __annotate__ to be writable, and the Callable is equivalent to your AnnotateCallable.

[DavidCEllis]

I'll note that Protocol could maybe special case and do some magic to avoid this, but I'm not sure it's a good idea.

Defining __annotate__ inside a class body has some surprising side effects and doesn't behave like assigning it after the class has been constructed. I'd almost propose making this an error but it would probably break other things.

class Example:
    @staticmethod
    def __annotate__(format): return {'a': "Original Annotations"}

def new_annotate(format): return {'a': "New Annotations"}

print(Example.__annotate__(1))

# Replace and try again
Example.__annotate__ = new_annotate
print(Example.__annotate__(1))

{'a': 'Original Annotations'}
{'a': 'Original Annotations'}

---

Yes the property technically 'works', it has still broken the annotations though. It just seems to hit a special case that returns an empty dictionary for __annotations__ which matches your protocol having no annotations. If there were other annotations they would be missing.

You can't get STRING annotations for example.

from annotationlib import Format, get_annotations
from collections.abc import Mapping
from typing import Any, Protocol

class CanAnnotate(Protocol):
    @property
    def __annotate__(self, /) -> Callable[[Format], Mapping[str, Any]]: ...

get_annotations(CanAnnotate, format=Format.STRING)  # TypeError: 'property' object is not callable