Debian Codegraph @

Doc/howto/annotations.rst

raw
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+).