Trait PyWeakrefMethods

pub trait PyWeakrefMethods<'py>: Sealed {
    // Required method
    fn upgrade(&self) -> Option<Bound<'py, PyAny>>;

    // Provided methods
    fn upgrade_as<T>(&self) -> PyResult<Option<Bound<'py, T>>>
       where T: PyTypeCheck { ... }
    unsafe fn upgrade_as_unchecked<T>(&self) -> Option<Bound<'py, T>> { ... }
    fn upgrade_as_exact<T>(&self) -> PyResult<Option<Bound<'py, T>>>
       where T: PyTypeInfo { ... }
    fn get_object(&self) -> Bound<'py, PyAny> { ... }
}

Implementation of functionality for PyWeakref.

These methods are defined for the Bound<'py, PyWeakref> 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 upgrade(&self) -> Option<Bound<'py, PyAny>>

Upgrade the weakref to a Bound PyAny reference to the target object if possible.

It is named upgrade to be inline with rust’s Weak::upgrade. This function returns Some(Bound<'py, PyAny>) if the reference still exists, otherwise None will be returned.

This function gets the optional target of this weakref.ReferenceType (result of calling weakref.ref). It produces similar results to using PyWeakref_GetRef in the C api.

Example

use pyo3::prelude::*;
use pyo3::types::PyWeakrefReference;

#[pyclass(weakref)]
struct Foo { /* fields omitted */ }

fn parse_data(reference: Borrowed<'_, '_, PyWeakrefReference>) -> PyResult<String> {
    if let Some(object) = reference.upgrade() {
        Ok(format!("The object '{}' refered by this reference still exists.", object.getattr("__class__")?.getattr("__qualname__")?))
    } else {
        Ok("The object, which this reference refered to, no longer exists".to_owned())
    }
}

Python::with_gil(|py| {
    let data = Bound::new(py, Foo{})?;
    let reference = PyWeakrefReference::new(&data)?;

    assert_eq!(
        parse_data(reference.as_borrowed())?,
        "The object 'Foo' refered by this reference still exists."
    );

    drop(data);

    assert_eq!(
        parse_data(reference.as_borrowed())?,
        "The object, which this reference refered to, no longer exists"
    );

    Ok(())
})

Panics

This function panics is the current object is invalid. If used properly this is never the case. (NonNull and actually a weakref type)

Provided Methods

fn upgrade_as<T>(&self) -> PyResult<Option<Bound<'py, T>>>

where T: PyTypeCheck,

Upgrade the weakref to a direct Bound object reference.

It is named upgrade to be inline with rust’s Weak::upgrade. In Python it would be equivalent to PyWeakref_GetRef.

Example

use pyo3::prelude::*;
use pyo3::types::PyWeakrefReference;

#[pyclass(weakref)]
struct Foo { /* fields omitted */ }

#[pymethods]
impl Foo {
    fn get_data(&self) -> (&str, u32) {
        ("Dave", 10)
    }
}

fn parse_data(reference: Borrowed<'_, '_, PyWeakrefReference>) -> PyResult<String> {
    if let Some(data_src) = reference.upgrade_as::<Foo>()? {
        let data = data_src.borrow();
        let (name, score) = data.get_data();
        Ok(format!("Processing '{}': score = {}", name, score))
    } else {
        Ok("The supplied data reference is nolonger relavent.".to_owned())
    }
}

Python::with_gil(|py| {
    let data = Bound::new(py, Foo{})?;
    let reference = PyWeakrefReference::new(&data)?;

    assert_eq!(
        parse_data(reference.as_borrowed())?,
        "Processing 'Dave': score = 10"
    );

    drop(data);

    assert_eq!(
        parse_data(reference.as_borrowed())?,
        "The supplied data reference is nolonger relavent."
    );

    Ok(())
})

Panics

This function panics is the current object is invalid. If used propperly this is never the case. (NonNull and actually a weakref type)

unsafe fn upgrade_as_unchecked<T>(&self) -> Option<Bound<'py, T>>

Upgrade the weakref to a direct Bound object reference unchecked. The type of the recovered object is not checked before downcasting, this could lead to unexpected behavior. Use only when absolutely certain the type can be guaranteed. The weakref may still return None.

It is named upgrade to be inline with rust’s Weak::upgrade. In Python it would be equivalent to PyWeakref_GetRef.

Safety

Callers must ensure that the type is valid or risk type confusion. The weakref is still allowed to be None, if the referenced object has been cleaned up.

Example

use pyo3::prelude::*;
use pyo3::types::PyWeakrefReference;

#[pyclass(weakref)]
struct Foo { /* fields omitted */ }

#[pymethods]
impl Foo {
    fn get_data(&self) -> (&str, u32) {
        ("Dave", 10)
    }
}

fn parse_data(reference: Borrowed<'_, '_, PyWeakrefReference>) -> String {
    if let Some(data_src) = unsafe { reference.upgrade_as_unchecked::<Foo>() } {
        let data = data_src.borrow();
        let (name, score) = data.get_data();
        format!("Processing '{}': score = {}", name, score)
    } else {
        "The supplied data reference is nolonger relavent.".to_owned()
    }
}

Python::with_gil(|py| {
    let data = Bound::new(py, Foo{})?;
    let reference = PyWeakrefReference::new(&data)?;

    assert_eq!(
        parse_data(reference.as_borrowed()),
        "Processing 'Dave': score = 10"
    );

    drop(data);

    assert_eq!(
        parse_data(reference.as_borrowed()),
        "The supplied data reference is nolonger relavent."
    );

    Ok(())
})

Panics

This function panics is the current object is invalid. If used propperly this is never the case. (NonNull and actually a weakref type)

fn upgrade_as_exact<T>(&self) -> PyResult<Option<Bound<'py, T>>>

where T: PyTypeInfo,

Upgrade the weakref to a exact direct Bound object reference.

It is named upgrade to be inline with rust’s Weak::upgrade. In Python it would be equivalent to PyWeakref_GetRef.

Example

use pyo3::prelude::*;
use pyo3::types::PyWeakrefReference;

#[pyclass(weakref)]
struct Foo { /* fields omitted */ }

#[pymethods]
impl Foo {
    fn get_data(&self) -> (&str, u32) {
        ("Dave", 10)
    }
}

fn parse_data(reference: Borrowed<'_, '_, PyWeakrefReference>) -> PyResult<String> {
    if let Some(data_src) = reference.upgrade_as_exact::<Foo>()? {
        let data = data_src.borrow();
        let (name, score) = data.get_data();
        Ok(format!("Processing '{}': score = {}", name, score))
    } else {
        Ok("The supplied data reference is nolonger relavent.".to_owned())
    }
}

Python::with_gil(|py| {
    let data = Bound::new(py, Foo{})?;
    let reference = PyWeakrefReference::new(&data)?;

    assert_eq!(
        parse_data(reference.as_borrowed())?,
        "Processing 'Dave': score = 10"
    );

    drop(data);

    assert_eq!(
        parse_data(reference.as_borrowed())?,
        "The supplied data reference is nolonger relavent."
    );

    Ok(())
})

Panics

This function panics is the current object is invalid. If used propperly this is never the case. (NonNull and actually a weakref type)

fn get_object(&self) -> Bound<'py, PyAny>

👎Deprecated since 0.23.0: Use upgrade instead

Retrieve to a Bound object pointed to by the weakref.

This function returns Bound<'py, PyAny>, which is either the object if it still exists, otherwise it will refer to PyNone.

This function gets the optional target of this weakref.ReferenceType (result of calling weakref.ref). It produces similar results to using PyWeakref_GetRef in the C api.

Example

#![allow(deprecated)]
use pyo3::prelude::*;
use pyo3::types::PyWeakrefReference;

#[pyclass(weakref)]
struct Foo { /* fields omitted */ }

fn get_class(reference: Borrowed<'_, '_, PyWeakrefReference>) -> PyResult<String> {
    reference
        .get_object()
        .getattr("__class__")?
        .repr()
        .map(|repr| repr.to_string())
}

Python::with_gil(|py| {
    let object = Bound::new(py, Foo{})?;
    let reference = PyWeakrefReference::new(&object)?;

    assert_eq!(
        get_class(reference.as_borrowed())?,
        "<class 'builtins.Foo'>"
    );

    drop(object);

    assert_eq!(get_class(reference.as_borrowed())?, "<class 'NoneType'>");

    Ok(())
})

Panics

This function panics is the current object is invalid. If used propperly this is never the case. (NonNull and actually a weakref type)

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> PyWeakrefMethods<'py> for Bound<'py, PyWeakrefProxy>

impl<'py> PyWeakrefMethods<'py> for Bound<'py, PyWeakrefReference>

impl<'py> PyWeakrefMethods<'py> for Bound<'py, PyWeakref>