View Source Pythonx.C.PyDict (Pythonx v0.2.3)

This subtype of PyObject represents a Python dictionary object.

Summary

Functions

Return true if p is a dict object or an instance of a subtype of the dict type.

Return true if p is a dict object, but not an instance of a subtype of the dict type.

Empty an existing dictionary of all key-value pairs.

Determine if dictionary p contains key. If an item in p is matches key, return true, otherwise return false.

Return a new dictionary that contains the same key-value pairs as p.

Remove the entry in dictionary p with key key.

This is the same as PyDict.del_item/2, but key is specified as a UTF-8 encoded binary string, rather than a PyObject*.

Return the object from dictionary p which has a key key.

This is the same as PyDict.get_item/2, but key is specified as a UTF-8 encoded binary string, rather than a PyObject*.

Variant of PyDict.get_item/2() that does not suppress exceptions.

Return a PyListObject containing all the items from the dictionary.

Return a PyListObject containing all the keys from the dictionary.

Iterate over mapping object b adding key-value pairs to dictionary a.

Update or merge into dictionary a, from the key-value pairs in seq2.

Return a new empty dictionary, or PyErr on failure.

This is the same as the Python-level dict.setdefault().

Insert val into the dictionary p with a key of key.

This is the same as PyDict.set_item/3, but key is specified as a UTF-8 encoded binary string, rather than a PyObject*.

Return the number of items in the dictionary.

This is the same as PyDict.merge(a, b, true), and is similar to a.update(b) in Python except that PyDict.update/2 doesn’t fall back to the iterating over a sequence of key value pairs if the second argument has no “keys” attribute.

Return a PyListObject containing all the values from the dictionary p.

Functions

@spec check(Pythonx.C.PyObject.t()) :: boolean()

Return true if p is a dict object or an instance of a subtype of the dict type.

This function always succeeds.

@spec check_exact(Pythonx.C.PyObject.t()) :: boolean()

Return true if p is a dict object, but not an instance of a subtype of the dict type.

This function always succeeds.

@spec clear(Pythonx.C.PyObject.t()) :: :ok

Empty an existing dictionary of all key-value pairs.

Determine if dictionary p contains key. If an item in p is matches key, return true, otherwise return false.

On error, return PyErr.t().

This is equivalent to the Python expression key in p.

Return a new dictionary that contains the same key-value pairs as p.

Return value: New reference.

Remove the entry in dictionary p with key key.

key must be hashable; if it isn’t, PyErr.t() with TypeError will be returned.

If key is not in the dictionary, PyErr.t() with KeyError will be returned.

Return true on success or PyErr.t() on failure.

@spec del_item_string(Pythonx.C.PyObject.t(), String.t()) :: :ok | Pythonx.C.PyErr.t()

This is the same as PyDict.del_item/2, but key is specified as a UTF-8 encoded binary string, rather than a PyObject*.

Return the object from dictionary p which has a key key.

Return nil if the key key is not present, but without setting an exception.

Note

Exceptions that occur while this calls __hash__() and __eq__() methods are silently ignored.

Prefer the PyDict.get_item_with_error function instead.

Warning

Changed in version 3.10:

Calling this API without GIL held had been allowed for historical reason. It is no longer allowed.

Return value: Borrowed reference

@spec get_item_string(Pythonx.C.PyObject.t(), String.t()) ::
  Pythonx.C.PyObject.borrowed() | nil

This is the same as PyDict.get_item/2, but key is specified as a UTF-8 encoded binary string, rather than a PyObject*.

Note

Exceptions that occur while this calls __hash__() and __eq__() methods or while creating the temporary str object are silently ignored.

Prefer using the PyDict.get_item_with_error/2 function with your own PyUnicode.from_string/1 key instead.

Link to this function

get_item_with_error(p, key)

View Source

Variant of PyDict.get_item/2() that does not suppress exceptions.

Return PyErr.t() with an exception set if an exception occurred.

Return nil without an exception set if the key wasn’t present.

Return value: Borrowed reference

Return a PyListObject containing all the items from the dictionary.

Return value: New reference.

Return a PyListObject containing all the keys from the dictionary.

Return value: New reference.

Iterate over mapping object b adding key-value pairs to dictionary a.

b may be a dictionary, or any object supporting PyMapping.keys/1 and PyObject.get_item/2.

If override is true, existing pairs in a will be replaced if a matching key is found in b, otherwise pairs will only be added if there is not a matching key in a.

Return :ok on success or PyErr.t() with an exception.

Link to this function

merge_from_seq2(a, seq2, override)

View Source
@spec merge_from_seq2(Pythonx.C.PyObject.t(), Pythonx.C.PyObject.t(), boolean()) ::
  :ok | Pythonx.C.PyErr.t()

Update or merge into dictionary a, from the key-value pairs in seq2.

seq2 must be an iterable object producing iterable objects of length 2, viewed as key-value pairs.

In case of duplicate keys, the last wins if override is true, else the first wins.

Return :ok on success or PyErr.t() with an exception.

Equivalent Python (except for the return value):

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

Return a new empty dictionary, or PyErr on failure.

Return value: New reference.

Link to this function

set_default(p, key, defaultobj)

View Source

This is the same as the Python-level dict.setdefault().

If present, it returns the value corresponding to key from the dictionary p.

If the key is not in the dict, it is inserted with value defaultobj and defaultobj is returned.

This function evaluates the hash function of key only once, instead of evaluating it independently for the lookup and the insertion.

Return value: Borrowed reference.

Insert val into the dictionary p with a key of key.

key must be hashable; if it isn’t, PyErr.t() with TypeError will be returned.

Return :ok on success or PyErr.t() on failure.

This function does not steal a reference to val.

Link to this function

set_item_string(p, key, val)

View Source
@spec set_item_string(Pythonx.C.PyObject.t(), String.t(), Pythonx.C.PyObject.t()) ::
  :ok | Pythonx.C.PyErr.t()

This is the same as PyDict.set_item/3, but key is specified as a UTF-8 encoded binary string, rather than a PyObject*.

@spec size(Pythonx.C.PyObject.t()) :: integer()

Return the number of items in the dictionary.

This is equivalent to len(p) on a dictionary.

This is the same as PyDict.merge(a, b, true), and is similar to a.update(b) in Python except that PyDict.update/2 doesn’t fall back to the iterating over a sequence of key value pairs if the second argument has no “keys” attribute.

Return :ok on success or PyErr.t() with an exception.

Return a PyListObject containing all the values from the dictionary p.

Return value: New reference.