Sequence Protocol — Python 2.7.18 documentation

This document is for an old version of Python that is no longer supported. You should upgrade and read the Python documentation for the current stable release.

# Sequence Protocol

int `PySequence_Check`(PyObject *o)

  Return `1` if the object provides sequence protocol, and `0` otherwise. This function always succeeds.

Py_ssize_t `PySequence_Size`(PyObject *o)
Py_ssize_t `PySequence_Length`(PyObject *o)

  Returns the number of objects in sequence o on success, and `-1` on failure. This is equivalent to the Python expression `len(o)`.

  Changed in version 2.5: These functions returned an `int` type. This might require changes in your code for properly supporting 64-bit systems.

PyObject* `PySequence_Concat`(PyObject *o1, PyObject *o2)
  Return value: New reference.

  Return the concatenation of o1 and o2 on success, and NULL on failure. This is the equivalent of the Python expression `o1 + o2`.

PyObject* `PySequence_Repeat`(PyObject *o, Py_ssize_t count)
  Return value: New reference.

  Return the result of repeating sequence object o count times, or NULL on failure. This is the equivalent of the Python expression `o * count`.

  Changed in version 2.5: This function used an `int` type for count. This might require changes in your code for properly supporting 64-bit systems.

PyObject* `PySequence_InPlaceConcat`(PyObject *o1, PyObject *o2)
  Return value: New reference.

  Return the concatenation of o1 and o2 on success, and NULL on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python expression `o1 += o2`.

PyObject* `PySequence_InPlaceRepeat`(PyObject *o, Py_ssize_t count)
  Return value: New reference.

  Return the result of repeating sequence object o count times, or NULL on failure. The operation is done in-place when o supports it. This is the equivalent of the Python expression `o *= count`.

  Changed in version 2.5: This function used an `int` type for count. This might require changes in your code for properly supporting 64-bit systems.

PyObject* `PySequence_GetItem`(PyObject *o, Py_ssize_t i)
  Return value: New reference.

  Return the ith element of o, or NULL on failure. This is the equivalent of the Python expression `o[i]`.

  Changed in version 2.5: This function used an `int` type for i. This might require changes in your code for properly supporting 64-bit systems.

PyObject* `PySequence_GetSlice`(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
  Return value: New reference.

  Return the slice of sequence object o between i1 and i2, or NULL on failure. This is the equivalent of the Python expression `o[i1:i2]`.

  Changed in version 2.5: This function used an `int` type for i1 and i2. This might require changes in your code for properly supporting 64-bit systems.

int `PySequence_SetItem`(PyObject *o, Py_ssize_t i, PyObject *v)

  Assign object v to the ith element of o. Raise an exception and return `-1` on failure; return `0` on success. This is the equivalent of the Python statement `o[i] = v`. This function does not steal a reference to v.

  If v is NULL, the element is deleted, however this feature is deprecated in favour of using `PySequence_DelItem()`.

  Changed in version 2.5: This function used an `int` type for i. This might require changes in your code for properly supporting 64-bit systems.

int `PySequence_DelItem`(PyObject *o, Py_ssize_t i)

  Delete the ith element of object o. Returns `-1` on failure. This is the equivalent of the Python statement `del o[i]`.

  Changed in version 2.5: This function used an `int` type for i. This might require changes in your code for properly supporting 64-bit systems.

int `PySequence_SetSlice`(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)

  Assign the sequence object v to the slice in sequence object o from i1 to i2. Raise an exception and return `-1` on failure; return `0` on success. This is the equivalent of the Python statement `o[i1:i2] = v`.

  If v is NULL, the slice is deleted, however this feature is deprecated in favour of using `PySequence_DelSlice()`.

  Changed in version 2.5: This function used an `int` type for i1 and i2. This might require changes in your code for properly supporting 64-bit systems.

int `PySequence_DelSlice`(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)

  Delete the slice in sequence object o from i1 to i2. Returns `-1` on failure. This is the equivalent of the Python statement `del o[i1:i2]`.

  Changed in version 2.5: This function used an `int` type for i1 and i2. This might require changes in your code for properly supporting 64-bit systems.

Py_ssize_t `PySequence_Count`(PyObject *o, PyObject *value)

  Return the number of occurrences of value in o, that is, return the number of keys for which `o[key] == value`. On failure, return `-1`. This is equivalent to the Python expression `o.count(value)`.

  Changed in version 2.5: This function returned an `int` type. This might require changes in your code for properly supporting 64-bit systems.

int `PySequence_Contains`(PyObject *o, PyObject *value)

  Determine if o contains value. If an item in o is equal to value, return `1`, otherwise return `0`. On error, return `-1`. This is equivalent to the Python expression `value in o`.

Py_ssize_t `PySequence_Index`(PyObject *o, PyObject *value)

  Return the first index i for which `o[i] == value`. On error, return `-1`. This is equivalent to the Python expression `o.index(value)`.

  Changed in version 2.5: This function returned an `int` type. This might require changes in your code for properly supporting 64-bit systems.

PyObject* `PySequence_List`(PyObject *o)
  Return value: New reference.

  Return a list object with the same contents as the arbitrary sequence o. The returned list is guaranteed to be new.

PyObject* `PySequence_Tuple`(PyObject *o)
  Return value: New reference.

  Return a tuple object with the same contents as the arbitrary sequence o or NULL on failure. If o is a tuple, a new reference will be returned, otherwise a tuple will be constructed with the appropriate contents. This is equivalent to the Python expression `tuple(o)`.

PyObject* `PySequence_Fast`(PyObject *o, const char *m)
  Return value: New reference.

  Return the sequence o as a list, unless it is already a tuple or list, in which case o is returned. Use `PySequence_Fast_GET_ITEM()` to access the members of the result. Returns NULL on failure. If the object is not a sequence, raises `TypeError` with m as the message text.

PyObject* `PySequence_Fast_GET_ITEM`(PyObject *o, Py_ssize_t i)
  Return value: Borrowed reference.

  Return the ith element of o, assuming that o was returned by `PySequence_Fast()`, o is not NULL, and that i is within bounds.

  Changed in version 2.5: This function used an `int` type for i. This might require changes in your code for properly supporting 64-bit systems.

PyObject** `PySequence_Fast_ITEMS`(PyObject *o)

  Return the underlying array of PyObject pointers. Assumes that o was returned by `PySequence_Fast()` and o is not NULL.

  Note, if a list gets resized, the reallocation may relocate the items array. So, only use the underlying array pointer in contexts where the sequence cannot change.

  New in version 2.4.

PyObject* `PySequence_ITEM`(PyObject *o, Py_ssize_t i)
  Return value: New reference.

  Return the ith element of o or NULL on failure. Macro form of `PySequence_GetItem()` but without checking that `PySequence_Check()` on o is true and without adjustment for negative indices.

  New in version 2.3.

  Changed in version 2.5: This function used an `int` type for i. This might require changes in your code for properly supporting 64-bit systems.

Py_ssize_t `PySequence_Fast_GET_SIZE`(PyObject *o)

  Returns the length of o, assuming that o was returned by `PySequence_Fast()` and that o is not NULL. The size can also be gotten by calling `PySequence_Size()` on o, but `PySequence_Fast_GET_SIZE()` is faster because it can assume o is a list or tuple.