Trait pyo3::prelude::PyWeakrefMethods

source · 
pub trait PyWeakrefMethods<'py> {
    // Required method
    fn get_object_borrowed(&self) -> Borrowed<'_, 'py, PyAny>;

    // Provided methods
    fn upgrade_as<T>(&self) -> PyResult<Option<Bound<'py, T>>>
       where T: PyTypeCheck { ... }
    fn upgrade_borrowed_as<'a, T>(
        &'a self,
    ) -> PyResult<Option<Borrowed<'a, 'py, T>>>
       where T: PyTypeCheck,
             'py: 'a { ... }
    unsafe fn upgrade_as_unchecked<T>(&self) -> Option<Bound<'py, T>> { ... }
    unsafe fn upgrade_borrowed_as_unchecked<'a, T>(
        &'a self,
    ) -> Option<Borrowed<'a, 'py, T>>
       where 'py: 'a { ... }
    fn upgrade_as_exact<T>(&self) -> PyResult<Option<Bound<'py, T>>>
       where T: PyTypeInfo { ... }
    fn upgrade_borrowed_as_exact<'a, T>(
        &'a self,
    ) -> PyResult<Option<Borrowed<'a, 'py, T>>>
       where T: PyTypeInfo,
             'py: 'a { ... }
    fn upgrade(&self) -> Option<Bound<'py, PyAny>> { ... }
    fn upgrade_borrowed<'a>(&'a self) -> Option<Borrowed<'a, 'py, PyAny>>
       where 'py: 'a { ... }
    fn get_object(&self) -> Bound<'py, PyAny> { ... }
}
Expand description

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§

source

fn get_object_borrowed(&self) -> Borrowed<'_, 'py, PyAny>

Retrieve to a Borrowed object pointed to by the weakref.

This function returns Borrowed<'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 similair results to using PyWeakref_GetObject in the C api.

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

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

fn get_class(reference: Borrowed<'_, '_, PyWeakrefReference>) -> PyResult<String> {
    reference
        .get_object_borrowed()
        .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)

Provided Methods§

source

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

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

source

fn upgrade_borrowed_as<'a, T>( &'a self, ) -> PyResult<Option<Borrowed<'a, 'py, T>>>
where T: PyTypeCheck, 'py: 'a,

Upgrade the weakref to a Borrowed object reference.

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

§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_borrowed_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)

source

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

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

source

unsafe fn upgrade_borrowed_as_unchecked<'a, T>( &'a self, ) -> Option<Borrowed<'a, 'py, T>>
where 'py: 'a,

Upgrade the weakref to a Borrowed 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_borrowed to be inline with rust’s Weak::upgrade. In Python it would be equivalent to PyWeakref_GetObject.

§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_borrowed_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)

source

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

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

source

fn upgrade_borrowed_as_exact<'a, T>( &'a self, ) -> PyResult<Option<Borrowed<'a, 'py, T>>>
where T: PyTypeInfo, 'py: 'a,

Upgrade the weakref to a exact Borrowed object reference.

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

§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_borrowed_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)

source

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 similair results to using PyWeakref_GetObject 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 propperly this is never the case. (NonNull and actually a weakref type)

source

fn upgrade_borrowed<'a>(&'a self) -> Option<Borrowed<'a, 'py, PyAny>>
where 'py: 'a,

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

It is named upgrade_borrowed to be inline with rust’s Weak::upgrade. This function returns Some(Borrowed<'_, '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 similair results to using PyWeakref_GetObject 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_borrowed() {
        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 propperly this is never the case. (NonNull and actually a weakref type)

source

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

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 similair results to using PyWeakref_GetObject in the C api.

§Example
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)

Object Safety§

This trait is not object safe.

Implementors§