rubyx-py 0.1.1-aarch64-linux → 0.2.1-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78e55da43621514d0e7e8457b19a61a11940c227acbc58e2b2bc74cb69f02c14
-  data.tar.gz: eaa68df2386ad15bbb8330ca66e3d4c226e9b5705af0c2c36f1eca44040f274a
+  metadata.gz: 25cb549b764a4c233144af01c9fe0fc86709ba1c9c6bbc8ac01a4f60f030ffe6
+  data.tar.gz: 812f62a87103e7c52e2503054942645aaa6e9e5f5c0ddf63d20a484c6f9da1b2
 SHA512:
-  metadata.gz: 27fb43d1eb60920ca4cd78b65e682200c4f5a0297a1ecb3b258b77a6ed6971957ab3e94184df168e185752181bcb74493f686a25acff8931a67773f39af145e1
-  data.tar.gz: 7bd77196083a87066eb1e384bbe2df8f49dae64995028bc58ee327fc646a80ce6a110674593d114ee383c421321de0adbc593dd2cafb0c2e5fb8cfe7290075fd
+  metadata.gz: ea4882957a0522567d2dbdfe7c9a64b0d7bfa23522928d7bb39d22c763b5d936d348b1dfa762e4197bd67174aa3d2e4a26928f0586c93bc267d7d56ca02a7563
+  data.tar.gz: 34b00a5cdcf9347ec8a812ac30ad7e6142ff435768e66d582c0e6125632a637ae136b813f1ffba4af3b3c19779674968e088f5014bfa9383a8c76a9c9be437bc

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/lib/rubyx/railtie.rb

@@ -14,7 +14,8 @@ module Rubyx
 
     # Register rake tasks
     rake_tasks do
-      load 'rubyx/tasks/rubyx.rake'
+      task_file = File.expand_path('tasks/rubyx.rake', __dir__)
+      load task_file if File.exist?(task_file)
     end
   end
 end

data/lib/rubyx/tasks/rubyx.rake

@@ -0,0 +1,127 @@
+namespace :rubyx do
+  desc 'Initialize Python environment (downloads uv and Python if needed)'
+  task init: :environment do
+    Rubyx::Rails.init!
+    puts '[Rubyx] Python environment initialized successfully.'
+  end
+
+  desc 'Check Python environment health'
+  task check: :environment do
+    puts 'Checking Python environment...'
+    puts
+
+    # Check uv
+    system_uv = `which uv 2>/dev/null`.strip
+    uv_available = !system_uv.empty? && File.exist?(system_uv)
+    puts "uv available: #{uv_available ? "Yes (#{system_uv})" : 'No (will auto-download)'}"
+
+    begin
+      Rubyx::Rails.ensure_initialized!
+      puts 'Python initialized: Yes'
+    rescue => e
+      puts "Python initialized: No (#{e.message})"
+      puts
+      puts 'Run `rake rubyx:init` to initialize.'
+      exit 1
+    end
+
+    begin
+      Rubyx.eval('1 + 1')
+      puts 'Basic eval: OK'
+    rescue => e
+      puts "Basic eval: FAILED (#{e.message})"
+      exit 1
+    end
+
+    begin
+      gen = Rubyx.eval("import sys\niter([sys.version.split()[0]])")
+      version = Rubyx.stream(gen).first
+      puts "Import sys: OK (Python #{version})"
+    rescue => e
+      puts "Import sys: FAILED (#{e.message})"
+      exit 1
+    end
+
+    puts
+    puts 'All checks passed!'
+  end
+
+  desc 'Show Rubyx configuration and status'
+  task status: :environment do
+    config = Rubyx::Rails.configuration
+
+    puts 'Rubyx Status'
+    puts '=' * 40
+
+    puts "Initialized: #{Rubyx::Rails.initialized?}"
+    puts
+
+    puts 'Configuration:'
+    puts "  pyproject_path:    #{config.pyproject_path || '(not set)'}"
+    puts "  pyproject_content: #{config.pyproject_content ? '(inline, %d bytes)' % config.pyproject_content.length : '(not set)'}"
+    puts "  auto_init:         #{config.auto_init}"
+    puts "  force_reinit:      #{config.force_reinit}"
+    puts "  uv_version:        #{config.uv_version}"
+    puts "  debug:             #{config.debug}"
+    puts "  python_paths:      #{config.python_paths.inspect}"
+    puts "  uv_path:           #{config.uv_path || '(auto-download)'}"
+    puts "  uv_args:           #{config.uv_args.inspect}"
+    puts
+
+    if config.pyproject_path
+      exists = File.exist?(config.pyproject_path.to_s)
+      puts "pyproject.toml exists: #{exists}"
+    end
+
+    if config.pyproject_path
+      venv_dir = File.join(File.dirname(config.pyproject_path.to_s), '.venv')
+      puts ".venv exists: #{Dir.exist?(venv_dir)}"
+    end
+
+    system_uv = `which uv 2>/dev/null`.strip
+    puts "System uv: #{!system_uv.empty? ? system_uv : '(not found)'}"
+  end
+
+  desc 'List installed Python packages'
+  task packages: :environment do
+    Rubyx::Rails.ensure_initialized!
+
+    gen = Rubyx.eval(<<~PY)
+      import pkg_resources
+      packages = sorted([f"{d.project_name}=={d.version}" for d in pkg_resources.working_set])
+      iter(packages)
+    PY
+
+    puts 'Installed Python packages:'
+    Rubyx.stream(gen).each { |pkg| puts "  #{pkg}" }
+  rescue => e
+    begin
+      gen = Rubyx.eval(<<~PY)
+        from importlib.metadata import distributions
+        packages = sorted([f"{d.metadata['Name']}=={d.metadata['Version']}" for d in distributions()])
+        iter(packages)
+      PY
+
+      puts 'Installed Python packages:'
+      Rubyx.stream(gen).each { |pkg| puts "  #{pkg}" }
+    rescue => e2
+      puts "Could not list packages: #{e2.message}"
+    end
+  end
+
+  desc 'Clear the Rubyx cache (re-download uv + Python on next init)'
+  task clear_cache: :environment do
+    cache_dir = File.join(
+      ENV.fetch('XDG_CACHE_HOME', File.join(Dir.home, '.cache')),
+      'rubyx'
+    )
+
+    if Dir.exist?(cache_dir)
+      require 'fileutils'
+      FileUtils.rm_rf(cache_dir)
+      puts "[Rubyx] Cache cleared: #{cache_dir}"
+    else
+      puts '[Rubyx] No cache directory found.'
+    end
+  end
+end

data/lib/rubyx/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Rubyx
-  VERSION = "0.1.1".freeze
-end
+  VERSION = "0.2.1".freeze
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubyx-py
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: aarch64-linux
 authors:
 - Naiker
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-03-24 00:00:00.000000000 Z
+date: 2026-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -47,6 +47,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - README.md
+- docs/assets/logo.png
 - ext/rubyx/src/python/sync_adapter.py
 - lib/generators/rubyx/install_generator.rb
 - lib/generators/rubyx/templates/example.py
@@ -62,6 +63,7 @@ files:
 - lib/rubyx/error.rb
 - lib/rubyx/rails.rb
 - lib/rubyx/railtie.rb
+- lib/rubyx/tasks/rubyx.rake
 - lib/rubyx/uv.rb
 - lib/rubyx/version.rb
 homepage: https://github.com/yinho999/rubyx