# 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.

  Return a new tuple object of size len, or `NULL` with an exception set on failure.

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

  Return a new tuple object of size n, or `NULL` with an exception set on failure. The tuple values are initialized to the subsequent n C arguments pointing to Python objects. `PyTuple_Pack(2, a, b)` is equivalent to `Py_BuildValue("(OO)", a, b)`.

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

  Take a pointer to a tuple object, and return the size of that tuple. On error, return `-1` and with an exception set.

Py_ssize_t PyTuple_GET_SIZE( PyObject *p)

  Like `PyTuple_Size()`, but without error checking.

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` with an exception set 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.

  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 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 presumir 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()`.

  Return `NULL` with an exception set on failure.

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)

  Like `PyStructSequence_InitType()`, but returns `0` on success and `-1` with an exception set on failure.

  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

    Fully qualified name of the type; null-terminated UTF-8 encoded. The name must contain the module name.

  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()`.

  Return `NULL` with an exception set on failure.

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

  Return the object at position pos in the struct sequence pointed to by p.

  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`.

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

  Alias to `PyStructSequence_GetItem()`.

  Alterado na versão 3.13: Now implemented as an alias to `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.

  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 função “rouba” uma referência a o.

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

  Alias to `PyStructSequence_SetItem()`.

  Alterado na versão 3.13: Now implemented as an alias to `PyStructSequence_SetItem()`.