# Objeto List

type PyListObject

  Este subtipo de `PyObject` representa um objeto de lista Python.

PyTypeObject PyList_Type
  Parte da ABI Estável.

  Esta instância de `PyTypeObject` representa o tipo de lista Python. Este é o mesmo objeto que `list` na camada Python.

int PyList_Check(PyObject *p)
  Thread safety: Atomic.

  Retorna verdadeiro se p é um objeto lista ou uma instância de um subtipo do tipo lista. Esta função sempre tem sucesso.

int PyList_CheckExact(PyObject *p)
  Thread safety: Atomic.

  Retorna verdadeiro se p é um objeto lista, mas não uma instância de um subtipo do tipo lista. Esta função sempre tem sucesso.

PyObject *PyList_New(Py_ssize_t len)
  Retorna valor: Nova referência. Parte da ABI Estável. Thread safety: Atomic.

  Retorna uma nova lista de comprimento len em caso de sucesso, ou `NULL` em caso de falha.

  Nota

  Se len for maior que zero, os itens do objeto da lista retornada são definidos como `NULL`. Portanto, você não pode usar funções API abstratas, como `PySequence_SetItem()` ou expor o objeto ao código Python antes de definir todos os itens para um objeto real com `PyList_SetItem()` ou `PyList_SET_ITEM()`. As seguintes APIs são seguras desde que antes as listas tenham sido inicializadas: `PyList_SetItem()` e `PyList_SET_ITEM()`.

Py_ssize_t PyList_Size(PyObject *list)
  Parte da ABI Estável. Thread safety: Atomic.

  Retorna o comprimento do objeto de lista em list; isto é equivalente a `len(list)` em um objeto lista.

Py_ssize_t PyList_GET_SIZE(PyObject *list)
  Thread safety: Atomic.

  Similar a `PyList_Size()`, mas sem verificação de erro.

PyObject *PyList_GetItemRef(PyObject *list, Py_ssize_t index)
  Retorna valor: Nova referência. Parte da ABI Estável desde a versão 3.13. Thread safety: Atomic.

  Retorna o objeto na posição index na lista apontada por list. A posição deve ser não negativa; não há suporte à indexação do final da lista. Se index estiver fora dos limites (`<0 or >=len(list)`), retorna `NULL` e levanta uma exceção `IndexError`.

  Adicionado na versão 3.13.

PyObject *PyList_GetItem(PyObject *list, Py_ssize_t index)
  Retorna valor: Referência emprestada. Parte da ABI Estável. Thread safety: Safe to call from multiple threads with external synchronization only.

  Como `PyList_GetItemRef()`, mas retorna uma referência emprestada em vez de uma referência forte.

  Nota

  In the free-threaded build, the returned borrowed reference may become invalid if another thread modifies the list concurrently. Prefer `PyList_GetItemRef()`, which returns a strong reference.

PyObject *PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
  Retorna valor: Referência emprestada. Thread safety: Safe to call from multiple threads with external synchronization only.

  Similar a `PyList_GetItem()`, mas sem verificação de erro.

  Nota

  In the free-threaded build, the returned borrowed reference may become invalid if another thread modifies the list concurrently. Prefer `PyList_GetItemRef()`, which returns a strong reference.

int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
  Parte da ABI Estável. Thread safety: Atomic.

  Define o item no índice index na lista como item. Retorna `0` em caso de sucesso. Se index estiver fora dos limites, retorna `-1` e levanta uma exceção `IndexError`.

  Nota

  Esta função “rouba” uma referência para o item e descarta uma referência para um item já presente na lista na posição afetada.

void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
  Thread safety: Safe to call from multiple threads with external synchronization only.

  Forma macro de `PyList_SetItem()` sem verificação de erro. Este é normalmente usado apenas para preencher novas listas onde não há conteúdo anterior.

  A verificação de limites é realizada como uma asserção se o Python for construído em modo de depuração ou `com asserções`.

  Nota

  Esta macro “rouba” uma referência para o item e, ao contrário de `PyList_SetItem()`, não descarta uma referência para nenhum item que esteja sendo substituído; qualquer referência em list será perdida.

  Nota

  In the free-threaded build, this macro has no internal synchronization. It is normally only used to fill in new lists where no other thread has a reference to the list. If the list may be shared, use `PyList_SetItem()` instead, which uses a per-object lock.

