Objetos dicionários
*******************

PyDictObject

   Este subtipo do "PyObject" representa um objeto dicionário Python.

PyTypeObject PyDict_Type

   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 dict ou uma instância de um
   subtipo do tipo dict.

int PyDict_CheckExact(PyObject *p)

   Retorna verdadeiro se *p* for um objeto dict, mas não uma instância
   de um subtipo do tipo dict.

PyObject* PyDict_New()
    *Return value: New reference.*

   Retorna um novo dicionário vazio ou "NULL" em caso de falha.

PyObject* PyDictProxy_New(PyObject *mapping)
    *Return value: New reference.*

   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)

   Esvazia um dicionário existente de todos os pares chave-valor.

int PyDict_Contains(PyObject *p, PyObject *key)

   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)
    *Return value: New reference.*

   Retorna um novo dicionário que contém o mesmo chave-valor como *p*.

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)

   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)

   Insert *val* into the dictionary *p* using *key* as a key. *key*
   should be a "const char*".  The key object is created using
   "PyUnicode_FromString(key)".  Return "0" on success or "-1" on
   failure.  This function *does not* steal a reference to *val*.

int PyDict_DelItem(PyObject *p, PyObject *key)

   Remove the entry in dictionary *p* with key *key*. *key* must be
   hashable; if it isn't, "TypeError" is raised. If *key* is not in
   the dictionary, "KeyError" is raised. Return "0" on success or "-1"
   on failure.

int PyDict_DelItemString(PyObject *p, const char *key)

   Remove the entry in dictionary *p* which has a key specified by the
   string *key*. If *key* is not in the dictionary, "KeyError" is
   raised. Return "0" on success or "-1" on failure.

PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
    *Return value: Borrowed reference.*

   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.

   Observe que as exceções que ocorrem ao chamar os métodos
   "__hash__()" e "__eq__()" serão suprimidas. Para obter o relatório
   de erros, use "PyDict_GetItemWithError()".

PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
    *Return value: Borrowed reference.*

   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)
    *Return value: Borrowed reference.*

   This is the same as "PyDict_GetItem()", but *key* is specified as a
   "const char*", rather than a "PyObject*".

   Observe que as exceções que ocorrem ao chamar os métodos
   "__hash__()" e "__eq__()" e criar um objeto string temporário serão
   suprimidas. Para obter o relatório de erros, use
   "PyDict_GetItemWithError()".

PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)
    *Return value: Borrowed reference.*

   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)
    *Return value: New reference.*

   Retorna um "PyListObject" contendo todos os itens do dicionário.

PyObject* PyDict_Keys(PyObject *p)
    *Return value: New reference.*

   Retorna um "PyListObject" contendo todas as chaves do dicionário.

PyObject* PyDict_Values(PyObject *p)
    *Return value: New reference.*

   Retorna um "PyListObject" contendo todos os valores do dicionário
   *p*.

Py_ssize_t PyDict_Size(PyObject *p)

   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)

   Iterate over all key-value pairs in the dictionary *p*.  The
   "Py_ssize_t" referred to by *ppos* must be initialized to "0" prior
   to the first call to this function to start the iteration; the
   function returns true for each pair in the dictionary, and false
   once all pairs have been reported.  The parameters *pkey* and
   *pvalue* should either point to "PyObject*" variables that will be
   filled in with each key and value, respectively, or may be "NULL".
   Any references returned through them are borrowed.  *ppos* should
   not be altered during iteration. Its value represents offsets
   within the internal dictionary structure, and since the structure
   is sparse, the offsets are not consecutive.

   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)

   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)

   É 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)

   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_ClearFreeList()

   Limpe a lista livre. Retorna o número total de itens liberados.

   Novo na versão 3.3.
