[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