int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
  Parte da ABI Estável. Thread safety: Safe for concurrent use on the same object.

  Insere o item item na lista list na frente do índice index. Retorna `0` se for bem-sucedido; retorna `-1` e levanta uma exceção se malsucedido. Análogo a `list.insert(index, item)`.

int PyList_Append(PyObject *list, PyObject *item)
  Parte da ABI Estável. Thread safety: Atomic.

  Adiciona o item item ao final da lista list. Retorna `0` se for bem-sucedido; retorna `-1` e levanta uma exceção se malsucedido. Análogo a `list.insert(index, item)`.

PyObject *PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
  Retorna valor: Nova referência. Parte da ABI Estável. Thread safety: Atomic.

  Retorna uma lista dos objetos em list contendo os objetos entre low e alto. Retorne `NULL` e levanta uma exceção se malsucedido. Análogo a `list[low:high]`. Não há suporte à indexação do final da lista.

int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
  Parte da ABI Estável. Thread safety: Safe for concurrent use on the same object.

  Define a fatia de list entre low e high para o conteúdo de itemlist. Análogo a `list[low:high] = itemlist`. itemlist pode ser `NULL`, indicando a atribuição de uma lista vazia (exclusão de fatia). Retorna `0` em caso de sucesso, `-1` em caso de falha. Não há suporte à indexação do final da lista.

  Nota

  In the free-threaded build, when itemlist is a `list`, both list and itemlist are locked for the duration of the operation. For other iterables (or `NULL`), only list is locked.

int PyList_Extend(PyObject *list, PyObject *iterable)
  Thread safety: Safe for concurrent use on the same object.

  Estende list com o conteúdo de iterable. Isto é o mesmo que `PyList_SetSlice(list, PY_SSIZE_T_MAX, PY_SSIZE_T_MAX, iterable)` e análogo a `list.extend(iterable)` ou `list += iterable`.

  Levanta uma exceção e retorna `-1` se list não for um objeto `list`. Retorna 0 em caso de sucesso.

  Adicionado na versão 3.13.

  Nota

  In the free-threaded build, when iterable is a `list`, `set`, `dict`, or dict view, both list and iterable (or its underlying dict) are locked for the duration of the operation. For other iterables, only list is locked; iterable may be concurrently modified by another thread.

int PyList_Clear(PyObject *list)
  Thread safety: Atomic.

  Remove todos os itens da lista. Isto é o mesmo que `PyList_SetSlice(list, 0, PY_SSIZE_T_MAX, NULL)` e análogo a `list.clear()` ou `del list[:]`.

  Levanta uma exceção e retorna `-1` se list não for um objeto `list`. Retorna 0 em caso de sucesso.

  Adicionado na versão 3.13.

int PyList_Sort(PyObject *list)
  Parte da ABI Estável. Thread safety: Safe for concurrent use on the same object.

  Ordena os itens de list no mesmo lugar. Retorna `0` em caso de sucesso, e `-1` em caso de falha. Isso é o equivalente de `list.sort()`.

  Nota

  In the free-threaded build, element comparison via `__lt__()` can execute arbitrary Python code, during which the per-object lock may be temporarily released. For built-in types (`str`, `int`, `float`), the lock is not released during comparison.

int PyList_Reverse(PyObject *list)
  Parte da ABI Estável. Thread safety: Safe for concurrent use on the same object.

  Inverte os itens de list no mesmo lugar. Retorna `0` em caso de sucesso, e `-1` em caso de falha. Isso é o equivalente de `list.reverse()`.

PyObject *PyList_AsTuple(PyObject *list)
  Retorna valor: Nova referência. Parte da ABI Estável. Thread safety: Atomic.

  Retorna um novo objeto tupla contendo os conteúdos de list; equivale a `tuple(list)`.