bpo-35900: Add a state_setter arg to save_reduce (GH-12588)

Allow reduction methods to return a 6-item tuple where the 6th item specifies a
custom state-setting method that's called instead of the regular
``__setstate__`` method.

1 files changed, 10 insertions, 1 deletions

diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst
index 53eb5d39ef..3d89536d7d 100644
--- a/Doc/library/pickle.rst
+++ b/Doc/library/pickle.rst
@@ -598,7 +598,7 @@ or both.
    module; the pickle module searches the module namespace to determine the
    object's module.  This behaviour is typically useful for singletons.
 
-   When a tuple is returned, it must be between two and five items long.
+   When a tuple is returned, it must be between two and six items long.
    Optional items can either be omitted, or ``None`` can be provided as their
    value.  The semantics of each item are in order:
 
@@ -629,6 +629,15 @@ or both.
      value``.  This is primarily used for dictionary subclasses, but may be used
      by other classes as long as they implement :meth:`__setitem__`.
 
+   * Optionally, a callable with a ``(obj, state)`` signature. This
+     callable allows the user to programatically control the state-updating
+     behavior of a specific object, instead of using ``obj``'s static
+     :meth:`__setstate__` method. If not ``None``, this callable will have
+     priority over ``obj``'s :meth:`__setstate__`.
+
+     .. versionadded:: 3.8
+        The optional sixth tuple item, ``(obj, state)``, was added.
+
 
 .. method:: object.__reduce_ex__(protocol)