Skip to content

DOC: emphasize the need to always call PySequence_Fast #11140

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Sep 12, 2019
Merged

DOC: emphasize the need to always call PySequence_Fast #11140

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d590938
DOC: emphasize the need to always call PySequence_Fast
mattip Dec 13, 2018
f4a8052
DOC: changes from review
mattip Sep 12, 2019
04a8822
DOC: changes from review
mattip Sep 12, 2019
b1a77ed
tweak
benjaminp Sep 12, 2019
01e1486
delete comma
benjaminp Sep 12, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 14 additions & 7 deletions Doc/c-api/sequence.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,19 +130,26 @@ 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. If the object is not a sequence or
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.

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*. 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_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)
Expand All @@ -163,7 +170,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.