classification
Title: PyTuple_GetSlice docs minor inaccuracy
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, miss-islington, serhiy.storchaka, terry.reedy, wim.glenn
Priority: normal Keywords: patch

Created on 2019-10-22 15:51 by wim.glenn, last changed 2019-10-26 21:14 by serhiy.storchaka. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 16925 merged serhiy.storchaka, 2019-10-25 21:28
PR 16933 merged miss-islington, 2019-10-26 19:59
PR 16934 merged miss-islington, 2019-10-26 19:59
PR 16935 merged miss-islington, 2019-10-26 20:00
Messages (7)
msg355141 - (view) Author: wim glenn (wim.glenn) * Date: 2019-10-22 15:51
https://docs.python.org/3/c-api/tuple.html#c.PyTuple_GetSlice

In the c-api it says (emphasis mine):

    PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)ΒΆ
    Return value: New reference.

    Take a slice of the tuple pointed to by p from low to high and return it **as a new tuple**.

But when slicing the entire tuple, CPython will return already existing instance, not a new tuple.

https://github.com/python/cpython/blob/3.8/Objects/tupleobject.c#L448-L451

I propose the language in the docs be loosened so as not to tie the hands of implementation
msg355385 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-10-25 20:18
Verified from Python.
>>> t = (1,2,3)
>>> t2 = t[:]
>>> id(t), id(t2)
(1672756229504, 1672756229504)

A partial slice cannot the original tuple, so I presume that the emphasis is about returning a (new) *tuple*, rather than some sort of view of the original.  However,
        Py_INCREF(a);
        return (PyObject *)a;
date back to at least 1997 (GvR), so the optimization is not new.  I don't know what should replace 'New reference.'  'Old or new reverence.'?

"Take a slice of the tuple pointed to by p from low to high and return it **as a new tuple**."

could be replaces with

"Return the slice of the tuple point to by p for low to high.  If it is a proper subslice, return a new tuple."

This leave it undefined when a complete slice.
msg355388 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2019-10-25 21:34
The part about "new tuple" can be removed. The documentation olready contains an automatically generated note about a new reference.

PR 16925 improves the documentation for getting/setting items/slices of lists and tuples.
msg355426 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2019-10-26 19:59
New changeset d898d20e8c228229eb68e545f544db13f246f216 by Serhiy Storchaka in branch 'master':
bpo-38557: Improve documentation for list and tuple C API. (GH-16925)
https://github.com/python/cpython/commit/d898d20e8c228229eb68e545f544db13f246f216
msg355428 - (view) Author: miss-islington (miss-islington) Date: 2019-10-26 20:04
New changeset 7356e10820b160d14b0ce0aba5427a8f9e757aa7 by Miss Skeleton (bot) in branch '2.7':
bpo-38557: Improve documentation for list and tuple C API. (GH-16925)
https://github.com/python/cpython/commit/7356e10820b160d14b0ce0aba5427a8f9e757aa7
msg355429 - (view) Author: miss-islington (miss-islington) Date: 2019-10-26 20:05
New changeset 334fc923b3a7a8d0d163692befd2a27b98b481df by Miss Skeleton (bot) in branch '3.7':
bpo-38557: Improve documentation for list and tuple C API. (GH-16925)
https://github.com/python/cpython/commit/334fc923b3a7a8d0d163692befd2a27b98b481df
msg355430 - (view) Author: miss-islington (miss-islington) Date: 2019-10-26 20:06
New changeset 4992dc6610fb354e36c0012a47ea9613b61c9038 by Miss Skeleton (bot) in branch '3.8':
bpo-38557: Improve documentation for list and tuple C API. (GH-16925)
https://github.com/python/cpython/commit/4992dc6610fb354e36c0012a47ea9613b61c9038
History
Date User Action Args
2019-10-26 21:14:51serhiy.storchakasetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2019-10-26 20:06:37miss-islingtonsetmessages: + msg355430
2019-10-26 20:05:21miss-islingtonsetmessages: + msg355429
2019-10-26 20:04:16miss-islingtonsetnosy: + miss-islington
messages: + msg355428
2019-10-26 20:00:00miss-islingtonsetpull_requests: + pull_request16464
2019-10-26 19:59:53miss-islingtonsetpull_requests: + pull_request16463
2019-10-26 19:59:47miss-islingtonsetstage: patch review
pull_requests: + pull_request16462
2019-10-26 19:59:22serhiy.storchakasetmessages: + msg355426
2019-10-25 21:34:31serhiy.storchakasetnosy: + serhiy.storchaka

messages: + msg355388
stage: patch review -> (no value)
2019-10-25 21:28:15serhiy.storchakasetkeywords: + patch
stage: patch review
pull_requests: + pull_request16455
2019-10-25 20:18:29terry.reedysetnosy: + terry.reedy

messages: + msg355385
versions: - Python 3.5, Python 3.6
2019-10-22 15:51:00wim.glenncreate