| 1 |
.. _annotations-howto: |
| 2 |
|
| 3 |
************************** |
| 4 |
Annotations Best Practices |
| 5 |
************************** |
| 6 |
|
| 7 |
:author: Larry Hastings |
| 8 |
|
| 9 |
.. topic:: Abstract |
| 10 |
|
| 11 |
This document is designed to encapsulate the best practices |
| 12 |
for working with annotations dicts. If you write Python code |
| 13 |
that examines ``__annotations__`` on Python objects, we |
| 14 |
encourage you to follow the guidelines described below. |
| 15 |
|
| 16 |
The document is organized into four sections: |
| 17 |
best practices for accessing the annotations of an object |
| 18 |
in Python versions 3.10 and newer, |
| 19 |
best practices for accessing the annotations of an object |
| 20 |
in Python versions 3.9 and older, |
| 21 |
other best practices |
| 22 |
for ``__annotations__`` that apply to any Python version, |
| 23 |
and |
| 24 |
quirks of ``__annotations__``. |
| 25 |
|
| 26 |
Note that this document is specifically about working with |
| 27 |
``__annotations__``, not uses *for* annotations. |
| 28 |
If you're looking for information on how to use "type hints" |
| 29 |
in your code, please see the :mod:`typing` module. |
| 30 |
|
| 31 |
|
| 32 |
Accessing The Annotations Dict Of An Object In Python 3.10 And Newer |
| 33 |
==================================================================== |
| 34 |
|
| 35 |
Python 3.10 adds a new function to the standard library: |
| 36 |
:func:`inspect.get_annotations`. In Python versions 3.10 |
| 37 |
through 3.13, calling this function is the best practice for |
| 38 |
accessing the annotations dict of any object that supports |
| 39 |
annotations. This function can also "un-stringize" |
| 40 |
stringized annotations for you. |
| 41 |
|
| 42 |
In Python 3.14, there is a new :mod:`annotationlib` module |
| 43 |
with functionality for working with annotations. This |
| 44 |
includes a :func:`annotationlib.get_annotations` function, |
| 45 |
which supersedes :func:`inspect.get_annotations`. |
| 46 |
|
| 47 |
If for some reason :func:`inspect.get_annotations` isn't |
| 48 |
viable for your use case, you may access the |
| 49 |
``__annotations__`` data member manually. Best practice |
| 50 |
for this changed in Python 3.10 as well: as of Python 3.10, |
| 51 |
``o.__annotations__`` is guaranteed to *always* work |
| 52 |
on Python functions, classes, and modules. If you're |
| 53 |
certain the object you're examining is one of these three |
| 54 |
*specific* objects, you may simply use ``o.__annotations__`` |
| 55 |
to get at the object's annotations dict. |
| 56 |
|
| 57 |
However, other types of callables--for example, |
| 58 |
callables created by :func:`functools.partial`--may |
| 59 |
not have an ``__annotations__`` attribute defined. When |
| 60 |
accessing the ``__annotations__`` of a possibly unknown |
| 61 |
object, best practice in Python versions 3.10 and |
| 62 |
newer is to call :func:`getattr` with three arguments, |
| 63 |
for example ``getattr(o, '__annotations__', None)``. |
| 64 |
|
| 65 |
Before Python 3.10, accessing ``__annotations__`` on a class that |
| 66 |
defines no annotations but that has a parent class with |
| 67 |
annotations would return the parent's ``__annotations__``. |
| 68 |
In Python 3.10 and newer, the child class's annotations |
| 69 |
will be an empty dict instead. |
| 70 |
|
| 71 |
|
| 72 |
Accessing The Annotations Dict Of An Object In Python 3.9 And Older |
| 73 |
=================================================================== |
| 74 |
|
| 75 |
In Python 3.9 and older, accessing the annotations dict |
| 76 |
of an object is much more complicated than in newer versions. |
| 77 |
The problem is a design flaw in these older versions of Python, |
| 78 |
specifically to do with class annotations. |
| 79 |
|
| 80 |
Best practice for accessing the annotations dict of other |
| 81 |
objects--functions, other callables, and modules--is the same |
| 82 |
as best practice for 3.10, assuming you aren't calling |
| 83 |
:func:`inspect.get_annotations`: you should use three-argument |
| 84 |
:func:`getattr` to access the object's ``__annotations__`` |
| 85 |
attribute. |
| 86 |
|
| 87 |
Unfortunately, this isn't best practice for classes. The problem |
| 88 |
is that, since ``__annotations__`` is optional on classes, and |
| 89 |
because classes can inherit attributes from their base classes, |
| 90 |
accessing the ``__annotations__`` attribute of a class may |
| 91 |
inadvertently return the annotations dict of a *base class.* |
| 92 |
As an example:: |
| 93 |
|
| 94 |
class Base: |
| 95 |
a: int = 3 |
| 96 |
b: str = 'abc' |
| 97 |
|
| 98 |
class Derived(Base): |
| 99 |
pass |
| 100 |
|
| 101 |
print(Derived.__annotations__) |
| 102 |
|
| 103 |
This will print the annotations dict from ``Base``, not |
| 104 |
``Derived``. |
| 105 |
|
| 106 |
Your code will have to have a separate code path if the object |
| 107 |
you're examining is a class (``isinstance(o, type)``). |
| 108 |
In that case, best practice relies on an implementation detail |
| 109 |
of Python 3.9 and before: if a class has annotations defined, |
| 110 |
they are stored in the class's :attr:`~type.__dict__` dictionary. Since |
| 111 |
the class may or may not have annotations defined, best practice |
| 112 |
is to call the :meth:`~dict.get` method on the class dict. |
| 113 |
|
| 114 |
To put it all together, here is some sample code that safely |
| 115 |
accesses the ``__annotations__`` attribute on an arbitrary |
| 116 |
object in Python 3.9 and before:: |
| 117 |
|
| 118 |
if isinstance(o, type): |
| 119 |
ann = o.__dict__.get('__annotations__', None) |
| 120 |
else: |
| 121 |
ann = getattr(o, '__annotations__', None) |
| 122 |
|
| 123 |
After running this code, ``ann`` should be either a |
| 124 |
dictionary or ``None``. You're encouraged to double-check |
| 125 |
the type of ``ann`` using :func:`isinstance` before further |
| 126 |
examination. |
| 127 |
|
| 128 |
Note that some exotic or malformed type objects may not have |
| 129 |
a :attr:`~type.__dict__` attribute, so for extra safety you may also wish |
| 130 |
to use :func:`getattr` to access :attr:`!__dict__`. |
| 131 |
|
| 132 |
|
| 133 |
Manually Un-Stringizing Stringized Annotations |
| 134 |
============================================== |
| 135 |
|
| 136 |
In situations where some annotations may be "stringized", |
| 137 |
and you wish to evaluate those strings to produce the |
| 138 |
Python values they represent, it really is best to |
| 139 |
call :func:`inspect.get_annotations` to do this work |
| 140 |
for you. |
| 141 |
|
| 142 |
If you're using Python 3.9 or older, or if for some reason |
| 143 |
you can't use :func:`inspect.get_annotations`, you'll need |
| 144 |
to duplicate its logic. You're encouraged to examine the |
| 145 |
implementation of :func:`inspect.get_annotations` in the |
| 146 |
current Python version and follow a similar approach. |
| 147 |
|
| 148 |
In a nutshell, if you wish to evaluate a stringized annotation |
| 149 |
on an arbitrary object ``o``: |
| 150 |
|
| 151 |
* If ``o`` is a module, use ``o.__dict__`` as the |
| 152 |
``globals`` when calling :func:`eval`. |
| 153 |
* If ``o`` is a class, use ``sys.modules[o.__module__].__dict__`` |
| 154 |
as the ``globals``, and ``dict(vars(o))`` as the ``locals``, |
| 155 |
when calling :func:`eval`. |
| 156 |
* If ``o`` is a wrapped callable using :func:`functools.update_wrapper`, |
| 157 |
:func:`functools.wraps`, or :func:`functools.partial`, iteratively |
| 158 |
unwrap it by accessing either ``o.__wrapped__`` or ``o.func`` as |
| 159 |
appropriate, until you have found the root unwrapped function. |
| 160 |
* If ``o`` is a callable (but not a class), use |
| 161 |
:attr:`o.__globals__ <function.__globals__>` as the globals when calling |
| 162 |
:func:`eval`. |
| 163 |
|
| 164 |
However, not all string values used as annotations can |
| 165 |
be successfully turned into Python values by :func:`eval`. |
| 166 |
String values could theoretically contain any valid string, |
| 167 |
and in practice there are valid use cases for type hints that |
| 168 |
require annotating with string values that specifically |
| 169 |
*can't* be evaluated. For example: |
| 170 |
|
| 171 |
* :pep:`604` union types using ``|``, before support for this |
| 172 |
was added to Python 3.10. |
| 173 |
* Definitions that aren't needed at runtime, only imported |
| 174 |
when :const:`typing.TYPE_CHECKING` is true. |
| 175 |
|
| 176 |
If :func:`eval` attempts to evaluate such values, it will |
| 177 |
fail and raise an exception. So, when designing a library |
| 178 |
API that works with annotations, it's recommended to only |
| 179 |
attempt to evaluate string values when explicitly requested |
| 180 |
to by the caller. |
| 181 |
|
| 182 |
|
| 183 |
Best Practices For ``__annotations__`` In Any Python Version |
| 184 |
============================================================ |
| 185 |
|
| 186 |
* You should avoid assigning to the ``__annotations__`` member |
| 187 |
of objects directly. Let Python manage setting ``__annotations__``. |
| 188 |
|
| 189 |
* If you do assign directly to the ``__annotations__`` member |
| 190 |
of an object, you should always set it to a ``dict`` object. |
| 191 |
|
| 192 |
* You should avoid accessing ``__annotations__`` directly on any object. |
| 193 |
Instead, use :func:`annotationlib.get_annotations` (Python 3.14+) |
| 194 |
or :func:`inspect.get_annotations` (Python 3.10+). |
| 195 |
|
| 196 |
* If you do directly access the ``__annotations__`` member |
| 197 |
of an object, you should ensure that it's a |
| 198 |
dictionary before attempting to examine its contents. |
| 199 |
|
| 200 |
* You should avoid modifying ``__annotations__`` dicts. |
| 201 |
|
| 202 |
* You should avoid deleting the ``__annotations__`` attribute |
| 203 |
of an object. |
| 204 |
|
| 205 |
|
| 206 |
``__annotations__`` Quirks |
| 207 |
========================== |
| 208 |
|
| 209 |
In all versions of Python 3, function |
| 210 |
objects lazy-create an annotations dict if no annotations |
| 211 |
are defined on that object. You can delete the ``__annotations__`` |
| 212 |
attribute using ``del fn.__annotations__``, but if you then |
| 213 |
access ``fn.__annotations__`` the object will create a new empty dict |
| 214 |
that it will store and return as its annotations. Deleting the |
| 215 |
annotations on a function before it has lazily created its annotations |
| 216 |
dict will throw an ``AttributeError``; using ``del fn.__annotations__`` |
| 217 |
twice in a row is guaranteed to always throw an ``AttributeError``. |
| 218 |
|
| 219 |
Everything in the above paragraph also applies to class and module |
| 220 |
objects in Python 3.10 and newer. |
| 221 |
|
| 222 |
In all versions of Python 3, you can set ``__annotations__`` |
| 223 |
on a function object to ``None``. However, subsequently |
| 224 |
accessing the annotations on that object using ``fn.__annotations__`` |
| 225 |
will lazy-create an empty dictionary as per the first paragraph of |
| 226 |
this section. This is *not* true of modules and classes, in any Python |
| 227 |
version; those objects permit setting ``__annotations__`` to any |
| 228 |
Python value, and will retain whatever value is set. |
| 229 |
|
| 230 |
If Python stringizes your annotations for you |
| 231 |
(using ``from __future__ import annotations``), and you |
| 232 |
specify a string as an annotation, the string will |
| 233 |
itself be quoted. In effect the annotation is quoted |
| 234 |
*twice.* For example:: |
| 235 |
|
| 236 |
from __future__ import annotations |
| 237 |
def foo(a: "str"): pass |
| 238 |
|
| 239 |
print(foo.__annotations__) |
| 240 |
|
| 241 |
This prints ``{'a': "'str'"}``. This shouldn't really be considered |
| 242 |
a "quirk"; it's mentioned here simply because it might be surprising. |
| 243 |
|
| 244 |
If you use a class with a custom metaclass and access ``__annotations__`` |
| 245 |
on the class, you may observe unexpected behavior; see |
| 246 |
:pep:`749 <749#pep749-metaclasses>` for some examples. You can avoid these |
| 247 |
quirks by using :func:`annotationlib.get_annotations` on Python 3.14+ or |
| 248 |
:func:`inspect.get_annotations` on Python 3.10+. On earlier versions of |
| 249 |
Python, you can avoid these bugs by accessing the annotations from the |
| 250 |
class's :attr:`~type.__dict__` |
| 251 |
(for example, ``cls.__dict__.get('__annotations__', None)``). |
| 252 |
|
| 253 |
In some versions of Python, instances of classes may have an ``__annotations__`` |
| 254 |
attribute. However, this is not supported functionality. If you need the |
| 255 |
annotations of an instance, you can use :func:`type` to access its class |
| 256 |
(for example, ``annotationlib.get_annotations(type(myinstance))`` on Python 3.14+). |