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

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

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

   Retorna 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()".

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.

   Novo na versão 3.4.

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);
      }

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
