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§
Sourcefn get_object_borrowed(&self) -> Borrowed<'_, 'py, PyAny>
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_bound(&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§
Sourcefn upgrade_as<T>(&self) -> PyResult<Option<Bound<'py, T>>>where
T: PyTypeCheck,
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_bound(&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)
Sourcefn upgrade_borrowed_as<'a, T>(
&'a self,
) -> PyResult<Option<Borrowed<'a, 'py, T>>>where
T: PyTypeCheck,
'py: 'a,
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_bound(&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)
Sourceunsafe fn upgrade_as_unchecked<T>(&self) -> Option<Bound<'py, T>>
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_bound(&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)
Sourceunsafe fn upgrade_borrowed_as_unchecked<'a, T>(
&'a self,
) -> Option<Borrowed<'a, 'py, T>>where
'py: 'a,
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_bound(&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)
Sourcefn upgrade_as_exact<T>(&self) -> PyResult<Option<Bound<'py, T>>>where
T: PyTypeInfo,
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_bound(&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)
Sourcefn upgrade_borrowed_as_exact<'a, T>(
&'a self,
) -> PyResult<Option<Borrowed<'a, 'py, T>>>where
T: PyTypeInfo,
'py: 'a,
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_bound(&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)
Sourcefn upgrade(&self) -> Option<Bound<'py, PyAny>>
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_bound(&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)
Sourcefn upgrade_borrowed<'a>(&'a self) -> Option<Borrowed<'a, 'py, PyAny>>where
'py: 'a,
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_bound(&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)
Sourcefn get_object(&self) -> Bound<'py, PyAny>
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_bound(&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.