Cleaned up some docs

Author: Andrew J Westlake

pytests/test_tokio_asyncio.rs

@@ -1,14 +1,8 @@
 mod common;
 
-use std::{
-    future::{pending, Future},
-    thread,
-    time::Duration,
-};
+use std::{future::Future, time::Duration};
 
-use lazy_static::lazy_static;
 use pyo3::{prelude::*, wrap_pyfunction};
-use tokio::runtime::{Builder, Runtime};
 
 use pyo3_asyncio::{
     testing::Test,

src/async_std.rs

@@ -1,7 +1,6 @@
 use std::future::Future;
 
 use async_std::task;
-use futures::channel::oneshot;
 use pyo3::prelude::*;
 
 use crate::generic::{self, JoinError, Runtime};
@@ -70,45 +69,6 @@ where
     generic::run_until_complete::<AsyncStdRuntime, _>(py, fut)
 }
 
-#[pyclass]
-struct PyTaskCompleter {
-    tx: Option<oneshot::Sender<PyResult<PyObject>>>,
-}
-
-#[pymethods]
-impl PyTaskCompleter {
-    #[call]
-    #[args(task)]
-    pub fn __call__(&mut self, task: &PyAny) -> PyResult<()> {
-        debug_assert!(task.call_method0("done")?.extract()?);
-
-        let result = match task.call_method0("result") {
-            Ok(val) => Ok(val.into()),
-            Err(e) => Err(e),
-        };
-
-        // unclear to me whether or not this should be a panic or silent error.
-        //
-        // calling PyTaskCompleter twice should not be possible, but I don't think it really hurts
-        // anything if it happens.
-        if let Some(tx) = self.tx.take() {
-            if tx.send(result).is_err() {
-                // cancellation is not an error
-            }
-        }
-
-        Ok(())
-    }
-}
-
-fn dump_err(py: Python<'_>) -> impl FnOnce(PyErr) + '_ {
-    move |e| {
-        // We can't display Python exceptions via std::fmt::Display,
-        // so print the error here manually.
-        e.print_and_set_sys_last_vars(py);
-    }
-}
-
 /// Convert a Rust Future into a Python coroutine
 ///
 /// # Arguments
@@ -230,11 +190,7 @@ pub mod testing {
     use async_std::task;
     use pyo3::prelude::*;
 
-    use crate::{
-        async_std::{dump_err, run_until_complete},
-        testing::{parse_args, test_harness, Test},
-        with_runtime,
-    };
+    use crate::{async_std::AsyncStdRuntime, generic, testing::Test};
 
     /// Construct a test from a blocking function (like the traditional `#[test]` attribute)
     pub fn new_sync_test<F>(name: String, func: F) -> Test
@@ -250,14 +206,6 @@ pub mod testing {
     /// additional control over the initialization (i.e. env_logger initialization), you can use this
     /// function as a template.
     pub fn test_main(suite_name: &str, tests: Vec<Test>) {
-        Python::with_gil(|py| {
-            with_runtime(py, || {
-                let args = parse_args(suite_name);
-                run_until_complete(py, test_harness(tests, args))?;
-                Ok(())
-            })
-            .map_err(dump_err(py))
-            .unwrap();
-        })
+        generic::testing::test_main::<AsyncStdRuntime>(suite_name, tests)
     }
 }

src/generic.rs

@@ -3,16 +3,22 @@ use std::future::Future;
 use futures::channel::oneshot;
 use pyo3::{exceptions::PyException, prelude::*};
 
-use crate::{get_event_loop, CALL_SOON, CREATE_FUTURE, EXPECT_INIT};
+use crate::{dump_err, get_event_loop, CALL_SOON, CREATE_FUTURE, EXPECT_INIT};
 
+/// Generic utilities for a JoinError
 pub trait JoinError {
+    /// Check if the spawned task exited because of a panic
     fn is_panic(&self) -> bool;
 }
 
+/// Generic Rust async/await runtime
 pub trait Runtime {
+    /// The type of errors that a JoinHandle can return after awaited
     type JoinError: JoinError + Send;
+    /// A future that completes with the result of the spawned task
     type JoinHandle: Future<Output = Result<(), Self::JoinError>> + Send;
 
+    /// Spawn a function onto this runtime's event loop
     fn spawn<F>(fut: F) -> Self::JoinHandle
     where
         F: Future<Output = ()> + Send + 'static;
@@ -153,14 +159,6 @@ fn set_result(py: Python, future: &PyAny, result: PyResult<PyObject>) -> PyResul
     Ok(())
 }
 
-fn dump_err(py: Python<'_>) -> impl FnOnce(PyErr) + '_ {
-    move |e| {
-        // We can't display Python exceptions via std::fmt::Display,
-        // so print the error here manually.
-        e.print_and_set_sys_last_vars(py);
-    }
-}
-
 /// Convert a Rust Future into a Python coroutine with a generic runtime
 ///
 /// # Arguments
@@ -272,7 +270,8 @@ pub mod testing {
     use pyo3::prelude::*;
 
     use crate::{
-        generic::{dump_err, run_until_complete, Runtime},
+        dump_err,
+        generic::{run_until_complete, Runtime},
         testing::{parse_args, test_harness, Test},
         with_runtime,
     };

src/lib.rs

@@ -90,6 +90,7 @@ pub mod async_std;
 #[doc(inline)]
 pub mod tokio;
 
+/// Generic implementations of PyO3 Asyncio utilities that can be used for any Rust runtime
 pub mod generic;
 
 use std::future::Future;
@@ -372,3 +373,11 @@ pub fn into_future(
         }
     })
 }
+
+fn dump_err(py: Python<'_>) -> impl FnOnce(PyErr) + '_ {
+    move |e| {
+        // We can't display Python exceptions via std::fmt::Display,
+        // so print the error here manually.
+        e.print_and_set_sys_last_vars(py);
+    }
+}

src/tokio.rs

@@ -7,11 +7,10 @@ use ::tokio::{
     runtime::{Builder, Runtime},
     task,
 };
-use futures::channel::oneshot;
 use lazy_static::lazy_static;
 use pyo3::prelude::*;
 
-use crate::{generic, CALL_SOON, EXPECT_INIT};
+use crate::generic;
 
 lazy_static! {
     static ref CURRENT_THREAD_RUNTIME: Runtime = {
@@ -97,66 +96,6 @@ where
     generic::run_until_complete::<TokioRuntime, _>(py, fut)
 }
 
-#[pyclass]
-struct PyTaskCompleter {
-    tx: Option<oneshot::Sender<PyResult<PyObject>>>,
-}
-
-#[pymethods]
-impl PyTaskCompleter {
-    #[call]
-    #[args(task)]
-    pub fn __call__(&mut self, task: &PyAny) -> PyResult<()> {
-        debug_assert!(task.call_method0("done")?.extract()?);
-
-        let result = match task.call_method0("result") {
-            Ok(val) => Ok(val.into()),
-            Err(e) => Err(e),
-        };
-
-        // unclear to me whether or not this should be a panic or silent error.
-        //
-        // calling PyTaskCompleter twice should not be possible, but I don't think it really hurts
-        // anything if it happens.
-        if let Some(tx) = self.tx.take() {
-            if tx.send(result).is_err() {
-                // cancellation is not an error
-            }
-        }
-
-        Ok(())
-    }
-}
-
-fn set_result(py: Python, future: &PyAny, result: PyResult<PyObject>) -> PyResult<()> {
-    match result {
-        Ok(val) => {
-            let set_result = future.getattr("set_result")?;
-            CALL_SOON
-                .get()
-                .expect(EXPECT_INIT)
-                .call1(py, (set_result, val))?;
-        }
-        Err(err) => {
-            let set_exception = future.getattr("set_exception")?;
-            CALL_SOON
-                .get()
-                .expect(EXPECT_INIT)
-                .call1(py, (set_exception, err))?;
-        }
-    }
-
-    Ok(())
-}
-
-fn dump_err(py: Python<'_>) -> impl FnOnce(PyErr) + '_ {
-    move |e| {
-        // We can't display Python exceptions via std::fmt::Display,
-        // so print the error here manually.
-        e.print_and_set_sys_last_vars(py);
-    }
-}
-
 /// Convert a Rust Future into a Python coroutine
 ///
 /// # Arguments
@@ -275,8 +214,8 @@ pub mod testing {
     use pyo3::prelude::*;
 
     use crate::{
+        dump_err,
         testing::{parse_args, test_harness, Test},
-        tokio::dump_err,
         with_runtime,
     };