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

chore: Version bumps and package naming in CI and README #9

Merged
merged 5 commits into from
Oct 24, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
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
2 changes: 1 addition & 1 deletion .github/workflows/guide.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ jobs:
cargo doc --no-deps --all-features
mkdir -p gh-pages-build
cp -r target/doc gh-pages-build/doc
echo "<meta http-equiv=refresh content=0;url=pyo3_asyncio/index.html>" > gh-pages-build/doc/index.html
echo "<meta http-equiv=refresh content=0;url=pyo3_async_runtimes/index.html>" > gh-pages-build/doc/index.html

- name: Prepare tag
id: prepare_tag
Expand Down
14 changes: 7 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -229,7 +229,7 @@ to do something special with the object that it returns.
Normally in Python, that something special is the `await` keyword, but in order to await this
coroutine in Rust, we first need to convert it into Rust's version of a `coroutine`: a `Future`.
That's where `pyo3-async-runtimes` comes in.
[`pyo3_async_runtimes::into_future`](https://docs.rs/pyo3-asyncio/latest/pyo3_asyncio/fn.into_future.html)
[`pyo3_async_runtimes::into_future`](https://docs.rs/pyo3-asyncio/latest/pyo3_async_runtimes/fn.into_future.html)
douglasdavis marked this conversation as resolved.
Show resolved Hide resolved
performs this conversion for us:

```rust no_run
Expand Down Expand Up @@ -281,7 +281,7 @@ let future = rust_sleep();

We can convert this `Future` object into Python to make it `awaitable`. This tells Python that you
can use the `await` keyword with it. In order to do this, we'll call
[`pyo3_async_runtimes::async_std::future_into_py`](https://docs.rs/pyo3-asyncio/latest/pyo3_asyncio/async_std/fn.future_into_py.html):
[`pyo3_async_runtimes::async_std::future_into_py`](https://docs.rs/pyo3-asyncio/latest/pyo3_async_runtimes/async_std/fn.future_into_py.html):

```rust
use pyo3::prelude::*;
Expand Down Expand Up @@ -323,7 +323,7 @@ implementations _prefer_ control over the main thread, this can still make some

Because Python needs to control the main thread, we can't use the convenient proc macros from Rust
runtimes to handle the `main` function or `#[test]` functions. Instead, the initialization for PyO3 has to be done from the `main` function and the main
thread must block on [`pyo3_async_runtimes::run_forever`](https://docs.rs/pyo3-asyncio/latest/pyo3_asyncio/fn.run_forever.html) or [`pyo3_async_runtimes::async_std::run_until_complete`](https://docs.rs/pyo3-asyncio/latest/pyo3_asyncio/async_std/fn.run_until_complete.html).
thread must block on [`pyo3_async_runtimes::run_forever`](https://docs.rs/pyo3-asyncio/latest/pyo3_async_runtimes/fn.run_forever.html) or [`pyo3_async_runtimes::async_std::run_until_complete`](https://docs.rs/pyo3-asyncio/latest/pyo3_async_runtimes/async_std/fn.run_until_complete.html).

Because we have to block on one of those functions, we can't use [`#[async_std::main]`](https://docs.rs/async-std/latest/async_std/attr.main.html) or [`#[tokio::main]`](https://docs.rs/tokio/1.1.0/tokio/attr.main.html)
since it's not a good idea to make long blocking calls during an async function.
Expand Down Expand Up @@ -534,8 +534,8 @@ fn main() -> PyResult<()> {

### Additional Information

- Managing event loop references can be tricky with pyo3-asyncio. See [Event Loop References and ContextVars](https://awestlake87.github.io/pyo3-asyncio/master/doc/pyo3_asyncio/#event-loop-references-and-contextvars) in the API docs to get a better intuition for how event loop references are managed in this library.
- Testing pyo3-asyncio libraries and applications requires a custom test harness since Python requires control over the main thread. You can find a testing guide in the [API docs for the `testing` module](https://awestlake87.github.io/pyo3-asyncio/master/doc/pyo3_asyncio/testing)
- Managing event loop references can be tricky with pyo3-asyncio. See [Event Loop References and ContextVars](https://awestlake87.github.io/pyo3-asyncio/master/doc/pyo3_async_runtimes/#event-loop-references-and-contextvars) in the API docs to get a better intuition for how event loop references are managed in this library.
- Testing pyo3-asyncio libraries and applications requires a custom test harness since Python requires control over the main thread. You can find a testing guide in the [API docs for the `testing` module](https://awestlake87.github.io/pyo3-asyncio/master/doc/pyo3_async_runtimes/testing)

## Migration Guide

Expand All @@ -547,7 +547,7 @@ Well, a lot actually. There were some pretty major flaws in the initialization b

To make things a bit easier, I decided to keep most of the old API alongside the new one (with some deprecation warnings to encourage users to move away from it). It should be possible to use the `v0.13` API alongside the newer `v0.14` API, which should allow you to upgrade your application piecemeal rather than all at once.

**Before you get started, I personally recommend taking a look at [Event Loop References and ContextVars](https://awestlake87.github.io/pyo3-asyncio/master/doc/pyo3_asyncio/#event-loop-references-and-contextvars) in order to get a better grasp on the motivation behind these changes and the nuance involved in using the new conversions.**
**Before you get started, I personally recommend taking a look at [Event Loop References and ContextVars](https://awestlake87.github.io/pyo3-asyncio/master/doc/pyo3_async_runtimes/#event-loop-references-and-contextvars) in order to get a better grasp on the motivation behind these changes and the nuance involved in using the new conversions.**

### 0.14 Highlights

Expand Down Expand Up @@ -635,7 +635,7 @@ To make things a bit easier, I decided to keep most of the old API alongside the
```

4. Replace conversions with their newer counterparts.
> You may encounter some issues regarding the usage of `get_running_loop` vs `get_event_loop`. For more details on these newer conversions and how they should be used see [Event Loop References and ContextVars](https://awestlake87.github.io/pyo3-asyncio/master/doc/pyo3_asyncio/#event-loop-references-and-contextvars).
> You may encounter some issues regarding the usage of `get_running_loop` vs `get_event_loop`. For more details on these newer conversions and how they should be used see [Event Loop References and ContextVars](https://awestlake87.github.io/pyo3-asyncio/master/doc/pyo3_async_runtimes/#event-loop-references-and-contextvars).
- Replace `pyo3_async_runtimes::into_future` with `pyo3_async_runtimes::<runtime>::into_future`
- Replace `pyo3_async_runtimes::<runtime>::into_coroutine` with `pyo3_async_runtimes::<runtime>::future_into_py`
- Replace `pyo3_async_runtimes::get_event_loop` with `pyo3_async_runtimes::<runtime>::get_current_loop`
Expand Down
4 changes: 2 additions & 2 deletions src/async_std.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@
//! are only available when the `unstable-streams` Cargo feature is enabled:
//!
//! ```toml
//! [dependencies.pyo3-asyncio-0-21]
//! version = "0.21"
//! [dependencies.pyo3-async-runtimes]
//! version = "0.22"
//! features = ["unstable-streams"]
//! ```

Expand Down
2 changes: 1 addition & 1 deletion src/err.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
mod exceptions {
use pyo3::{create_exception, exceptions::PyException};

create_exception!(pyo3_asyncio, RustPanic, PyException);
create_exception!(pyo3_async_runtimes, RustPanic, PyException);
}

pub use exceptions::RustPanic;
8 changes: 4 additions & 4 deletions src/generic.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@
//! > are only available when the `unstable-streams` Cargo feature is enabled:
//!
//! ```toml
//! [dependencies.pyo3-asyncio-0-21]
//! version = "0.21"
//! [dependencies.pyo3-async-runtimes]
//! version = "0.22"
//! features = ["unstable-streams"]
//! ```

Expand Down Expand Up @@ -1651,8 +1651,8 @@ where
Ok(PyModule::from_code_bound(
py,
STREAM_GLUE,
"pyo3_asyncio/pyo3_asyncio_glue.py",
"pyo3_asyncio_glue",
"pyo3_async_runtimes/pyo3_async_runtimes_glue.py",
"pyo3_async_runtimes_glue",
)?
.into())
})?
Expand Down
18 changes: 9 additions & 9 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -299,8 +299,8 @@
//! > are only available when the `attributes` Cargo feature is enabled:
//!
//! ```toml
//! [dependencies.pyo3-asyncio-0-21]
//! version = "0.21"
//! [dependencies.pyo3-async-runtimes]
//! version = "0.22"
//! features = ["attributes"]
//! ```
//!
Expand All @@ -312,8 +312,8 @@
//! > are only available when the `async-std-runtime` Cargo feature is enabled:
//!
//! ```toml
//! [dependencies.pyo3-asyncio-0-21]
//! version = "0.21"
//! [dependencies.pyo3-async-runtimes]
//! version = "0.22"
//! features = ["async-std-runtime"]
//! ```
//!
Expand All @@ -325,8 +325,8 @@
//! > are only available when the `tokio-runtime` Cargo feature is enabled:
//!
//! ```toml
//! [dependencies.pyo3-asyncio-0-21]
//! version = "0.21"
//! [dependencies.pyo3-async-runtimes]
//! version = "0.22"
//! features = ["tokio-runtime"]
//! ```
//!
Expand All @@ -338,8 +338,8 @@
//! > are only available when the `testing` Cargo feature is enabled:
//!
//! ```toml
//! [dependencies.pyo3-asyncio-0-21]
//! version = "0.21"
//! [dependencies.pyo3-async-runtimes]
//! version = "0.22"
//! features = ["testing"]
//! ```

Expand All @@ -363,7 +363,7 @@ pub mod err;
pub mod generic;

#[pymodule]
fn pyo3_asyncio(py: Python, m: &Bound<PyModule>) -> PyResult<()> {
fn pyo3_async_runtimes(py: Python, m: &Bound<PyModule>) -> PyResult<()> {
m.add("RustPanic", py.get_type_bound::<err::RustPanic>())?;
Ok(())
}
Expand Down
18 changes: 9 additions & 9 deletions src/testing.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
//! harness since it doesn't allow Python to gain control over the main thread. Instead, we have to
//! provide our own test harness in order to create integration tests.
//!
//! Running `pyo3-asyncio` code in doc tests _is_ supported however since each doc test has its own
//! Running `pyo3-async-runtimes` code in doc tests _is_ supported however since each doc test has its own
//! `main` function. When writing doc tests, you may use the
//! [`#[pyo3_async_runtimes::async_std::main]`](crate::async_std::main) or
//! [`#[pyo3_async_runtimes::tokio::main]`](crate::tokio::main) macros on the test's main function to run
Expand All @@ -26,7 +26,7 @@
//! > The name `pytests` is just a convention. You can name this folder anything you want in your own
//! > projects.
//!
//! We'll also want to provide the test's main function. Most of the functionality that the test harness needs is packed in the [`pyo3_async_runtimes::testing::main`](https://docs.rs/pyo3-asyncio/latest/pyo3_asyncio/testing/fn.main.html) function. This function will parse the test's CLI arguments, collect and pass the functions marked with [`#[pyo3_async_runtimes::async_std::test]`](https://docs.rs/pyo3-asyncio/latest/pyo3_asyncio/async_std/attr.test.html) or [`#[pyo3_async_runtimes::tokio::test]`](https://docs.rs/pyo3-asyncio/latest/pyo3_asyncio/tokio/attr.test.html) and pass them into the test harness for running and filtering.
//! We'll also want to provide the test's main function. Most of the functionality that the test harness needs is packed in the [`pyo3_async_runtimes::testing::main`](https://docs.rs/pyo3-async-runtimes/latest/pyo3_async_runtimes/testing/fn.main.html) function. This function will parse the test's CLI arguments, collect and pass the functions marked with [`#[pyo3_async_runtimes::async_std::test]`](https://docs.rs/pyo3-async-runtimes/latest/pyo3_async_runtimes/async_std/attr.test.html) or [`#[pyo3_async_runtimes::tokio::test]`](https://docs.rs/pyo3-async-runtimes/latest/pyo3_async_runtimes/tokio/attr.test.html) and pass them into the test harness for running and filtering.
//!
//! `pytests/test_example.rs` for the `tokio` runtime:
//! ```rust
Expand Down Expand Up @@ -61,10 +61,10 @@
//! harness = false
//! ```
//!
//! Also add the `testing` and `attributes` features to the `pyo3-asyncio` dependency and select your preferred runtime:
//! Also add the `testing` and `attributes` features to the `pyo3-async-runtimes` dependency and select your preferred runtime:
//!
//! ```toml
//! pyo3-asyncio-0-21 = { version = "0.21", features = ["testing", "attributes", "async-std-runtime"] }
//! pyo3-async-runtimes = { version = "0.22", features = ["testing", "attributes", "async-std-runtime"] }
//! ```
//!
//! At this point, you should be able to run the test via `cargo test`
Expand All @@ -73,7 +73,7 @@
//!
//! We can add tests anywhere in the test crate with the runtime's corresponding `#[test]` attribute:
//!
//! For `async-std` use the [`pyo3_async_runtimes::async_std::test`](https://docs.rs/pyo3-asyncio/latest/pyo3_asyncio/async_std/attr.test.html) attribute:
//! For `async-std` use the [`pyo3_async_runtimes::async_std::test`](https://docs.rs/pyo3-async-runtimes/latest/pyo3_async_runtimes/async_std/attr.test.html) attribute:
//! ```rust
//! # #[cfg(all(feature = "async-std-runtime", feature = "attributes"))]
//! mod tests {
Expand Down Expand Up @@ -105,7 +105,7 @@
//! # fn main() {}
//! ```
//!
//! For `tokio` use the [`pyo3_async_runtimes::tokio::test`](https://docs.rs/pyo3-asyncio/latest/pyo3_asyncio/tokio/attr.test.html) attribute:
//! For `tokio` use the [`pyo3_async_runtimes::tokio::test`](https://docs.rs/pyo3-async-runtimes/latest/pyo3_async_runtimes/tokio/attr.test.html) attribute:
//! ```rust
//! # #[cfg(all(feature = "tokio-runtime", feature = "attributes"))]
//! mod tests {
Expand Down Expand Up @@ -202,7 +202,7 @@ pub struct Args {
/// Ideally, we should mirror the default test harness's arguments exactly, but
/// for the sake of simplicity, only filtering is supported for now. If you want
/// more features, feel free to request them
/// [here](https://github.com/awestlake87/pyo3-asyncio/issues).
/// [here](https://github.com/PyO3/pyo3-async-runtimes/issues).
///
/// # Examples
///
Expand Down Expand Up @@ -241,7 +241,7 @@ pub fn parse_args() -> Args {

type TestFn = dyn Fn() -> Pin<Box<dyn Future<Output = PyResult<()>> + Send>> + Send + Sync;

/// The structure used by the `#[test]` macros to provide a test to the `pyo3-asyncio` test harness.
/// The structure used by the `#[test]` macros to provide a test to the `pyo3-async-runtimes` test harness.
#[derive(Clone)]
pub struct Test {
/// The fully qualified name of the test
Expand Down Expand Up @@ -286,7 +286,7 @@ pub async fn test_harness(tests: Vec<Test>, args: Args) -> PyResult<()> {
Ok(())
}

/// Parses test arguments and passes the tests to the `pyo3-asyncio` test harness
/// Parses test arguments and passes the tests to the `pyo3-async-runtimes` test harness
///
/// This function collects the test structures from the `inventory` boilerplate and forwards them to
/// the test harness.
Expand Down
Loading