From 32f1491a9770b7f2989507ecf8f13ef35dd95b0b Mon Sep 17 00:00:00 2001
From: "Miss Islington (bot)"
 <31488909+miss-islington@users.noreply.github.com>
Date: Mon, 29 Nov 2021 10:32:56 -0800
Subject: [PATCH] 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@gmail.com>
---
 Doc/library/dataclasses.rst                   | 22 +++++++++++++++----
 .../2021-05-24-05-00-12.bpo-43905.tBIndE.rst  |  2 ++
 2 files changed, 20 insertions(+), 4 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2021-05-24-05-00-12.bpo-43905.tBIndE.rst

diff --git a/Doc/library/dataclasses.rst b/Doc/library/dataclasses.rst
index 5915bacbcdc4ec..7f9ffcb6137b40 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 00000000000000..760e1eea0deb70
--- /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.