From d5909383e985ef0c5c907e2b525388e55e6e9f89 Mon Sep 17 00:00:00 2001 From: mattip Date: Thu, 13 Dec 2018 08:23:25 +0200 Subject: [PATCH 1/5] DOC: emphasize the need to always call PySequence_Fast --- Doc/c-api/sequence.rst | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst index 6d22f35e22b1f2..64aa193a4236ef 100644 --- a/Doc/c-api/sequence.rst +++ b/Doc/c-api/sequence.rst @@ -130,25 +130,29 @@ Sequence Protocol .. c:function:: PyObject* PySequence_Fast(PyObject *o, const char *m) - Return the sequence or iterable *o* as a list, unless it is already a tuple or list, in - which case *o* is returned. Use :c:func:`PySequence_Fast_GET_ITEM` to access - the members of the result. Returns *NULL* on failure. If the object is not - a sequence or iterable, raises :exc:`TypeError` with *m* as the message text. + Return the sequence or iterable *o* as an object usable by the other + ``PySequence_Fast*`` family of functions. On CPython, if *o* is already a + sequence or list, it will be returned, but this is an implementation detail. + Returns *NULL* on failure. If the object is not a sequence or iterable, + raises :exc:`TypeError` with *m* as the message text. + + This family of functions is labelled *Fast* since it can assume *o* is a + :c:type:`PyTupleObject` or a :c:type:`PyListObject`, and accesses the type's + data fields directly. .. c:function:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o) Returns the length of *o*, assuming that *o* was returned by - :c:func:`PySequence_Fast` and that *o* is not *NULL*. The size can also be - gotten by calling :c:func:`PySequence_Size` on *o*, but - :c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list - or tuple. + :c:func:`PySequence_Fast` and that *o* is not *NULL*. Equivalent to + :c:func:`PySequence_Size` but faster. .. c:function:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i) Return the *i*\ th element of *o*, assuming that *o* was returned by :c:func:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds. + Equivalent to :c:func:`PySequence_GetItem` but faster. .. c:function:: PyObject** PySequence_Fast_ITEMS(PyObject *o) @@ -163,7 +167,7 @@ Sequence Protocol .. c:function:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i) - Return the *i*\ th element of *o* or *NULL* on failure. Macro form of + Return the *i*\ th element of *o* or *NULL* on failure. Faster form of :c:func:`PySequence_GetItem` but without checking that :c:func:`PySequence_Check` on *o* is true and without adjustment for negative indices. From f4a80528528420131484764a623eefbbbc47e60f Mon Sep 17 00:00:00 2001 From: mattip Date: Thu, 12 Sep 2019 18:18:11 +0300 Subject: [PATCH 2/5] DOC: changes from review --- Doc/c-api/sequence.rst | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst index 64aa193a4236ef..b80470552afb2b 100644 --- a/Doc/c-api/sequence.rst +++ b/Doc/c-api/sequence.rst @@ -131,28 +131,33 @@ Sequence Protocol .. c:function:: PyObject* PySequence_Fast(PyObject *o, const char *m) Return the sequence or iterable *o* as an object usable by the other - ``PySequence_Fast*`` family of functions. On CPython, if *o* is already a - sequence or list, it will be returned, but this is an implementation detail. + ``PySequence_Fast*`` family of functions. If the object is not a sequence or + iterable, raises :exc:`TypeError` with *m* as the message text. + + The ``PySequence_Fast*`` functions are thus named because they can assume + *o* is a :c:type:`PyTupleObject` or a :c:type:`PyListObject`, and accesses + the type's data fields directly. + Returns *NULL* on failure. If the object is not a sequence or iterable, raises :exc:`TypeError` with *m* as the message text. - This family of functions is labelled *Fast* since it can assume *o* is a - :c:type:`PyTupleObject` or a :c:type:`PyListObject`, and accesses the type's - data fields directly. + As a CPython implementation detail, if *o* is already a sequence or list, it + will be returned. .. c:function:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o) Returns the length of *o*, assuming that *o* was returned by - :c:func:`PySequence_Fast` and that *o* is not *NULL*. Equivalent to - :c:func:`PySequence_Size` but faster. + :c:func:`PySequence_Fast` and that *o* is not *NULL*. The size can also be + gotten by calling :c:func:`PySequence_Size` on *o*, but + :c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a + list or tuple. .. c:function:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i) Return the *i*\ th element of *o*, assuming that *o* was returned by :c:func:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds. - Equivalent to :c:func:`PySequence_GetItem` but faster. .. c:function:: PyObject** PySequence_Fast_ITEMS(PyObject *o) From 04a88227aac69a46581f44114e662735806b7173 Mon Sep 17 00:00:00 2001 From: mattip Date: Thu, 12 Sep 2019 18:38:40 +0300 Subject: [PATCH 3/5] DOC: changes from review --- Doc/c-api/sequence.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst index b80470552afb2b..52f5a7ffedc21c 100644 --- a/Doc/c-api/sequence.rst +++ b/Doc/c-api/sequence.rst @@ -134,12 +134,11 @@ Sequence Protocol ``PySequence_Fast*`` family of functions. If the object is not a sequence or iterable, raises :exc:`TypeError` with *m* as the message text. - The ``PySequence_Fast*`` functions are thus named because they can assume - *o* is a :c:type:`PyTupleObject` or a :c:type:`PyListObject`, and accesses - the type's data fields directly. + The ``PySequence_Fast*`` functions are thus named because they assume + *o* is a :c:type:`PyTupleObject` or a :c:type:`PyListObject`, and access + the data fields of *o* directly. - Returns *NULL* on failure. If the object is not a sequence or iterable, - raises :exc:`TypeError` with *m* as the message text. + Returns *NULL* on failure. As a CPython implementation detail, if *o* is already a sequence or list, it will be returned. From b1a77ed571f2345f6e241c3d077440071fa34de7 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Thu, 12 Sep 2019 17:03:12 +0100 Subject: [PATCH 4/5] tweak --- Doc/c-api/sequence.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst index 52f5a7ffedc21c..c415314cb13612 100644 --- a/Doc/c-api/sequence.rst +++ b/Doc/c-api/sequence.rst @@ -132,14 +132,13 @@ Sequence Protocol Return the sequence or iterable *o* as an object usable by the other ``PySequence_Fast*`` family of functions. If the object is not a sequence or - iterable, raises :exc:`TypeError` with *m* as the message text. + iterable, raises :exc:`TypeError` with *m* as the message text. Returns + *NULL* on failure. The ``PySequence_Fast*`` functions are thus named because they assume *o* is a :c:type:`PyTupleObject` or a :c:type:`PyListObject`, and access the data fields of *o* directly. - Returns *NULL* on failure. - As a CPython implementation detail, if *o* is already a sequence or list, it will be returned. From 01e14869fb895e74abc922c927c6fa6bc421c708 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Thu, 12 Sep 2019 17:04:05 +0100 Subject: [PATCH 5/5] delete comma --- Doc/c-api/sequence.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst index c415314cb13612..d653319f8064b8 100644 --- a/Doc/c-api/sequence.rst +++ b/Doc/c-api/sequence.rst @@ -136,7 +136,7 @@ Sequence Protocol *NULL* on failure. The ``PySequence_Fast*`` functions are thus named because they assume - *o* is a :c:type:`PyTupleObject` or a :c:type:`PyListObject`, and access + *o* is a :c:type:`PyTupleObject` or a :c:type:`PyListObject` and access the data fields of *o* directly. As a CPython implementation detail, if *o* is already a sequence or list, it