Trait PyDictMethods

pub trait PyDictMethods<'py>: Sealed {
    // Required methods
    fn copy(&self) -> PyResult<Bound<'py, PyDict>>;
    fn clear(&self);
    fn len(&self) -> usize;
    fn is_empty(&self) -> bool;
    fn contains<K>(&self, key: K) -> PyResult<bool>
       where K: IntoPyObject<'py>;
    fn get_item<K>(&self, key: K) -> PyResult<Option<Bound<'py, PyAny>>>
       where K: IntoPyObject<'py>;
    fn set_item<K, V>(&self, key: K, value: V) -> PyResult<()>
       where K: IntoPyObject<'py>,
             V: IntoPyObject<'py>;
    fn del_item<K>(&self, key: K) -> PyResult<()>
       where K: IntoPyObject<'py>;
    fn keys(&self) -> Bound<'py, PyList>;
    fn values(&self) -> Bound<'py, PyList>;
    fn items(&self) -> Bound<'py, PyList>;
    fn iter(&self) -> BoundDictIterator<'py> ;
    fn locked_for_each<F>(&self, closure: F) -> PyResult<()>
       where F: Fn(Bound<'py, PyAny>, Bound<'py, PyAny>) -> PyResult<()>;
    fn as_mapping(&self) -> &Bound<'py, PyMapping>;
    fn into_mapping(self) -> Bound<'py, PyMapping>;
    fn update(&self, other: &Bound<'_, PyMapping>) -> PyResult<()>;
    fn update_if_missing(&self, other: &Bound<'_, PyMapping>) -> PyResult<()>;
}

Implementation of functionality for PyDict.

These methods are defined for the Bound<'py, PyDict> smart pointer, so to use method call syntax these methods are separated into a trait, because stable Rust does not yet support arbitrary_self_types.

Required Methods

fn copy(&self) -> PyResult<Bound<'py, PyDict>>

Returns a new dictionary that contains the same key-value pairs as self.

This is equivalent to the Python expression self.copy().

fn clear(&self)

Empties an existing dictionary of all key-value pairs.

fn len(&self) -> usize

Return the number of items in the dictionary.

This is equivalent to the Python expression len(self).

fn is_empty(&self) -> bool

Checks if the dict is empty, i.e. len(self) == 0.

fn contains<K>(&self, key: K) -> PyResult<bool>

where K: IntoPyObject<'py>,

Determines if the dictionary contains the specified key.

This is equivalent to the Python expression key in self.

fn get_item<K>(&self, key: K) -> PyResult<Option<Bound<'py, PyAny>>>

where K: IntoPyObject<'py>,

Gets an item from the dictionary.

Returns None if the item is not present, or if an error occurs.

To get a KeyError for non-existing keys, use PyAny::get_item.

fn set_item<K, V>(&self, key: K, value: V) -> PyResult<()>

where K: IntoPyObject<'py>, V: IntoPyObject<'py>,

Sets an item value.

This is equivalent to the Python statement self[key] = value.

fn del_item<K>(&self, key: K) -> PyResult<()>

where K: IntoPyObject<'py>,

Deletes an item.

This is equivalent to the Python statement del self[key].

fn keys(&self) -> Bound<'py, PyList>

Returns a list of dict keys.

This is equivalent to the Python expression list(dict.keys()).

fn values(&self) -> Bound<'py, PyList>

Returns a list of dict values.

This is equivalent to the Python expression list(dict.values()).

fn items(&self) -> Bound<'py, PyList>

Returns a list of dict items.

This is equivalent to the Python expression list(dict.items()).

fn iter(&self) -> BoundDictIterator<'py>

Returns an iterator of (key, value) pairs in this dictionary.

Panics

If PyO3 detects that the dictionary is mutated during iteration, it will panic. It is allowed to modify values as you iterate over the dictionary, but only so long as the set of keys does not change.

fn locked_for_each<F>(&self, closure: F) -> PyResult<()>

where F: Fn(Bound<'py, PyAny>, Bound<'py, PyAny>) -> PyResult<()>,

Iterates over the contents of this dictionary while holding a critical section on the dict. This is useful when the GIL is disabled and the dictionary is shared between threads. It is not guaranteed that the dictionary will not be modified during iteration when the closure calls arbitrary Python code that releases the current critical section.

This method is a small performance optimization over .iter().try_for_each() when the nightly feature is not enabled because we cannot implement an optimised version of iter().try_fold() on stable yet. If your iteration is infallible then this method has the same performance as .iter().for_each().

fn as_mapping(&self) -> &Bound<'py, PyMapping>

Returns self cast as a PyMapping.

fn into_mapping(self) -> Bound<'py, PyMapping>

Returns self cast as a PyMapping.

fn update(&self, other: &Bound<'_, PyMapping>) -> PyResult<()>

Update this dictionary with the key/value pairs from another.

This is equivalent to the Python expression self.update(other). If other is a PyDict, you may want to use self.update(other.as_mapping()), note: PyDict::as_mapping is a zero-cost conversion.

fn update_if_missing(&self, other: &Bound<'_, PyMapping>) -> PyResult<()>

Add key/value pairs from another dictionary to this one only when they do not exist in this.

This is equivalent to the Python expression self.update({k: v for k, v in other.items() if k not in self}). If other is a PyDict, you may want to use self.update_if_missing(other.as_mapping()), note: PyDict::as_mapping is a zero-cost conversion.

This method uses PyDict_Merge internally, so should have the same performance as update.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<'py> PyDictMethods<'py> for Bound<'py, PyDict>