[issue29813] PyTuple_GetSlice documentation incorrect
New submission from Michael Seifert: The PyTuple_GetSlice documentation says it "Take a slice of the tuple pointed to by p from low to high and return it as a new tuple." [0] However in case the start is <= 0 and the stop is >= tuplesize it doesn't return the promised "new tuple", it just returns the tuplepointer after incrementing it's refcount [1]. The behaviour is fine (it gave me a bit of a headache though), however could a note/warning/sentence be included in the docs mentioning that special case? [0] https://docs.python.org/3/c-api/tuple.html#c.PyTuple_GetSlice [1] https://github.com/python/cpython/blob/master/Objects/tupleobject.c#L414 ---------- assignee: docs@python components: Documentation messages: 289632 nosy: MSeifert, docs@python priority: normal severity: normal status: open title: PyTuple_GetSlice documentation incorrect type: behavior _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29813> _______________________________________
Changes by Michael Seifert <michaelseifert04@yahoo.de>: ---------- title: PyTuple_GetSlice documentation incorrect -> PyTuple_GetSlice does not always return a new tuple _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29813> _______________________________________
Xiang Zhang added the comment: I think the description is fine. :-( What leads to your headache? ---------- nosy: +xiang.zhang _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29813> _______________________________________
Michael Seifert added the comment:
What leads to your headache?
That depending on the arguments to "PyTuple_GetSlice" I get "SystemError: ..\Objects\tupleobject.c:156: bad argument to internal function" when using PyTuple_SetItem on the (supposedly) new tuple. Maybe I just misunderstood the word "new" in the documentation. :-) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29813> _______________________________________
Changes by Xiang Zhang <angwerzx@126.com>: ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29813> _______________________________________
Raymond Hettinger added the comment: I think the docs are fine as-is. Whether an identical tuple is new or not is an implementation detail. IMO, the docs would create more confusion by trying to over-explain, "slicing of tuples always returns a new tuple when the result tuple is distinct from the original; however, in the case where the result tuple is not distinct, the implementation is at liberty to return the original tuple instead of a new tuple. Since tuples are immutable, this should make no difference at all to the user." ---------- resolution: -> not a bug stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29813> _______________________________________
Michael Seifert added the comment: I rather thought about something along the lines of: "Take a slice of the tuple pointed to by *p* from *low* to *high* and return it as a tuple. Whether the returned tuple is new or not is an implementation detail (and may depend on the value of the arguments)." Because from the point of the C-API tuples aren't immutable, at least not if they are new (refcount 1). Thank you both for your feedback. I'll leave it closed as "not a bug", I got the point about over-explaining. :) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29813> _______________________________________
participants (3)
-
Michael Seifert -
Raymond Hettinger
-
Xiang Zhang