Skip to content

gh-148669: Clarify __reduce__() module lookup behavior #148670

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JelleZijlstra merged 3 commits into from
May 12, 2026
+5 −2
Merged

gh-148669: Clarify __reduce__() module lookup behavior #148670

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
63ba350
Clarify `__reduce__()` behavior when a string is returned
Viicos Apr 17, 2026
37851dd
Remove outdated pickle limitation
Viicos Apr 17, 2026
0dfae55
Apply suggestions from code review
Viicos May 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions Doc/library/pickle.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ The :mod:`!pickle` module differs from :mod:`marshal` in several significant way
* :mod:`marshal` cannot be used to serialize user-defined classes and their
instances. :mod:`!pickle` can save and restore class instances transparently,
Copy link
Copy Markdown
Member

@JelleZijlstra JelleZijlstra Apr 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why was this removed? It's still accurate.

Copy link
Copy Markdown
Contributor Author

@Viicos Viicos Apr 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think the statement was true? It is perfectly fine to pickle an instance which lives in a separate module than the one storing the class definition right?

Copy link
Copy Markdown
Member

@JelleZijlstra JelleZijlstra Apr 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This refers to cases where the class is no longer accessible at its assigned place. For example, if you pickle an instance of some_mod.ClassA, then do del some_mod.ClassA, you can't unpickle the instance any more.

Copy link
Copy Markdown
Contributor Author

@Viicos Viicos Apr 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like I deleted too much, we should just keep however the class definition must be importable. But the instance doesn't have to live in the same module of the class:

# module1.py

class Test: ...
# module2.py

import pickle
from module1 import Test

t = Test()
pickle.loads(pickle.dumps(t))  # fine

Copy link
Copy Markdown
Member

@JelleZijlstra JelleZijlstra May 10, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is referring to cases where the class definition is moved between the pickling and unpickling code. Not a common issue but that can be relevant if e.g. a new library (or stdlib) version moves a class from one file to another, and you try to pickle under one version and unpickle under another.

Copy link
Copy Markdown
Contributor Author

@Viicos Viicos May 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed that makes sense. I think I misread when -> where.

however the class definition must be importable and live in the same module as
when the object was stored.
when the object was pickled.

* The :mod:`marshal` serialization format is not guaranteed to be portable
across Python versions. Because its primary job in life is to support
Expand Down Expand Up @@ -693,7 +693,10 @@ or both.
If a string is returned, the string should be interpreted as the name of a
global variable. It should be the object's local name relative to its
module; the pickle module searches the module namespace to determine the
object's module. This behaviour is typically useful for singletons.
object's module: for a given ``obj`` to be pickled, the ``__module__``
attribute is looked up on ``obj`` directly, which falls back to a lookup
on the type of ``obj`` if no ``__module__`` instance attribute is set.
This behaviour is typically useful for singletons.

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
Expand Down
Loading