rubyx-py 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 779abf6ff7235f29633d44399308ee23f3a6244b4f23e3f0fb0a056914602ea7
-  data.tar.gz: a08a4226433cecb9533b09e23e5867f248b5fcec4b994dc3623a7f5698c33475
+  metadata.gz: cf3d6decfdb8c4bf6dd12f891389511ce96deeaf3efffb1664bb35d6b9b6066f
+  data.tar.gz: 7dcbdcceac38a4a8dc0908e0f11fc19237080025fbb36e8d7cb8d38d0c8ec58f
 SHA512:
-  metadata.gz: 85de3fdcbe4f96fc99db882a0e06c25347f31cb5e1d474e0d330698be781ee215163590ff68ed368aa9ecff3dd605dfd509349458307e33eedfff6c9137c4473
-  data.tar.gz: 2ed6beee3da490dda53cb6d49897d3c092870404e1f93c53d2e0fdeb22a1bf59159c14a67ab60411601f493fa06df4e19aae09ab4914bbe9c5413899f616f7ad
+  metadata.gz: 63cd8eba2c550fd0f4728d6a836ae3e2c80c0b81421830e07938a4d6acba4823e9cc11fb73e767384e33993c01fe4e4138097d9b26e53b361d87d46281ac8de4
+  data.tar.gz: 27c3168265e2e40186c2e0cb554192b03fd484400e34b788d125f9d4347abfecd9d3be260bf093deec48fc38f350c4655ce1e8632b3e7729f41cf967fce6d7ca

data/README.md

@@ -1,17 +1,21 @@
 <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.
+Powered by Rust for safety and performance. Built for Rails. Inspired by [Pythonx](https://github.com/livebook-dev/pythonx)
 
-[![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)
 [![Rust](https://img.shields.io/badge/Rust-powered-orange.svg)](https://www.rust-lang.org)
-
+> *"Rubyx showed that the proxy-object pattern works beautifully for cross-language bridges in Rust, and its magnus + rb-sys architecture is exactly what [Boax](https://intertwingly.net/blog/2026/03/25/Calling-JavaScript-from-Ruby.html) uses."*
+> 
+> — [Sam Ruby](https://en.wikipedia.org/wiki/Sam_Ruby), author of *Agile Web Development with Rails*
 </div>
 
 ---
@@ -34,15 +38,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 +94,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):
+    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] || 'World').to_ruby }
   end
 end
 ```
 
+```ruby
+Rails.application.routes.draw do
+  root "greetings#index"
+end
+```
+
 ### 2. Streaming — iterate a Python generator
 
 ```python
@@ -112,6 +125,7 @@ def count_up(n):
 ```
 
 ```ruby
+
 class CountController < ApplicationController
   include ActionController::Live
 
@@ -141,14 +155,15 @@ async def delayed_greet(name, seconds=1):
 ```
 
 ```ruby
+
 class TasksController < ApplicationController
   def show
     tasks = Rubyx.import('tasks')
 
     # Non-blocking — returns a Future immediately
-    future = Rubyx.async_await(tasks.delayed_greet(params[:name], seconds: 2))
+    future = Rubyx.async_await(tasks.delayed_greet(params[:name] || 'World', seconds: 2))
     do_other_work()
-    render json: { message: future.value.to_ruby }
+    render json: { message: future.await.to_ruby }
   end
 end
 ```
@@ -263,6 +278,7 @@ end
 ```
 
 ```ruby
+
 class ChatController < ApplicationController
   include ActionController::Live
 
@@ -317,7 +333,29 @@ Rubyx.eval("f'Hello, {name}!'", name: "World").to_ruby # => "Hello, World!"
 Rubyx.eval("max(items)", items: [3, 1, 4, 1, 5]).to_ruby # => 5
 ```
 
-Supports: Integer, Float, String, Symbol, Bool, nil, Array, Hash, and RubyxObject.
+Supports: Integer, Float, String, Symbol, Bool, nil, Array, Hash, binary String (ASCII-8BIT), and RubyxObject.
+
+## Bytes / Binary Data
+
+Python `bytes` and `bytearray` convert to Ruby `String` with `ASCII-8BIT` encoding. Ruby binary strings (`.b`) convert to Python `bytes`:
+
+```ruby
+# Python bytes → Ruby
+Rubyx.eval("b'hello'").to_ruby # => "hello" (ASCII-8BIT)
+Rubyx.eval("bytearray(b'hello')").to_ruby # => "hello" (ASCII-8BIT)
+
+# Ruby → Python
+ctx = Rubyx.context
+ctx.eval("type(data).__name__", data: "hello".b) # => "bytes"
+ctx.eval("type(data).__name__", data: "hello")   # => "str"
+
+# Roundtrip binary data
+ctx.eval("data", data: "\xff\x00\xfe".b).to_ruby # => "\xFF\x00\xFE" (ASCII-8BIT)
+
+# Works with Python stdlib
+ctx.eval("import base64")
+ctx.eval("base64.b64encode(raw)", raw: "Hello".b).to_ruby # => "SGVsbG8=" (ASCII-8BIT)
+```
 
 ## Python Objects
 
@@ -378,13 +416,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 +471,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              |                               |
 |--------------------------|-------------------------------|
@@ -456,6 +494,37 @@ svc.Analyzer([1, 2, 3]).summary.to_ruby # => {"count" => 3, "sum" => 6}
 | `.callable?`             | Check if callable             |
 | `.py_type`               | Python type name              |
 
+## Type Conversion
+
+| Python                | Ruby                         | Notes                  |
+|-----------------------|------------------------------|------------------------|
+| `int`                 | `Integer`                    |                        |
+| `float`               | `Float`                      |                        |
+| `str`                 | `String` (UTF-8)             |                        |
+| `bytes`               | `String` (ASCII-8BIT)        | binary data            |
+| `bytearray`           | `String` (ASCII-8BIT)        | binary data            |
+| `bool`                | `true` / `false`             |                        |
+| `None`                | `nil`                        |                        |
+| `list` / `tuple`      | `Array`                      |                        |
+| `dict`                | `Hash`                       |                        |
+| `set` / `frozenset`   | `Array`                      |                        |
+| everything else       | `RubyxObject`                | proxy to Python object |
+
+**Ruby → Python** (via globals/kwargs):
+
+| Ruby                           | Python      |
+|--------------------------------|-------------|
+| `Integer`                      | `int`       |
+| `Float`                        | `float`     |
+| `String` (UTF-8)               | `str`       |
+| `String` (ASCII-8BIT / `.b`)   | `bytes`     |
+| `true` / `false`               | `bool`      |
+| `nil`                          | `None`      |
+| `Array`                        | `list`      |
+| `Hash`                         | `dict`      |
+| `Symbol`                       | `str`       |
+| `RubyxObject`                  | original    |
+
 ## Requirements
 
 - Ruby >= 3.0

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(