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

  Isto é semelhante 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)) {
          /* 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()` 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.