[Python-checkins] bpo-43905: Expand dataclasses.astuple() and asdict() docs (GH-26154)

[miss-islington]

https://github.com/python/cpython/commit/32f1491a9770b7f2989507ecf8f13ef35dd95b0b
commit: 32f1491a9770b7f2989507ecf8f13ef35dd95b0b
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2021-11-29T10:32:56-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
(cherry picked from commit c1f93f0d378958dfae4f24aad0c0088e3e04e403)

Co-authored-by: andrei kulakov <andrei.avk at gmail.com>

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 5915bacbcdc4e..7f9ffcb6137b4 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.