Objetos dicionários¶
-
PyTypeObject PyDict_Type¶
- Parte da ABI Estável.
Esta instância do
PyTypeObject
representa o tipo do dicionário Python. Este é o mesmo objetodict
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, retorna0
. Em caso de erro, retorna-1
. Isso é equivalente à expressão Pythonkey 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. Retorna0
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. Retorna0
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 retorna0
.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çãoPyDict_GetItemWithError()
.Alterado na versão 3.10: Chamar esta API sem GIL retida 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. RetornaNULL
com uma exceção definida se uma exceção ocorreu. RetornaNULL
** 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 classestr
são ignoradas silenciosamente. Ao invés disso, prefira usar a funçãoPyDict_GetItemWithError()
com sua própria key dePyUnicode_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. Retorna1
se a chave estava presente e default_value não foi inserido, ou0
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
comoNULL
.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 retorna1
.Se a chave estiver ausente, define *result como
NULL
se result não forNULL
e retorna0
.Em caso de erro, levanta uma exceção e retorna
-1
.
Isto é semelhante a
dict.pop()
, mas sem o valor padrão e sem levantarKeyError
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 para0
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 serNULL
. 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)) { /* do something interesting with the values... */ ... }
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();
-
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()
ePyObject_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. Retorna0
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 aa.update(b)
em Python, exceto quePyDict_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”. Retorna0
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()
. Retorna0
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. Retorna0
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. Retorna0
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
ouPyDict_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
ouPyDict_EVENT_DEALLOCATED
, tanto key quanto new_value serãoNULL
. Se event forPyDict_EVENT_ADDED
ouPyDict_EVENT_MODIFIED
, new_value será o novo valor de key. Se event forPyDict_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 eventosPyDict_EVENT_ADDED
por chave não são emitidos nesse caso; em vez disso, um únicoPyDict_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 usandoPyErr_WriteUnraisable()
. Caso contrário, deverá retornar0
.É 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.