rubyx-py 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 779abf6ff7235f29633d44399308ee23f3a6244b4f23e3f0fb0a056914602ea7
-  data.tar.gz: a08a4226433cecb9533b09e23e5867f248b5fcec4b994dc3623a7f5698c33475
+  metadata.gz: 2815c45d6a58b835cfc97484894c6aff43abf13316f18006f46a38c059988ec9
+  data.tar.gz: 2eb4aa61608a7553046b01143d7a704dd204a9eb0a13aa1c1a933350f092b660
 SHA512:
-  metadata.gz: 85de3fdcbe4f96fc99db882a0e06c25347f31cb5e1d474e0d330698be781ee215163590ff68ed368aa9ecff3dd605dfd509349458307e33eedfff6c9137c4473
-  data.tar.gz: 2ed6beee3da490dda53cb6d49897d3c092870404e1f93c53d2e0fdeb22a1bf59159c14a67ab60411601f493fa06df4e19aae09ab4914bbe9c5413899f616f7ad
+  metadata.gz: 4bd4ce8b2bf2e169a8b32adc9f3fefaf8445fdcc72b1eb1ac821d6c8b8ae192979b0f00260585844e22f0aa3b76a70648801c11130e82df8cb6b6da66bdfec4d
+  data.tar.gz: 0ef30d48d7cbeb5b85e33cb51fa5abebc67808495ff2bcb840b78c1b7c962fa62cb484b7f88a3ee84cc0506e13c6a06c0d173aa0fb03f9f0074443e0aa3e2397

data/README.md

@@ -1,12 +1,14 @@
 <div align="center">
 
+<img src="docs/assets/logo.png" alt="rubyx-py" width="200">
+
 # Rubyx-py
 
 **Call Python from Ruby. No microservices, no REST APIs, no serialization overhead.**
 
 Powered by Rust for safety and performance. Built for Rails.
 
