[Python-checkins] bpo-43905: Expand dataclasses.astuple() and asdict() docs (GH-26154)
miss-islington
webhook-mailer at python.org
Mon Nov 29 13:10:41 EST 2021
https://github.com/python/cpython/commit/c1f93f0d378958dfae4f24aad0c0088e3e04e403
commit: c1f93f0d378958dfae4f24aad0c0088e3e04e403
branch: main
author: andrei kulakov <andrei.avk at gmail.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2021-11-29T10:10:32-08:00
summary:
bpo-43905: Expand dataclasses.astuple() and asdict() docs (GH-26154)
Expanded ``astuple()`` docs, warning about deepcopy being applied
and providing a workaround.
Automerge-Triggered-By: GH:ericvsmith
files:
A Misc/NEWS.d/next/Documentation/2021-05-24-05-00-12.bpo-43905.tBIndE.rst
M Doc/library/dataclasses.rst
diff --git a/Doc/library/dataclasses.rst b/Doc/library/dataclasses.rst
index a7144094c6849..b06547074378f 100644
--- a/Doc/library/dataclasses.rst
+++ b/Doc/library/dataclasses.rst
@@ -324,7 +324,10 @@ Module contents
Converts the dataclass ``instance`` to a dict (by using the
factory function ``dict_factory``). Each dataclass is converted
to a dict of its fields, as ``name: value`` pairs. dataclasses, dicts,
- lists, and tuples are recursed into. For example::
+ lists, and tuples are recursed into. Other objects are copied with
+ :func:`copy.deepcopy`.
+
+ Example of using :func:`asdict` on nested dataclasses::
@dataclass
class Point:
@@ -341,21 +344,32 @@ Module contents
c = C([Point(0, 0), Point(10, 4)])
assert asdict(c) == {'mylist': [{'x': 0, 'y': 0}, {'x': 10, 'y': 4}]}
- Raises :exc:`TypeError` if ``instance`` is not a dataclass instance.
+ To create a shallow copy, the following workaround may be used::
+
+ dict((field.name, getattr(instance, field.name)) for field in fields(instance))
+
+ :func:`asdict` raises :exc:`TypeError` if ``instance`` is not a dataclass
+ instance.
.. function:: astuple(instance, *, tuple_factory=tuple)
Converts the dataclass ``instance`` to a tuple (by using the
factory function ``tuple_factory``). Each dataclass is converted
to a tuple of its field values. dataclasses, dicts, lists, and
- tuples are recursed into.
+ tuples are recursed into. Other objects are copied with
+ :func:`copy.deepcopy`.
Continuing from the previous example::
assert astuple(p) == (10, 20)
assert astuple(c) == ([(0, 0), (10, 4)],)
- Raises :exc:`TypeError` if ``instance`` is not a dataclass instance.
+ To create a shallow copy, the following workaround may be used::
+
+ tuple(getattr(instance, field.name) for field in dataclasses.fields(instance))
+
+ :func:`astuple` raises :exc:`TypeError` if ``instance`` is not a dataclass
+ instance.
.. function:: make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False, slots=False)
diff --git a/Misc/NEWS.d/next/Documentation/2021-05-24-05-00-12.bpo-43905.tBIndE.rst b/Misc/NEWS.d/next/Documentation/2021-05-24-05-00-12.bpo-43905.tBIndE.rst
new file mode 100644
index 0000000000000..760e1eea0deb7
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2021-05-24-05-00-12.bpo-43905.tBIndE.rst
@@ -0,0 +1,2 @@
+Expanded :func:`~dataclasses.astuple` and :func:`~dataclasses.asdict` docs,
+warning about deepcopy being applied and providing a workaround.
More information about the Python-checkins
mailing list