[doc] Clarify copyreg.pickle() documentation

[peterotten]

BPO	20823
Nosy	@serhiy-storchaka, @miss-islington, @kumaraditya303
PRs	bpo-20823: Clarify copyreg.pickle() documentation #30230 [3.10] bpo-20823: Clarify copyreg.pickle() documentation (GH-30230) #30669 [3.9] bpo-20823: Clarify copyreg.pickle() documentation (GH-30230) #30670
Files	copyreg.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2014-03-02.08:46:06.048>
labels = ['easy', 'type-bug', '3.9', '3.10', '3.11', 'docs']
title = '[doc] Clarify copyreg.pickle() documentation'
updated_at = <Date 2022-01-18.20:17:10.000>
user = 'https://bugs.python.org/peterotten'

bugs.python.org fields:

activity = <Date 2022-01-18.20:17:10.000>
actor = 'miss-islington'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2014-03-02.08:46:06.048>
creator = 'peter.otten'
dependencies = []
files = ['34263']
hgrepos = []
issue_num = 20823
keywords = ['patch', 'easy']
message_count = 6.0
messages = ['212541', '288092', '296271', '410883', '410884', '410885']
nosy_count = 5.0
nosy_names = ['peter.otten', 'docs@python', 'serhiy.storchaka', 'miss-islington', 'kumaraditya']
pr_nums = ['30230', '30669', '30670']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue20823'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

Linked PRs

• GH-65022: Fix description of copyreg.pickle function #102656
• gh-65022: Fix description of tuple return value in copyreg #103892
• [3.11] gh-65022: Fix description of tuple return value in copyreg (GH-103892) #104098

[peterotten]

The documentation for

copyreg.pickle(type, function, constructor=None)

has the sentence

"TypeError will be raised if *object* is a class or *constructor* is not callable."

It's not clear to me what "object" refers to. I believe it refers to the first arg (called ob_type in 2.x) and classic classes which were handled with

def pickle(ob_type, pickle_function, constructor_ob=None):
    if type(ob_type) is _ClassType:
        raise TypeError("copy_reg is not intended for use with classes")

in 2.x If I'm right the above sentence should become.

"A TypeError will be raised if *constructor* is not callable."

in 3.x. If I'm wrong please think of way to express the intended meaning more clearly.

Another minor change: class C need not inherit from object explicitly in 3.x.

[serhiy-storchaka]

The phrase "*function* should return either a string or a tuple containing two or three elements." de-facto is outdated too. Since Python 2.3 a tuple returned by the function must have two to five elements.

copyreg.constructor() no longer does anything useful, and the constructor parameter of copyreg.pickle() is virtually ignored.

[serhiy-storchaka]

Could you update your patch Peter, and since CPython development is moved to GitHub, create a pull request?

[serhiy-storchaka]

New changeset 65940fa by Kumar Aditya in branch 'main':
bpo-20823: Clarify copyreg.pickle() documentation (GH-30230)
65940fa

[miss-islington]

New changeset 9238a52 by Miss Islington (bot) in branch '3.10':
bpo-20823: Clarify copyreg.pickle() documentation (GH-30230)
9238a52

[miss-islington]

New changeset 8527f7a by Miss Islington (bot) in branch '3.9':
bpo-20823: Clarify copyreg.pickle() documentation (GH-30230)
8527f7a

[slateny]

The PR updated the wording on TypeError for constructor, but it looks like the wording on the 2/3 elements still needs an update.

[furkanonder]

@slateny What exactly do you mean by wording on the 2/3 elements?

[slateny]

I was referring to Serhiy's comment above regarding the wording of copyreg.pickle.

[furkanonder]

@serhiy-storchaka I updated the copyreg.pickle function description as;

function must return either a string or a tuple containing two or five elements. 

[nanjekyejoannah]

@serhiy-storchaka can decide when to close this, @furkanonder the doc update is merged.

[hauntsaninja]

@nanjekyejoannah @furkanonder I don't think the change in #102656 is correct. The tuple can also be three, four, or six elements, not just "two or five"

From https://docs.python.org/3/library/pickle.html

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:

Opened a PR for this in #103892