-[![Gem Version](https://badge.fury.io/rb/rubyx.svg)](https://badge.fury.io/rb/rubyx)
+[![Gem Version](https://badge.fury.io/rb/rubyx-py.svg)](https://badge.fury.io/rb/rubyx-py)
 [![CI](https://github.com/yinho999/rubyx/actions/workflows/ci.yml/badge.svg)](https://github.com/yinho999/rubyx/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.0-red.svg)](https://www.ruby-lang.org)
@@ -34,15 +36,17 @@ Rubyx.stream(llm.generate("Tell me about Ruby")).each { |token| print token }
 # Non-blocking — Ruby stays free while Python works
 future = Rubyx.async_await("model.predict(data)", data: [1, 2, 3])
 do_other_work()
-result = future.value # get result when ready
+result = future.await # GVL released during wait, reacquired when ready
 ```
 
 ### Built with non-blocking in mind
 
 - **`Rubyx.stream`** / **`Rubyx.nb_stream`** — release Ruby's GVL during iteration, other threads and Fibers keep
   running
-- **`Rubyx.async_await`** — spawns Python on background threads, returns a `Future` immediately
-- **`Rubyx.await`** — blocks only when you choose to
+- **`Rubyx.async_await`** — spawns Python on background threads, returns a `Future` immediately; `future.await` releases
+  the GVL while waiting, reacquires when ready
+- **`Rubyx.await`** — GVL released while waiting; returns native Ruby types for primitives, `RubyxObject` for complex
+  Python objects
 
 Ideal for LLM streaming, ML inference, data pipelines, and high-concurrency Rails apps.
 
@@ -88,20 +92,27 @@ dependencies = []
 ### 1. Sync — call a Python function
 
 ```python
-# app/python/hello.py
-def greet(name):
-    return f"Hello, {name}!"
+# app/python/example.py
+def hello(name="World"):
+    return f"Hello, {name}! From Python."
 ```
 
 ```ruby
+
 class GreetingsController < ApplicationController
-  def show
-    hello = Rubyx.import('hello')
-    render json: { message: hello.greet(params[:name]).to_ruby }
+  def index
+    example = Rubyx.import('example')
+    render json: { message: example.hello(params[:name]).to_ruby }
   end
 end
 ```
 
+```ruby
+Rails.application.routes.draw do
+  root "greetings#index"
+end
+```
+
 ### 2. Streaming — iterate a Python generator
 
 ```python
@@ -112,6 +123,7 @@ def count_up(n):
 ```
 
 ```ruby
+
 class CountController < ApplicationController
   include ActionController::Live
 
@@ -141,6 +153,7 @@ async def delayed_greet(name, seconds=1):
 ```
 
 ```ruby
+
 class TasksController < ApplicationController
   def show
     tasks = Rubyx.import('tasks')
@@ -148,7 +161,7 @@ class TasksController < ApplicationController
     # Non-blocking — returns a Future immediately
     future = Rubyx.async_await(tasks.delayed_greet(params[:name], seconds: 2))
     do_other_work()
-    render json: { message: future.value.to_ruby }
+    render json: { message: future.await.to_ruby }
   end
 end
 ```
@@ -263,6 +276,7 @@ end
 ```
 
 ```ruby
+
 class ChatController < ApplicationController
   include ActionController::Live
 
@@ -378,13 +392,13 @@ ctx = Rubyx.context
 ctx.eval("import asyncio")
 ctx.eval("async def fetch(url): ...")
 
-# Blocking
+# GVL released while waiting, reacquired when ready
 result = ctx.await("fetch(url)", url: "https://example.com")
 
 # Non-blocking (returns Future)
 future = ctx.async_await("fetch(url)", url: "https://example.com")
 do_other_stuff()
-result = future.value # blocks only when needed
+result = future.await #  GVL released during wait, reacquired when ready
 future.ready? # check without blocking
 ```
 
@@ -433,17 +447,17 @@ svc.Analyzer([1, 2, 3]).summary.to_ruby # => {"count" => 3, "sum" => 6}
 
 ## API Reference
 
-| Method                               | Description                     |
-|--------------------------------------|---------------------------------|
-| `Rubyx.uv_init(toml, **opts)`        | Setup Python env and initialize |
-| `Rubyx.import(name)`                 | Import a Python module          |
-| `Rubyx.eval(code, **globals)`        | Evaluate Python code            |
-| `Rubyx.await(code, **globals)`       | Run async code (blocking)       |
-| `Rubyx.async_await(code, **globals)` | Run async code (returns Future) |
-| `Rubyx.stream(iterable)`             | Stream a Python generator       |
-| `Rubyx.nb_stream(iterable)`          | Non-blocking stream (GVL-aware) |
-| `Rubyx.context`                      | Create isolated Python context  |
-| `Rubyx.initialized?`                 | Check if Python is ready        |
+| Method                               | Description                                   |
+|--------------------------------------|-----------------------------------------------|
+| `Rubyx.uv_init(toml, **opts)`        | Setup Python env and initialize               |
+| `Rubyx.import(name)`                 | Import a Python module                        |
+| `Rubyx.eval(code, **globals)`        | Evaluate Python code                          |
+| `Rubyx.await(code, **globals)`       | Run async code (GVL released while waiting)   |
+| `Rubyx.async_await(code, **globals)` | Run async code (non-blocking, returns Future) |
+| `Rubyx.stream(iterable)`             | Stream a Python generator                     |
+| `Rubyx.nb_stream(iterable)`          | Non-blocking stream (GVL-aware)               |
+| `Rubyx.context`                      | Create isolated Python context                |
+| `Rubyx.initialized?`                 | Check if Python is ready                      |
 
 | RubyxObject              |                               |
 |--------------------------|-------------------------------|

data/ext/rubyx/src/context.rs

@@ -50,9 +50,12 @@ impl RubyxContext {
 
     pub(crate) fn await_eval(&self, code: String) -> Result<magnus::Value, magnus::Error> {
         let gil = self.api.ensure_gil();
-        let result = await_eval_with_globals(&code, self.globals, self.api);
+        let future = await_eval_with_globals(&code, self.globals, self.api);
         self.api.release_gil(gil);
-        result
+        match future {
+            Ok(future) => Ok(crate::future::value_nonblocking(&future)?),
+            Err(e) => Err(e),
+        }
     }
 
     pub(crate) fn await_eval_with_globals(
@@ -61,12 +64,15 @@ impl RubyxContext {
         globals_hash: RHash,
     ) -> Result<magnus::Value, magnus::Error> {
         let gil = self.api.ensure_gil();
-        let result = match self.inject_globals(globals_hash) {
+        let future = match self.inject_globals(globals_hash) {
             Ok(()) => await_eval_with_globals(&code, self.globals, self.api),
             Err(e) => Err(e),
         };
         self.api.release_gil(gil);
-        result
+        match future {
+            Ok(future) => Ok(crate::future::value_nonblocking(&future)?),
+            Err(e) => Err(e),
+        }
     }
 
     /// Eval code to get a coroutine, then run it on a background thread.
@@ -703,20 +709,28 @@ mod tests {
             ctx.eval("import asyncio\nasync def multiply(a, b): return a * b".to_string())
                 .expect("should define function");
 
+            // Inject globals into context
             let hash = magnus::RHash::new();
             hash.aset(ruby.sym_new("a"), 6_i64.into_value_with(ruby))
                 .unwrap();
             hash.aset(ruby.sym_new("b"), 7_i64.into_value_with(ruby))
                 .unwrap();
+            ctx.inject_globals(hash).expect("inject should succeed");
 
-            let result = ctx
-                .await_eval_with_globals("multiply(a, b)".to_string(), hash)
-                .expect("await should succeed");
+            // Manually create future (avoid ctx.await_eval_with_globals which
+            // nests ensure_gil/release_gil incorrectly with with_ruby_python's GIL)
+            let future = crate::eval::await_eval_with_globals("multiply(a, b)", ctx.globals, api)
+                .expect("should create future");
 
-            let obj =
-                magnus::typed_data::Obj::<crate::rubyx_object::RubyxObject>::try_convert(result)
-                    .expect("should be RubyxObject");
-            assert_eq!(api.long_to_i64(obj.as_ptr()), 42);
+            let tstate = api.save_thread();
+            while !future.is_ready() {
+                std::thread::sleep(std::time::Duration::from_millis(1));
+            }
+            let result = future.value().expect("await should succeed");
+            drop(future);
+            api.restore_thread(tstate);
+
+            assert_eq!(i64::try_convert(result).unwrap(), 42);
         });
     }
 
@@ -725,7 +739,7 @@ mod tests {
     fn test_context_await_with_globals_error() {
         use crate::test_helpers::with_ruby_python;
         use magnus::IntoValue;
-        with_ruby_python(|ruby, _api| {
+        with_ruby_python(|ruby, api| {
             let ctx = super::RubyxContext::new().expect("context should create");
 
             ctx.eval(
@@ -737,9 +751,23 @@ mod tests {
             let hash = magnus::RHash::new();
             hash.aset(ruby.sym_new("n"), (-5_i64).into_value_with(ruby))
                 .unwrap();
+            ctx.inject_globals(hash).expect("inject should succeed");
 
-            let result = ctx.await_eval_with_globals("fail_if_neg(n)".to_string(), hash);
-            assert!(result.is_err(), "should propagate ValueError");
+            let future_result =
+                crate::eval::await_eval_with_globals("fail_if_neg(n)", ctx.globals, api);
+
+            match future_result {
+                Err(_) => {} // eval itself failed
+                Ok(future) => {
+                    let tstate = api.save_thread();
+                    while !future.is_ready() {
+                        std::thread::sleep(std::time::Duration::from_millis(1));
+                    }
+                    let result = future.value();
+                    api.restore_thread(tstate);
+                    assert!(result.is_err(), "should propagate ValueError");
+                }
+            }
         });
     }
 
@@ -768,6 +796,9 @@ mod tests {
             api.release_gil(gil);
 
             let tstate = api.save_thread();
+            while !future.is_ready() {
+                std::thread::sleep(std::time::Duration::from_millis(1));
+            }
             let result = future.value().expect("future should resolve");
             drop(future);
             api.restore_thread(tstate);

data/ext/rubyx/src/eval.rs

@@ -1,3 +1,4 @@
+use crate::future::RubyxFuture;
 use crate::python_api::PythonApi;
 use crate::python_ffi::PyObject;
 use crate::python_guard::PyGuard;
@@ -234,55 +235,6 @@ fn inject_globals(
     Ok(())
 }
 
-/// Run a Python coroutine with asyncio.run() and return the result.
-/// The coroutine must already be a PyObject (not code string).
-/// Caller must hold the GIL.
-fn run_asyncio(coroutine: *mut PyObject, api: &'static PythonApi) -> Result<Value, magnus::Error> {
-    let ruby = Ruby::get().map_err(|e| Error::new(runtime_error(), e.to_string()))?;
-
-    let asyncio = api
-        .import_module("asyncio")
-        .map_err(|e| Error::new(runtime_error(), e.to_string()))?;
-    let run_fn = api.object_get_attr_string(asyncio, "run");
-
-    if run_fn.is_null() {
-        api.clear_error();
-        api.decref(asyncio);
-        return Err(Error::new(runtime_error(), "asyncio.run not found"));
-    }
-
-    let args = unsafe { (api.py_tuple_new)(1) };
-    if args.is_null() {
-        api.decref(run_fn);
-        api.decref(asyncio);
-        return Err(Error::new(
-            runtime_error(),
-            "Failed to allocate argument tuple",
-        ));
-    }
-    api.incref(coroutine);
-    unsafe { (api.py_tuple_set_item)(args, 0, coroutine) };
-
-    let result = api.object_call(run_fn, args, std::ptr::null_mut());
-    api.decref(args);
-    api.decref(run_fn);
-    api.decref(asyncio);
-
-    if result.is_null() {
-        let err = if let Some(exc) = PythonApi::extract_exception(api) {
-            exc.to_string()
-        } else {
-            "Python async call failed".to_string()
-        };
-        return Err(Error::new(runtime_error(), err));
-    }
-
-    let wrapper = RubyxObject::new(result, api)
-        .ok_or_else(|| Error::new(runtime_error(), "Failed to wrap async result"))?;
-
-    Ok(wrapper.into_value_with(&ruby))
-}
-
 /// Rubyx.await(coroutine) — takes a RubyxObject wrapping a Python coroutine,
 /// runs it with asyncio.run(), and returns the result.
 pub(crate) fn rubyx_await(coroutine: Value) -> Result<Value, magnus::Error> {
@@ -290,10 +242,10 @@ pub(crate) fn rubyx_await(coroutine: Value) -> Result<Value, magnus::Error> {
     let api = crate::api();
     let gil = api.ensure_gil();
 
-    let result = run_asyncio(obj.as_ptr(), api);
+    let future = RubyxFuture::from_coroutine(obj.as_ptr(), api);
 
     api.release_gil(gil);
-    result
+    crate::future::value_nonblocking(&future)
 }
 
 /// Eval code in context globals to get a coroutine, then run it with asyncio.run().
@@ -302,7 +254,7 @@ pub(crate) fn await_eval_with_globals(
     code: &str,
     globals: *mut PyObject,
     api: &'static PythonApi,
-) -> Result<Value, magnus::Error> {
+) -> Result<RubyxFuture, magnus::Error> {
     let py_coroutine = match api.run_string(code, PY_EVAL_INPUT, globals, globals) {
         Ok(obj) if !obj.is_null() => obj,
         Ok(_) => {
@@ -315,12 +267,12 @@ pub(crate) fn await_eval_with_globals(
             };
             return Err(err);
         }
-        Err(e) => return Err(Error::new(runtime_error(), e)),
+        Err(e) => {
+            return Err(magnus::Error::new(runtime_error(), e));
+        }
     };
-
-    let result = run_asyncio(py_coroutine, api);
-    api.decref(py_coroutine);
-    result
+    let future = RubyxFuture::from_coroutine(py_coroutine, api);
+    Ok(future)
 }
 
 pub(crate) fn rubyx_await_with_globals(
@@ -331,14 +283,16 @@ pub(crate) fn rubyx_await_with_globals(
     let gil = api.ensure_gil();
 
     let globals = make_globals(api);
-    let result = match inject_globals(&globals, globals_hash, api) {
+    let future = match inject_globals(&globals, globals_hash, api) {
         Ok(()) => await_eval_with_globals(&code, globals.ptr(), api),
         Err(e) => Err(e),
     };
     drop(globals);
-
     api.release_gil(gil);
-    result
+    match future {
+        Ok(future) => Ok(crate::future::value_nonblocking(&future)?),
+        Err(e) => Err(e),
+    }
 }
 
 pub(crate) fn rubyx_async_await_with_globals(