mirror of
https://github.com/python/cpython.git
synced 2025-09-27 02:39:58 +00:00
[3.12] gh-107432 Fix incorrect indentation in annotations HOWTO (GH-107445) (#107654)
gh-107432 Fix incorrect indentation in annotations HOWTO (GH-107445)
gh-107432 Fix incorrect indentation in annotations document
Body text in https://docs.python.org/3/howto/annotations.html was
indented throughout, and was being rendered in blockquote elements.
(cherry picked from commit 5e2746d6e2)
Co-authored-by: Daniele Procida <daniele@vurt.org>
This commit is contained in:
Miss Islington (bot)
GitHub
parent
6e4eec7606
commit
236cdadb08
1 changed files with 148 additions and 148 deletions
|
|
@ -32,201 +32,201 @@ Annotations Best Practices
|
||||||
Accessing The Annotations Dict Of An Object In Python 3.10 And Newer
|
Accessing The Annotations Dict Of An Object In Python 3.10 And Newer
|
||||||
====================================================================
|
====================================================================
|
||||||
|
|
||||||
Python 3.10 adds a new function to the standard library:
|
Python 3.10 adds a new function to the standard library:
|
||||||
:func:`inspect.get_annotations`. In Python versions 3.10
|
:func:`inspect.get_annotations`. In Python versions 3.10
|
||||||
and newer, calling this function is the best practice for
|
and newer, calling this function is the best practice for
|
||||||
accessing the annotations dict of any object that supports
|
accessing the annotations dict of any object that supports
|
||||||
annotations. This function can also "un-stringize"
|
annotations. This function can also "un-stringize"
|
||||||
stringized annotations for you.
|
stringized annotations for you.
|
||||||
|
|
||||||
If for some reason :func:`inspect.get_annotations` isn't
|
If for some reason :func:`inspect.get_annotations` isn't
|
||||||
viable for your use case, you may access the
|
viable for your use case, you may access the
|
||||||
``__annotations__`` data member manually. Best practice
|
``__annotations__`` data member manually. Best practice
|
||||||
for this changed in Python 3.10 as well: as of Python 3.10,
|
for this changed in Python 3.10 as well: as of Python 3.10,
|
||||||
``o.__annotations__`` is guaranteed to *always* work
|
``o.__annotations__`` is guaranteed to *always* work
|
||||||
on Python functions, classes, and modules. If you're
|
on Python functions, classes, and modules. If you're
|
||||||
certain the object you're examining is one of these three
|
certain the object you're examining is one of these three
|
||||||
*specific* objects, you may simply use ``o.__annotations__``
|
*specific* objects, you may simply use ``o.__annotations__``
|
||||||
to get at the object's annotations dict.
|
to get at the object's annotations dict.
|
||||||
|
|
||||||
However, other types of callables--for example,
|
However, other types of callables--for example,
|
||||||
callables created by :func:`functools.partial`--may
|
callables created by :func:`functools.partial`--may
|
||||||
not have an ``__annotations__`` attribute defined. When
|
not have an ``__annotations__`` attribute defined. When
|
||||||
accessing the ``__annotations__`` of a possibly unknown
|
accessing the ``__annotations__`` of a possibly unknown
|
||||||
object, best practice in Python versions 3.10 and
|
object, best practice in Python versions 3.10 and
|
||||||
newer is to call :func:`getattr` with three arguments,
|
newer is to call :func:`getattr` with three arguments,
|
||||||
for example ``getattr(o, '__annotations__', None)``.
|
for example ``getattr(o, '__annotations__', None)``.
|
||||||
|
|
||||||
Before Python 3.10, accessing ``__annotations__`` on a class that
|
Before Python 3.10, accessing ``__annotations__`` on a class that
|
||||||
defines no annotations but that has a parent class with
|
defines no annotations but that has a parent class with
|
||||||
annotations would return the parent's ``__annotations__``.
|
annotations would return the parent's ``__annotations__``.
|
||||||
In Python 3.10 and newer, the child class's annotations
|
In Python 3.10 and newer, the child class's annotations
|
||||||
will be an empty dict instead.
|
will be an empty dict instead.
|
||||||
|
|
||||||
|
|
||||||
Accessing The Annotations Dict Of An Object In Python 3.9 And Older
|
Accessing The Annotations Dict Of An Object In Python 3.9 And Older
|
||||||
===================================================================
|
===================================================================
|
||||||
|
|
||||||
In Python 3.9 and older, accessing the annotations dict
|
In Python 3.9 and older, accessing the annotations dict
|
||||||
of an object is much more complicated than in newer versions.
|
of an object is much more complicated than in newer versions.
|
||||||
The problem is a design flaw in these older versions of Python,
|
The problem is a design flaw in these older versions of Python,
|
||||||
specifically to do with class annotations.
|
specifically to do with class annotations.
|
||||||
|
|
||||||
Best practice for accessing the annotations dict of other
|
Best practice for accessing the annotations dict of other
|
||||||
objects--functions, other callables, and modules--is the same
|
objects--functions, other callables, and modules--is the same
|
||||||
as best practice for 3.10, assuming you aren't calling
|
as best practice for 3.10, assuming you aren't calling
|
||||||
:func:`inspect.get_annotations`: you should use three-argument
|
:func:`inspect.get_annotations`: you should use three-argument
|
||||||
:func:`getattr` to access the object's ``__annotations__``
|
:func:`getattr` to access the object's ``__annotations__``
|
||||||
attribute.
|
attribute.
|
||||||
|
|
||||||
Unfortunately, this isn't best practice for classes. The problem
|
Unfortunately, this isn't best practice for classes. The problem
|
||||||
is that, since ``__annotations__`` is optional on classes, and
|
is that, since ``__annotations__`` is optional on classes, and
|
||||||
because classes can inherit attributes from their base classes,
|
because classes can inherit attributes from their base classes,
|
||||||
accessing the ``__annotations__`` attribute of a class may
|
accessing the ``__annotations__`` attribute of a class may
|
||||||
inadvertently return the annotations dict of a *base class.*
|
inadvertently return the annotations dict of a *base class.*
|
||||||
As an example::
|
As an example::
|
||||||
|
|
||||||
class Base:
|
class Base:
|
||||||
a: int = 3
|
a: int = 3
|
||||||
b: str = 'abc'
|
b: str = 'abc'
|
||||||
|
|
||||||
class Derived(Base):
|
class Derived(Base):
|
||||||
pass
|
pass
|
||||||
|
|
||||||
print(Derived.__annotations__)
|
print(Derived.__annotations__)
|
||||||
|
|
||||||
This will print the annotations dict from ``Base``, not
|
This will print the annotations dict from ``Base``, not
|
||||||
``Derived``.
|
``Derived``.
|
||||||
|
|
||||||
Your code will have to have a separate code path if the object
|
Your code will have to have a separate code path if the object
|
||||||
you're examining is a class (``isinstance(o, type)``).
|
you're examining is a class (``isinstance(o, type)``).
|
||||||
In that case, best practice relies on an implementation detail
|
In that case, best practice relies on an implementation detail
|
||||||
of Python 3.9 and before: if a class has annotations defined,
|
of Python 3.9 and before: if a class has annotations defined,
|
||||||
they are stored in the class's ``__dict__`` dictionary. Since
|
they are stored in the class's ``__dict__`` dictionary. Since
|
||||||
the class may or may not have annotations defined, best practice
|
the class may or may not have annotations defined, best practice
|
||||||
is to call the ``get`` method on the class dict.
|
is to call the ``get`` method on the class dict.
|
||||||
|
|
||||||
To put it all together, here is some sample code that safely
|
To put it all together, here is some sample code that safely
|
||||||
accesses the ``__annotations__`` attribute on an arbitrary
|
accesses the ``__annotations__`` attribute on an arbitrary
|
||||||
object in Python 3.9 and before::
|
object in Python 3.9 and before::
|
||||||
|
|
||||||
if isinstance(o, type):
|
if isinstance(o, type):
|
||||||
ann = o.__dict__.get('__annotations__', None)
|
ann = o.__dict__.get('__annotations__', None)
|
||||||
else:
|
else:
|
||||||
ann = getattr(o, '__annotations__', None)
|
ann = getattr(o, '__annotations__', None)
|
||||||
|
|
||||||
After running this code, ``ann`` should be either a
|
After running this code, ``ann`` should be either a
|
||||||
dictionary or ``None``. You're encouraged to double-check
|
dictionary or ``None``. You're encouraged to double-check
|
||||||
the type of ``ann`` using :func:`isinstance` before further
|
the type of ``ann`` using :func:`isinstance` before further
|
||||||
examination.
|
examination.
|
||||||
|
|
||||||
Note that some exotic or malformed type objects may not have
|
Note that some exotic or malformed type objects may not have
|
||||||
a ``__dict__`` attribute, so for extra safety you may also wish
|
a ``__dict__`` attribute, so for extra safety you may also wish
|
||||||
to use :func:`getattr` to access ``__dict__``.
|
to use :func:`getattr` to access ``__dict__``.
|
||||||
|
|
||||||
|
|
||||||
Manually Un-Stringizing Stringized Annotations
|
Manually Un-Stringizing Stringized Annotations
|
||||||
==============================================
|
==============================================
|
||||||
|
|
||||||
In situations where some annotations may be "stringized",
|
In situations where some annotations may be "stringized",
|
||||||
and you wish to evaluate those strings to produce the
|
and you wish to evaluate those strings to produce the
|
||||||
Python values they represent, it really is best to
|
Python values they represent, it really is best to
|
||||||
call :func:`inspect.get_annotations` to do this work
|
call :func:`inspect.get_annotations` to do this work
|
||||||
for you.
|
for you.
|
||||||
|
|
||||||
If you're using Python 3.9 or older, or if for some reason
|
If you're using Python 3.9 or older, or if for some reason
|
||||||
you can't use :func:`inspect.get_annotations`, you'll need
|
you can't use :func:`inspect.get_annotations`, you'll need
|
||||||
to duplicate its logic. You're encouraged to examine the
|
to duplicate its logic. You're encouraged to examine the
|
||||||
implementation of :func:`inspect.get_annotations` in the
|
implementation of :func:`inspect.get_annotations` in the
|
||||||
current Python version and follow a similar approach.
|
current Python version and follow a similar approach.
|
||||||
|
|
||||||
In a nutshell, if you wish to evaluate a stringized annotation
|
In a nutshell, if you wish to evaluate a stringized annotation
|
||||||
on an arbitrary object ``o``:
|
on an arbitrary object ``o``:
|
||||||
|
|
||||||
* If ``o`` is a module, use ``o.__dict__`` as the
|
* If ``o`` is a module, use ``o.__dict__`` as the
|
||||||
``globals`` when calling :func:`eval`.
|
``globals`` when calling :func:`eval`.
|
||||||
* If ``o`` is a class, use ``sys.modules[o.__module__].__dict__``
|
* If ``o`` is a class, use ``sys.modules[o.__module__].__dict__``
|
||||||
as the ``globals``, and ``dict(vars(o))`` as the ``locals``,
|
as the ``globals``, and ``dict(vars(o))`` as the ``locals``,
|
||||||
when calling :func:`eval`.
|
when calling :func:`eval`.
|
||||||
* If ``o`` is a wrapped callable using :func:`functools.update_wrapper`,
|
* If ``o`` is a wrapped callable using :func:`functools.update_wrapper`,
|
||||||
:func:`functools.wraps`, or :func:`functools.partial`, iteratively
|
:func:`functools.wraps`, or :func:`functools.partial`, iteratively
|
||||||
unwrap it by accessing either ``o.__wrapped__`` or ``o.func`` as
|
unwrap it by accessing either ``o.__wrapped__`` or ``o.func`` as
|
||||||
appropriate, until you have found the root unwrapped function.
|
appropriate, until you have found the root unwrapped function.
|
||||||
* If ``o`` is a callable (but not a class), use
|
* If ``o`` is a callable (but not a class), use
|
||||||
``o.__globals__`` as the globals when calling :func:`eval`.
|
``o.__globals__`` as the globals when calling :func:`eval`.
|
||||||
|
|
||||||
However, not all string values used as annotations can
|
However, not all string values used as annotations can
|
||||||
be successfully turned into Python values by :func:`eval`.
|
be successfully turned into Python values by :func:`eval`.
|
||||||
String values could theoretically contain any valid string,
|
String values could theoretically contain any valid string,
|
||||||
and in practice there are valid use cases for type hints that
|
and in practice there are valid use cases for type hints that
|
||||||
require annotating with string values that specifically
|
require annotating with string values that specifically
|
||||||
*can't* be evaluated. For example:
|
*can't* be evaluated. For example:
|
||||||
|
|
||||||
* :pep:`604` union types using ``|``, before support for this
|
* :pep:`604` union types using ``|``, before support for this
|
||||||
was added to Python 3.10.
|
was added to Python 3.10.
|
||||||
* Definitions that aren't needed at runtime, only imported
|
* Definitions that aren't needed at runtime, only imported
|
||||||
when :const:`typing.TYPE_CHECKING` is true.
|
when :const:`typing.TYPE_CHECKING` is true.
|
||||||
|
|
||||||
If :func:`eval` attempts to evaluate such values, it will
|
If :func:`eval` attempts to evaluate such values, it will
|
||||||
fail and raise an exception. So, when designing a library
|
fail and raise an exception. So, when designing a library
|
||||||
API that works with annotations, it's recommended to only
|
API that works with annotations, it's recommended to only
|
||||||
attempt to evaluate string values when explicitly requested
|
attempt to evaluate string values when explicitly requested
|
||||||
to by the caller.
|
to by the caller.
|
||||||
|
|
||||||
|
|
||||||
Best Practices For ``__annotations__`` In Any Python Version
|
Best Practices For ``__annotations__`` In Any Python Version
|
||||||
============================================================
|
============================================================
|
||||||
|
|
||||||
* You should avoid assigning to the ``__annotations__`` member
|
* You should avoid assigning to the ``__annotations__`` member
|
||||||
of objects directly. Let Python manage setting ``__annotations__``.
|
of objects directly. Let Python manage setting ``__annotations__``.
|
||||||
|
|
||||||
* If you do assign directly to the ``__annotations__`` member
|
* If you do assign directly to the ``__annotations__`` member
|
||||||
of an object, you should always set it to a ``dict`` object.
|
of an object, you should always set it to a ``dict`` object.
|
||||||
|
|
||||||
* If you directly access the ``__annotations__`` member
|
* If you directly access the ``__annotations__`` member
|
||||||
of an object, you should ensure that it's a
|
of an object, you should ensure that it's a
|
||||||
dictionary before attempting to examine its contents.
|
dictionary before attempting to examine its contents.
|
||||||
|
|
||||||
* You should avoid modifying ``__annotations__`` dicts.
|
* You should avoid modifying ``__annotations__`` dicts.
|
||||||
|
|
||||||
* You should avoid deleting the ``__annotations__`` attribute
|
* You should avoid deleting the ``__annotations__`` attribute
|
||||||
of an object.
|
of an object.
|
||||||
|
|
||||||
|
|
||||||
``__annotations__`` Quirks
|
``__annotations__`` Quirks
|
||||||
==========================
|
==========================
|
||||||
|
|
||||||
In all versions of Python 3, function
|
In all versions of Python 3, function
|
||||||
objects lazy-create an annotations dict if no annotations
|
objects lazy-create an annotations dict if no annotations
|
||||||
are defined on that object. You can delete the ``__annotations__``
|
are defined on that object. You can delete the ``__annotations__``
|
||||||
attribute using ``del fn.__annotations__``, but if you then
|
attribute using ``del fn.__annotations__``, but if you then
|
||||||
access ``fn.__annotations__`` the object will create a new empty dict
|
access ``fn.__annotations__`` the object will create a new empty dict
|
||||||
that it will store and return as its annotations. Deleting the
|
that it will store and return as its annotations. Deleting the
|
||||||
annotations on a function before it has lazily created its annotations
|
annotations on a function before it has lazily created its annotations
|
||||||
dict will throw an ``AttributeError``; using ``del fn.__annotations__``
|
dict will throw an ``AttributeError``; using ``del fn.__annotations__``
|
||||||
twice in a row is guaranteed to always throw an ``AttributeError``.
|
twice in a row is guaranteed to always throw an ``AttributeError``.
|
||||||
|
|
||||||
Everything in the above paragraph also applies to class and module
|
Everything in the above paragraph also applies to class and module
|
||||||
objects in Python 3.10 and newer.
|
objects in Python 3.10 and newer.
|
||||||
|
|
||||||
In all versions of Python 3, you can set ``__annotations__``
|
In all versions of Python 3, you can set ``__annotations__``
|
||||||
on a function object to ``None``. However, subsequently
|
on a function object to ``None``. However, subsequently
|
||||||
accessing the annotations on that object using ``fn.__annotations__``
|
accessing the annotations on that object using ``fn.__annotations__``
|
||||||
will lazy-create an empty dictionary as per the first paragraph of
|
will lazy-create an empty dictionary as per the first paragraph of
|
||||||
this section. This is *not* true of modules and classes, in any Python
|
this section. This is *not* true of modules and classes, in any Python
|
||||||
version; those objects permit setting ``__annotations__`` to any
|
version; those objects permit setting ``__annotations__`` to any
|
||||||
Python value, and will retain whatever value is set.
|
Python value, and will retain whatever value is set.
|
||||||
|
|
||||||
If Python stringizes your annotations for you
|
If Python stringizes your annotations for you
|
||||||
(using ``from __future__ import annotations``), and you
|
(using ``from __future__ import annotations``), and you
|
||||||
specify a string as an annotation, the string will
|
specify a string as an annotation, the string will
|
||||||
itself be quoted. In effect the annotation is quoted
|
itself be quoted. In effect the annotation is quoted
|
||||||
*twice.* For example::
|
*twice.* For example::
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
def foo(a: "str"): pass
|
def foo(a: "str"): pass
|
||||||
|
|
||||||
print(foo.__annotations__)
|
print(foo.__annotations__)
|
||||||
|
|
||||||
This prints ``{'a': "'str'"}``. This shouldn't really be considered
|
This prints ``{'a': "'str'"}``. This shouldn't really be considered
|
||||||
a "quirk"; it's mentioned here simply because it might be surprising.
|
a "quirk"; it's mentioned here simply because it might be surprising.
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue