Objetos dicionários¶

type PyDictObject¶: Este subtipo do PyObject representa um objeto dicionário Python.

PyTypeObject PyDict_Type¶: Parte da ABI Estável.
Esta instância do PyTypeObject representa o tipo do dicionário Python. Este é o mesmo objeto dict na camada do Python.

int PyDict_Check(PyObject *p)¶: Retorna verdadeiro se p é um objeto dicionário ou uma instância de um subtipo do tipo dicionário. Esta função sempre tem sucesso.

int PyDict_CheckExact(PyObject *p)¶: Retorna verdadeiro se p é um objeto dicionário, mas não uma instância de um subtipo do tipo dicionário. Esta função sempre tem sucesso.

PyObject *PyDict_New()¶: Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um novo dicionário vazio ou NULL em caso de falha.

PyObject *PyDictProxy_New(PyObject *mapping)¶: Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um objeto types.MappingProxyType para um mapeamento que reforça o comportamento somente leitura. Isso normalmente é usado para criar uma visão para evitar a modificação do dicionário para tipos de classes não dinâmicas.

void PyDict_Clear(PyObject *p)¶: Parte da ABI Estável.
Esvazia um dicionário existente de todos os pares chave-valor.

int PyDict_Contains(PyObject *p, PyObject *key)¶: Parte da ABI Estável.
Determina se o dicionário p contém key. Se um item em p corresponder à key, retorna 1, caso contrário, retorna 0. Em caso de erro, retorna -1. Isso é equivalente à expressão Python key in p.

int PyDict_ContainsString(PyObject *p, const char *key)¶: É o mesmo que PyDict_Contains(), mas key é especificada como uma string de bytes const char* codificada em UTF-8, em vez de um PyObject*.

Adicionado na versão 3.13.

PyObject *PyDict_Copy(PyObject *p)¶: Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um novo dicionário que contém o mesmo chave-valor como p.

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)¶: Parte da ABI Estável.
Insere val no dicionário p com a tecla key. key deve ser hasheável; se não for, TypeError será levantada. Retorna 0 em caso de sucesso ou -1 em caso de falha. Esta função não rouba uma referência a val.

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)¶: Parte da ABI Estável.
É o mesmo que PyDict_SetItem(), mas key é especificada como uma string de bytes const char* codificada em UTF-8, em vez de um PyObject*.

int PyDict_DelItem(PyObject *p, PyObject *key)¶: Parte da ABI Estável.
Remove a entrada no dicionário p com a chave key. key deve ser hasheável; se não for, TypeError é levantada. Se key não estiver no dicionário, KeyError é levantada. Retorna 0 em caso de sucesso ou -1 em caso de falha.

int PyDict_DelItemString(PyObject *p, const char *key)¶: Parte da ABI Estável.
É o mesmo que PyDict_DelItem(), mas key é especificada como uma string de bytes const char* codificada em UTF-8, em vez de um PyObject*.

int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)¶

Parte da ABI Estável desde a versão 3.13.

Retorna uma nova referência forte para o objeto dicionário p que possui uma chave key:

Se a chave estiver presente, define *result como uma nova referência forte para o valor e retorna 1.
Se a chave estiver ausente, define *result como NULL e retorna 0.
Em caso de erro, levanta uma exceção e retorna -1.

Adicionado na versão 3.13.

Veja também a função PyObject_GetItem().

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)¶: Retorna valor: Referência emprestada. Parte da ABI Estável.
Retorna um referência emprestada para o objeto do dicionário p que possui uma chave key. Retorna NULL se a chave key não estiver presente, mas sem definir uma exceção.

Nota

Exceções que ocorrem ao chamar os métodos __hash__() e __eq__() são ignoradas silenciosamente. Ao invés disso, use a função PyDict_GetItemWithError().

Alterado na versão 3.10: Chamar esta API sem um estado de thread anexado era permitido por motivos históricos. Não é mais permitido.

PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)¶: Retorna valor: Referência emprestada. Parte da ABI Estável.
Variante de PyDict_GetItem() que não suprime exceções. Retorna NULL com uma exceção definida se uma exceção ocorreu. Retorna NULL ** sem ** uma exceção definida se a chave não estiver presente.

PyObject *PyDict_GetItemString(PyObject *p, const char *key)¶: Retorna valor: Referência emprestada. Parte da ABI Estável.
É o mesmo que PyDict_GetItem(), mas key é especificada como uma string de bytes const char* codificada em UTF-8, em vez de um PyObject*.

Nota

Exceções que ocorrem ao chamar os métodos __hash__() e __eq__() ou ao criar objetos temporários da classe str são ignoradas silenciosamente. Ao invés disso, prefira usar a função PyDict_GetItemWithError() com sua própria key de PyUnicode_FromString().

int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)¶: Parte da ABI Estável desde a versão 3.13.
Similar a PyDict_GetItemRef(), mas key é especificada como uma string de bytes const char* codificada em UTF-8, em vez de um PyObject*.

Adicionado na versão 3.13.

PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)¶: Retorna valor: Referência emprestada.
Isso é o mesmo que o dict.setdefault() de nível Python. Se presente, ele retorna o valor correspondente a key do dicionário p. Se a chave não estiver no dict, ela será inserida com o valor defaultobj e defaultobj será retornado. Esta função avalia a função hash de key apenas uma vez, em vez de avaliá-la independentemente para a pesquisa e a inserção.

Adicionado na versão 3.4.

int PyDict_SetDefaultRef(PyObject *p, PyObject *key, PyObject *default_value, PyObject **result)¶

Insere default_value no dicionário p com uma chave key se a chave ainda não estiver presente no dicionário. Se result não for NULL, então *result é definido como uma referência forte para default_value, se a chave não estiver presente, ou para o valor existente, se key já estava presente no dicionário. Retorna 1 se a chave estava presente e default_value não foi inserido, ou 0 se a chave não estava presente e default_value foi inserido. Em caso de falha, retorna -1, define uma exceção e define *result como NULL.

Para maior clareza: se você tiver uma referência forte para default_value antes de chamar esta função, então depois que ela retornar, você terá uma referência forte para default_value e *result (se não for NULL). Estes podem referir-se ao mesmo objeto: nesse caso você mantém duas referências separadas para ele.

Adicionado na versão 3.13.

int PyDict_Pop(PyObject *p, PyObject *key, PyObject **result)¶

Remove key do dicionário p e, opcionalmente, retorna o valor removido. Não levanta KeyError se a chave estiver ausente.

Se a chave estiver presente, define *result como uma nova referência para o valor se result não for NULL e retorna 1.
Se a chave estiver ausente, define *result como NULL se result não for NULL e retorna 0.
Em caso de erro, levanta uma exceção e retorna -1.

Similar a dict.pop(), mas sem o valor padrão e sem levantar KeyError se a chave estiver ausente.

Adicionado na versão 3.13.

int PyDict_PopString(PyObject *p, const char *key, PyObject **result)¶: Similar a PyDict_Pop(), mas key é especificada como uma string de bytes const char* codificada em UTF-8, em vez de um PyObject*.

Adicionado na versão 3.13.

PyObject *PyDict_Items(PyObject *p)¶: Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um PyListObject contendo todos os itens do dicionário.

PyObject *PyDict_Keys(PyObject *p)¶: Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um PyListObject contendo todas as chaves do dicionário.

PyObject *PyDict_Values(PyObject *p)¶: Retorna valor: Nova referência. Parte da ABI Estável.
Retorna um PyListObject contendo todos os valores do dicionário p.

Py_ssize_t PyDict_Size(PyObject *p)¶: Parte da ABI Estável.
Retorna o número de itens no dicionário. Isso é equivalente a len(p) em um dicionário.

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)¶

Parte da ABI Estável.

Itera todos os pares de valores-chave no dicionário p. O Py_ssize_t referido por ppos deve ser inicializado para 0 antes da primeira chamada para esta função para iniciar a iteração; a função retorna true para cada par no dicionário e false quando todos os pares forem relatados. Os parâmetros pkey e pvalue devem apontar para variáveis de PyObject* que serão preenchidas com cada chave e valor, respectivamente, ou podem ser NULL. Todas as referências retornadas por meio deles são emprestadas. ppos não deve ser alterado durante a iteração. Seu valor representa deslocamentos dentro da estrutura do dicionário interno e, como a estrutura é esparsa, os deslocamentos não são consecutivos.

Por exemplo:

PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    /* fazer algo de interessante com os valores... */
    ...
}

O dicionário p não deve sofrer mutação durante a iteração. É seguro modificar os valores das chaves à medida que você itera no dicionário, mas apenas enquanto o conjunto de chaves não mudar. Por exemplo:

PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    long i = PyLong_AsLong(value);
    if (i == -1 && PyErr_Occurred()) {
        return -1;
    }
    PyObject *o = PyLong_FromLong(i + 1);
    if (o == NULL)
        return -1;
    if (PyDict_SetItem(self->dict, key, o) < 0) {
        Py_DECREF(o);
        return -1;
    }
    Py_DECREF(o);
}

A função não é segura para thread na construção com threads livres sem sincronização externa. Você pode usar Py_BEGIN_CRITICAL_SECTION para travar o dicionário enquanto itera sobre ele:

Py_BEGIN_CRITICAL_SECTION(self->dict);
while (PyDict_Next(self->dict, &pos, &key, &value)) {
    ...
}
Py_END_CRITICAL_SECTION();

Nota

On the free-threaded build, this function can be used safely inside a critical section. However, the references returned for pkey and pvalue are borrowed and are only valid while the critical section is held. If you need to use these objects outside the critical section or when the critical section can be suspended, create a strong reference (for example, using Py_NewRef()).

int PyDict_Merge(PyObject *a, PyObject *b, int override)¶: Parte da ABI Estável.
Itera sobre o objeto de mapeamento b adicionando pares de valores-chave ao dicionário a. b pode ser um dicionário, ou qualquer objeto que suporte PyMapping_Keys() e PyObject_GetItem(). Se override for verdadeiro, os pares existentes em a serão substituídos se uma chave correspondente for encontrada em b, caso contrário, os pares serão adicionados apenas se não houver uma chave correspondente em a. Retorna 0 em caso de sucesso ou -1 se uma exceção foi levantada.

int PyDict_Update(PyObject *a, PyObject *b)¶: Parte da ABI Estável.
É o mesmo que PyDict_Merge(a, b, 1) em C, e é semelhante a a.update(b) em Python, exceto que PyDict_Update() não cai na iteração em uma sequência de pares de valores de chave se o segundo argumento não tiver o atributo “keys”. Retorna 0 em caso de sucesso ou -1 se uma exceção foi levantada.

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)¶

Parte da ABI Estável.

Atualiza ou mescla no dicionário a, a partir dos pares de chave-valor em seq2. seq2 deve ser um objeto iterável produzindo objetos iteráveis de comprimento 2, vistos como pares chave-valor. No caso de chaves duplicadas, a última vence se override for verdadeiro, caso contrário, a primeira vence. Retorne 0 em caso de sucesso ou -1 se uma exceção foi levantada. Python equivalente (exceto para o valor de retorno):

def PyDict_MergeFromSeq2(a, seq2, override):
    for key, value in seq2:
        if override or key not in a:
            a[key] = value

int PyDict_AddWatcher(PyDict_WatchCallback callback)¶: Registra callback como um observador de dicionário. Retorna um ID inteiro não negativo que deve ser passado para futuras chamadas a PyDict_Watch(). Em caso de erro (por exemplo, não há mais IDs de observador disponíveis), retorna -1 e define uma exceção.

Adicionado na versão 3.12.

int PyDict_ClearWatcher(int watcher_id)¶: Limpa o observador identificado por watcher_id retornado anteriormente de PyDict_AddWatcher(). Retorna 0 em caso de sucesso, -1 em caso de erro (por exemplo, se o watcher_id fornecido nunca foi registrado).

Adicionado na versão 3.12.

int PyDict_Watch(int watcher_id, PyObject *dict)¶: Marca o dicionário dict como observado. A função de retorno concedida a watcher_id por PyDict_AddWatcher() será chamada quando dict for modificado ou desalocado. Retorna 0 em caso de sucesso ou -1 em caso de erro.

Adicionado na versão 3.12.

int PyDict_Unwatch(int watcher_id, PyObject *dict)¶: Marca o dicionário dict como não mais observado. A função de retorno concedida a watcher_id por PyDict_AddWatcher() será chamada quando dict for modificado ou desalocado. O dicionário deve ter sido observado anteriormente por este observador. Retorna 0 em caso de sucesso ou -1 em caso de erro.

Adicionado na versão 3.12.

type PyDict_WatchEvent¶: Enumeração de possíveis eventos de observador de dicionário: PyDict_EVENT_ADDED, PyDict_EVENT_MODIFIED, PyDict_EVENT_DELETED, PyDict_EVENT_CLONED, PyDict_EVENT_CLEARED ou PyDict_EVENT_DEALLOCATED.

Adicionado na versão 3.12.

typedef int (*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject *dict, PyObject *key, PyObject *new_value)¶

Tipo de uma função de retorno de chamada de observador de dicionário.

Se event for PyDict_EVENT_CLEARED ou PyDict_EVENT_DEALLOCATED, tanto key quanto new_value serão NULL. Se event for PyDict_EVENT_ADDED ou PyDict_EVENT_MODIFIED, new_value será o novo valor de key. Se event for PyDict_EVENT_DELETED, key estará sendo excluída do dicionário e new_value será NULL.

PyDict_EVENT_CLONED ocorre quando dict estava anteriormente vazio e outro dict é mesclado a ele. Para manter a eficiência dessa operação, os eventos PyDict_EVENT_ADDED por chave não são emitidos nesse caso; em vez disso, um único PyDict_EVENT_CLONED é emitido e key será o dicionário de origem.

A função de retorno pode inspecionar, mas não deve modificar o dict; isso pode ter efeitos imprevisíveis, inclusive recursão infinita. Não acione a execução do código Python na função de retorno, pois isso poderia modificar o dict como um efeito colateral.

Se event for PyDict_EVENT_DEALLOCATED, a obtenção de uma nova referência na função de retorno para o dicionário prestes a ser destruído o ressuscitará e impedirá que ele seja liberado nesse momento. Quando o objeto ressuscitado for destruído mais tarde, quaisquer funções de retorno do observador ativos naquele momento serão chamados novamente.

As funções de retorno ocorrem antes que a modificação notificada no dict ocorra, de modo que o estado anterior do dict possa ser inspecionado.

Se a função de retorno definir uma exceção, ela deverá retornar -1; essa exceção será impressa como uma exceção não reprovável usando PyErr_WriteUnraisable(). Caso contrário, deverá retornar 0.

É possível que já exista uma exceção pendente definida na entrada da função de retorno. Nesse caso, a função de retorno deve retornar 0 com a mesma exceção ainda definida. Isso significa que a função de retorno não pode chamar nenhuma outra API que possa definir uma exceção, a menos que salve e limpe o estado da exceção primeiro e o restaure antes de retornar.

Adicionado na versão 3.12.

Objetos dicionários¶

Tópico anterior

Próximo tópico

Esta página