classification
Title: pickle: inconsistent arguments pickle.py vs _pickle.c vs docs
Type: enhancement Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: crusaderky, docs@python, miss-islington, pitrou, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2020-01-23 17:12 by crusaderky, last changed 2020-05-02 06:38 by serhiy.storchaka. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 18160 merged python-dev, 2020-01-24 05:19
PR 19843 merged pitrou, 2020-05-01 19:47
PR 19844 merged pitrou, 2020-05-01 19:48
PR 19846 merged serhiy.storchaka, 2020-05-01 20:27
Messages (8)
msg360569 - (view) Author: Guido Imperiale (crusaderky) * Date: 2020-01-23 17:12
(1)
In the documentation for loads(), the name for the first argument of loads is 'bytes_object'. The actual signature, both in pickle.py and _pickle.c, it is instead 'data'.

(2)
In the documentation and in pickle.py, the default value for the 'buffers' parameter is None. However, in _pickle.c, it is an empty tuple (); this is also reflected by running the interpreter:

In [1]: inspect.signature(pickle.loads).parameters['buffers']                                                                                                                                                                                                    
Out[1]: <Parameter "buffers=()">

Thanks to @hauntsaninja for spotting these in https://github.com/python/typeshed/pull/3636
msg360643 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2020-01-24 19:31
As mentioned on the attached PR, the first argument is positional, so it doesn't matter that the name in the docs is not the same as the name in the code.

The name "bytes_object" makes it clear which type of object is accepted, which makes it a better fit IMHO than "data".  Therefore, I'm going to close this issue.
msg360678 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2020-01-25 09:23
Reopening because it seems my reading of the doc was wrong (took a backslash for a regular slash :-o).
msg364188 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2020-03-14 18:26
In pickle.py the name of the first parameter is "s" (it was "str" in 2.7), not "data". And in the module docstring it is "string". So we have two options:

1. Make the first parameter positional-only. This is not breaking change because the documentation and two implementations had four different names, so there was no official way to pass it by keyword.

2. Make it positional-and-keyword parameter officially. All implementations, documentation and docstrings should be synchronized.

What is more preferable? Do we need to pass the first argument to pickle.loads() by keyword?

After resolving this issue we may want to revise other modules which have the loads() function.
msg367876 - (view) Author: miss-islington (miss-islington) Date: 2020-05-01 19:46
New changeset 289842ae820f99908d3a345f1f3b6d4e5b4b97fc by Shantanu in branch 'master':
bpo-39435: Fix docs for pickle.loads (GH-18160)
https://github.com/python/cpython/commit/289842ae820f99908d3a345f1f3b6d4e5b4b97fc
msg367877 - (view) Author: miss-islington (miss-islington) Date: 2020-05-01 19:53
New changeset 3859b1ac1d7014f8ff673962d94a01a408546e24 by Antoine Pitrou in branch '3.7':
[3.7] bpo-39435: Fix docs for pickle.loads (GH-18160). (GH-19844)
https://github.com/python/cpython/commit/3859b1ac1d7014f8ff673962d94a01a408546e24
msg367878 - (view) Author: miss-islington (miss-islington) Date: 2020-05-01 19:54
New changeset e05828055e5165cc7268ea3bea33adc502e054a1 by Antoine Pitrou in branch '3.8':
[3.8] bpo-39435: Fix docs for pickle.loads (GH-18160) (GH-19843)
https://github.com/python/cpython/commit/e05828055e5165cc7268ea3bea33adc502e054a1
msg367917 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2020-05-02 06:38
New changeset 531d1e541284bfd7944f8c66a5e8c3c3234afaff by Serhiy Storchaka in branch 'master':
bpo-39435: Make the first argument of pickle.loads() positional-only. (GH-19846)
https://github.com/python/cpython/commit/531d1e541284bfd7944f8c66a5e8c3c3234afaff
History
Date User Action Args
2020-05-02 06:38:08serhiy.storchakasetmessages: + msg367917
2020-05-01 20:27:10serhiy.storchakasetpull_requests: + pull_request19164
2020-05-01 19:59:45pitrousetstatus: open -> closed
stage: patch review -> resolved
resolution: fixed
versions: + Python 3.7, Python 3.8
2020-05-01 19:54:47miss-islingtonsetmessages: + msg367878
2020-05-01 19:53:42miss-islingtonsetmessages: + msg367877
2020-05-01 19:48:20pitrousetpull_requests: + pull_request19162
2020-05-01 19:47:09pitrousetstage: patch review
pull_requests: + pull_request19161
2020-05-01 19:46:09miss-islingtonsetnosy: + miss-islington
messages: + msg367876
2020-03-14 18:26:43serhiy.storchakasettype: enhancement
versions: + Python 3.9, - Python 3.8
2020-03-14 18:26:06serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg364188
2020-01-25 09:23:45pitrousetstatus: closed -> open
resolution: not a bug -> (no value)
messages: + msg360678

stage: resolved -> (no value)
2020-01-24 19:31:40pitrousetstatus: open -> closed
resolution: not a bug
messages: + msg360643

stage: patch review -> resolved
2020-01-24 05:19:56python-devsetkeywords: + patch
stage: patch review
pull_requests: + pull_request17547
2020-01-23 18:43:26xtreaksetnosy: + pitrou
2020-01-23 17:12:19crusaderkycreate