# Objeto tupla

type PyTupleObject

  Este subtipo de `PyObject` representa um objeto tupla em Python.

PyTypeObject PyTuple_Type
  Parte da ABI Estável.

  Esta instância de `PyTypeObject` representa o tipo tupla de Python; é o mesmo objeto que `tuple` na camada Python.

int PyTuple_Check(PyObject *p)

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

int PyTuple_CheckExact(PyObject *p)

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

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

  Retorna um novo objeto tupla de tamanho len, ou `NULL` em caso de falha.

PyObject *PyTuple_Pack(Py_ssize_t n, ...)
  Retorna valor: Nova referência. Parte da ABI Estável.

  Retorna um novo objeto tupla de tamanho n, ou `NULL` em caso de falha. Os valores da tupla são inicializados para os n argumentos C subsequentes apontando para objetos Python. ``PyTuple_Pack(2, a, b)` é equivalente a `Py_BuildValue("(OO)", a, b)`.

Py_ssize_t PyTuple_Size(PyObject *p)
  Parte da ABI Estável.

  Pega um ponteiro para um objeto tupla e retorna o tamanho dessa tupla.

Py_ssize_t PyTuple_GET_SIZE(PyObject *p)

  Retorna o tamanho da tupla p, que deve ser diferente de `NULL` e apontar para uma tupla; nenhuma verificação de erro é executada.

PyObject *PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
  Retorna valor: Referência emprestada. Parte da ABI Estável.

  Retorna o objeto na posição pos na tupla apontada por p. Se pos estiver fora dos limites, retorna `NULL` e define uma exceção `IndexError`.

  The returned reference is borrowed from the tuple p (that is: it is only valid as long as you hold a reference to p). To get a strong reference, use `Py_NewRef(PyTuple_GetItem(...))` or `PySequence_GetItem()`.

PyObject *PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
  Retorna valor: Referência emprestada.

  Como `PyTuple_GetItem()`, mas faz nenhuma verificação de seus argumentos.

PyObject *PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
  Retorna valor: Nova referência. Parte da ABI Estável.

  Return the slice of the tuple pointed to by p between low and high, or `NULL` on failure. This is the equivalent of the Python expression `p[low:high]`. Indexing from the end of the tuple is not supported.

int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
  Parte da ABI Estável.

  Insere uma referência ao objeto o na posição pos da tupla apontada por p. Retorna `0` em caso de sucesso. Se pos estiver fora dos limites, retorne `-1` e define uma exceção `IndexError`.

  Nota

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

void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)

  Como `PyTuple_SetItem()`, mas não verifica erros e deve apenas ser usado para preencher novas tuplas.

  Nota

  Esta função “rouba” uma referência para o e, ao contrário de `PyTuple_SetItem()`, não descarta uma referência para nenhum item que esteja sendo substituído; qualquer referência na tupla na posição pos será perdida.

int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)

  Pode ser usado para redimensionar uma tupla. newsize será o novo comprimento da tupla. Como as tuplas são supostamente imutáveis, isso só deve ser usado se houver apenas uma referência ao objeto. Não use isto se a tupla já for conhecida por alguma outra parte do código. A tupla sempre aumentará ou diminuirá no final. Pense nisso como destruir a tupla antiga e criar uma nova, mas com mais eficiência. Retorna `0` em caso de sucesso. O código do cliente nunca deve assumir que o valor resultante de `*p` será o mesmo de antes de chamar esta função. Se o objeto referenciado por `*p` for substituído, o `*p` original será destruído. Em caso de falha, retorna `-1` e define `*p` para `NULL`, e levanta `MemoryError` ou `SystemError`.

# Objetos sequência de estrutura

Objetos sequência de estrutura são o equivalente em C dos objetos `namedtuple()`, ou seja, uma sequência cujos itens também podem ser acessados por meio de atributos. Para criar uma sequência de estrutura, você primeiro precisa criar um tipo de sequência de estrutura específico.

PyTypeObject *PyStructSequence_NewType(PyStructSequence_Desc *desc)
  Retorna valor: Nova referência. Parte da ABI Estável.

  Cria um novo tipo de sequência de estrutura a partir dos dados em desc, descrito abaixo. Instâncias do tipo resultante podem ser criadas com `PyStructSequence_New()`.

void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)

  Inicializa um tipo de sequência de estrutura type de desc no lugar.

int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)

  O mesmo que `PyStructSequence_InitType`, mas retorna `0` em caso de sucesso e `-1` em caso de falha.

  Adicionado na versão 3.4.

type PyStructSequence_Desc
  Parte da ABI Estável (incluindo todos os membros).

  Contém as metainformações de um tipo de sequência de estrutura a ser criado.

  const char *name

    Name of the struct sequence type.

  const char *doc

    Pointer to docstring for the type or `NULL` to omit.

  PyStructSequence_Field *fields

    Pointer to `NULL`-terminated array with field names of the new type.

  int n_in_sequence

    Number of fields visible to the Python side (if used as tuple).

type PyStructSequence_Field
  Parte da ABI Estável (incluindo todos os membros).

  Describes a field of a struct sequence. As a struct sequence is modeled as a tuple, all fields are typed as PyObject*. The index in the `fields` array of the `PyStructSequence_Desc` determines which field of the struct sequence is described.

  const char *name

    Name for the field or `NULL` to end the list of named fields, set to `PyStructSequence_UnnamedField` to leave unnamed.

  const char *doc

    Field docstring or `NULL` to omit.

const char *const PyStructSequence_UnnamedField
  Parte da ABI Estável desde a versão 3.11.

  Valor especial para um nome de campo para deixá-lo sem nome.

  Alterado na versão 3.9: O tipo foi alterado de `char *`.

PyObject *PyStructSequence_New(PyTypeObject *type)
  Retorna valor: Nova referência. Parte da ABI Estável.

  Cria um instância de type, que deve ser criada com `PyStructSequence_NewType()`.

PyObject *PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
  Retorna valor: Referência emprestada. Parte da ABI Estável.

  Retorna o objeto na posição pos na sequência de estrutura apontada por p. Nenhuma verificação de limites é executada.

PyObject *PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)
  Retorna valor: Referência emprestada.

  Macro equivalente de `PyStructSequence_GetItem()`.

void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
  Parte da ABI Estável.

  Define o campo no índice pos da sequência de estrutura p para o valor o. Como `PyTuple_SET_ITEM()`, isto só deve ser usado para preencher novas instâncias.

  Nota

  Esta função “rouba” uma referência a o.

void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)

  Similar a `PyStructSequence_SetItem()`, mas implementada como uma função inline estática.

  Nota

  Esta função “rouba” uma referência a o.