Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feature gate deprecated more APIs for Py #4169

Merged
merged 1 commit into from
May 10, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions guide/src/python-from-rust/calling-existing-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ fn main() -> PyResult<()> {
}
```

## Want to run just an expression? Then use `eval`.
## Want to run just an expression? Then use `eval_bound`.

[`Python::eval`]({{#PYO3_DOCS_URL}}/pyo3/marker/struct.Python.html#method.eval) is
[`Python::eval_bound`]({{#PYO3_DOCS_URL}}/pyo3/marker/struct.Python.html#method.eval_bound) is
a method to execute a [Python expression](https://docs.python.org/3.7/reference/expressions.html)
and return the evaluated value as a `Bound<'py, PyAny>` object.

Expand All @@ -47,14 +47,14 @@ Python::with_gil(|py| {
# }
```

## Want to run statements? Then use `run`.
## Want to run statements? Then use `run_bound`.

[`Python::run`] is a method to execute one or more
[`Python::run_bound`] is a method to execute one or more
[Python statements](https://docs.python.org/3.7/reference/simple_stmts.html).
This method returns nothing (like any Python statement), but you can get
access to manipulated objects via the `locals` dict.

You can also use the [`py_run!`] macro, which is a shorthand for [`Python::run`].
You can also use the [`py_run!`] macro, which is a shorthand for [`Python::run_bound`].
Since [`py_run!`] panics on exceptions, we recommend you use this macro only for
quickly testing your Python extensions.

Expand Down
2 changes: 1 addition & 1 deletion src/err/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -724,7 +724,7 @@ impl PyErr {
///
/// The `category` should be one of the `Warning` classes available in
/// [`pyo3::exceptions`](crate::exceptions), or a subclass. The Python
/// object can be retrieved using [`Python::get_type()`].
/// object can be retrieved using [`Python::get_type_bound()`].
///
/// Example:
/// ```rust
Expand Down
4 changes: 2 additions & 2 deletions src/macros.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@
///
/// # Panics
///
/// This macro internally calls [`Python::run`](crate::Python::run) and panics
/// This macro internally calls [`Python::run_bound`](crate::Python::run_bound) and panics
/// if it returns `Err`, after printing the error to stdout.
///
/// If you need to handle failures, please use [`Python::run`](crate::marker::Python::run) instead.
/// If you need to handle failures, please use [`Python::run_bound`](crate::marker::Python::run_bound) instead.
///
/// # Examples
/// ```
Expand Down
50 changes: 22 additions & 28 deletions src/marker.rs
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,9 @@ use crate::types::{
PyAny, PyDict, PyEllipsis, PyModule, PyNone, PyNotImplemented, PyString, PyType,
};
use crate::version::PythonVersionInfo;
use crate::{ffi, Bound, IntoPy, Py, PyNativeType, PyObject, PyTypeInfo};
#[cfg(feature = "gil-refs")]
use crate::PyNativeType;
use crate::{ffi, Bound, IntoPy, Py, PyObject, PyTypeInfo};
#[allow(deprecated)]
use crate::{gil::GILPool, FromPyPointer};
use std::ffi::{CStr, CString};
Expand Down Expand Up @@ -305,7 +307,7 @@ pub use nightly::Ungil;
/// A marker token that represents holding the GIL.
///
/// It serves three main purposes:
/// - It provides a global API for the Python interpreter, such as [`Python::eval`].
/// - It provides a global API for the Python interpreter, such as [`Python::eval_bound`].
/// - It can be passed to functions that require a proof of holding the GIL, such as
/// [`Py::clone_ref`].
/// - Its lifetime represents the scope of holding the GIL which can be used to create Rust
Expand All @@ -321,7 +323,7 @@ pub use nightly::Ungil;
/// - In a function or method annotated with [`#[pyfunction]`](crate::pyfunction) or [`#[pymethods]`](crate::pymethods) you can declare it
/// as a parameter, and PyO3 will pass in the token when Python code calls it.
/// - If you already have something with a lifetime bound to the GIL, such as `&`[`PyAny`], you can
/// use its [`.py()`][PyAny::py] method to get a token.
/// use its `.py()` method to get a token.
/// - When you need to acquire the GIL yourself, such as when calling Python code from Rust, you
/// should call [`Python::with_gil`] to do that and pass your code as a closure to it.
///
Expand Down Expand Up @@ -352,7 +354,7 @@ pub use nightly::Ungil;
/// # Releasing and freeing memory
///
/// The [`Python`] type can be used to create references to variables owned by the Python
/// interpreter, using functions such as [`Python::eval`] and `PyModule::import`. These
/// interpreter, using functions such as `Python::eval` and `PyModule::import`. These
/// references are tied to a [`GILPool`] whose references are not cleared until it is dropped.
/// This can cause apparent "memory leaks" if it is kept around for a long time.
///
Expand Down Expand Up @@ -552,12 +554,10 @@ impl<'py> Python<'py> {
}

/// Deprecated version of [`Python::eval_bound`]
#[cfg_attr(
not(feature = "gil-refs"),
deprecated(
since = "0.21.0",
note = "`Python::eval` will be replaced by `Python::eval_bound` in a future PyO3 version"
)
#[cfg(feature = "gil-refs")]
#[deprecated(
since = "0.21.0",
note = "`Python::eval` will be replaced by `Python::eval_bound` in a future PyO3 version"
)]
pub fn eval(
self,
Expand Down Expand Up @@ -601,12 +601,10 @@ impl<'py> Python<'py> {
}

/// Deprecated version of [`Python::run_bound`]
#[cfg_attr(
not(feature = "gil-refs"),
deprecated(
since = "0.21.0",
note = "`Python::run` will be replaced by `Python::run_bound` in a future PyO3 version"
)
#[cfg(feature = "gil-refs")]
#[deprecated(
since = "0.21.0",
note = "`Python::run` will be replaced by `Python::run_bound` in a future PyO3 version"
)]
pub fn run(
self,
Expand Down Expand Up @@ -728,12 +726,10 @@ impl<'py> Python<'py> {
}

/// Gets the Python type object for type `T`.
#[cfg_attr(
not(feature = "gil-refs"),
deprecated(
since = "0.21.0",
note = "`Python::get_type` will be replaced by `Python::get_type_bound` in a future PyO3 version"
)
#[cfg(feature = "gil-refs")]
#[deprecated(
since = "0.21.0",
note = "`Python::get_type` will be replaced by `Python::get_type_bound` in a future PyO3 version"
)]
#[inline]
pub fn get_type<T>(self) -> &'py PyType
Expand All @@ -753,12 +749,10 @@ impl<'py> Python<'py> {
}

/// Deprecated form of [`Python::import_bound`]
#[cfg_attr(
not(feature = "gil-refs"),
deprecated(
since = "0.21.0",
note = "`Python::import` will be replaced by `Python::import_bound` in a future PyO3 version"
)
#[cfg(feature = "gil-refs")]
#[deprecated(
since = "0.21.0",
note = "`Python::import` will be replaced by `Python::import_bound` in a future PyO3 version"
)]
pub fn import<N>(self, name: N) -> PyResult<&'py PyModule>
where
Expand Down
Loading