contents

  1. Description
  2. Where
  3. Synopsis
    1. Basic Usage
    2. Specific Python Version
    3. VirtualEnv
    4. Iterator support
    5. Python to Ruby callbacks
    6. Python-style Generators
    7. Python named arguments (Experimental)
  4. Features / Problems
    1. Features
    2. Known Problems
  5. What's planned
    1. Python 3
    2. Simpler Imports
    3. Catch Exceptions from Ruby
  6. Requirements
    1. Python Support
    2. Ruby Support
    3. OS Support
  7. Install
  8. Contributors
  9. License

description

RubyPython is a bridge between the Ruby and Python interpreters. It embeds a running Python interpreter in the Ruby application’s process using FFI and provides a means for wrapping, converting, and calling Python objects and methods.

RubyPython uses FFI to marshal the data between the Ruby and Python VMs and make Python calls. You can:

where

The RubyPython homepage, project description, and main downloads can be found on RubyForge.

Source is kept in sync between Bitbucket and GitHub, but the Bitbucket repository is the canonical repository and where the issue tracker resides. We use Hg-Git to keep the two repositories in sync.

synopsis

RubyPython is fairly easy to start using; there are three phases to its use:

  1. Start the Python interpreter (RubyPython.start).

  2. Import and use Python code (RubyPython.import).

  3. Stop the Python interpreter (RubyPython.stop).

There are also two methods, RubyPython.session and RubyPython.run that will start before running the code provided in the block and stop it afterwards.

basic usage

require "rubypython"

RubyPython.start # start the Python interpreter

cPickle = RubyPython.import("cPickle")
p cPickle.dumps("Testing RubyPython.").rubify

RubyPython.stop # stop the Python interpreter

specific python version

require "rubypython"

RubyPython.start(:python_exe => "python2.7") # Can also be a full path

cPickle = RubyPython.import("cPickle")
p cPickle.dumps("Testing RubyPython.").rubify

RubyPython.stop # stop the Python interpreter

virtualenv

# Easy
RubyPython.start_from_virtualenv("/path/to/virtualenv")

# Or verbose
RubyPython.start(:python_exe => "/path/to/virtualenv/bin/python")
RubyPython.activate

iterator support

# Python
def readfile():
  for line in open("/some/file"):
    yield line

# Ruby
readfile.to_enum.each do |line|
  puts line
end

# Python
def iterate_list():
  for item in [ 1, 2, 3 ]:
    yield item

# Ruby
items = []
iterate_list.to_enum.each { |item| items << item }
puts items == [ 1, 2, 3 ] # => true

python to ruby callbacks

# Python
def simple_callback(callback, value):
  return callback(value)

# Ruby
simple_callback(lambda { |v| v * v }, 4) # => 16

def triple(v)
  v * 3
end

simple_callback(method(:triple), 4) # => 12

python-style generators

# Python
def test_generator(callback):
  for i in callback():
    print "Got %d" % i

# Ruby 1.9.2 or later
test_generator(RubyPython.generator do
  (0..10).each { |i| RubyPython.yield i }
end)

python named arguments (experimental)

This format is experimental and may be changed.

# Python
def foo(arg1, arg2):
  pass

# Ruby
foo!(:arg2 => "bar2", :arg1 => "bar1")

# with Ruby 1.9
foo!(arg2: "bar2", arg1: "bar1")

features / problems

features

experimental features

known problems

what’s planned

There are features that are not currently supported in RubyPython that may be considered for future releases, dependent on need, interest, and solutions.

python 3

We do plan on working this, but as none of the projects any of us are working on require Python 3 as of yet, this is not yet started.

simpler imports

It might be nice to have some nice import helpers provided by RubyPython to make the interface more seamless and provide advanced import features:

import aliasing

# Python
from mod2.mod1 import sym as mysym

# Ruby
py :from => "mod2.mod1", :import => "sym", :as => "mysym"
py :from => "mod2.mod1", :import => :sym, :as => :mysym
py :from => [ :mod2, :mod1 ], :import => :sym, :as => :mysym

# Python
import mod1 as mymod

# Ruby
py :import => "mod1", :as => "mymod"
py :import => :mod1, :as => :mymod

# Python
from mod2.mod1 import *

# Ruby
py :from => "mod2.mod1", :import => :*
pyrequire "mod2/mod1" # ruby style imports

catch exceptions from ruby

# Python
class MyFirstException(Exception):
  pass

class MySecondException(MyFirstException):
  pass

def test():
  raise MySecondException

# Ruby
begin
  test
rescue MyFirstException => e
  # We may need to work out name collisions
  puts e.message
end

requirements

python support

RubyPython has been tested with the C-based Python interpreter (cpython), versions 2.4 through 2.7. Work is planned to enable Python 3 support, but has not yet been started. If you’re interested in helping us enable Python 3 support, please let us know.

ruby support

It should work with other implementations that support the Ruby FFI gem with no modification.

os support

RubyPython has been extensively tested on Mac OS 10.5 and 10.6, and Ubuntu 10.10 (64-bit Intel). If your platform has a DLL or shared object version of Python and supports the FFI gem, it should work. Feedback on other platforms is always welcome.

install

gem install rubypython

contributors

RubyPython has a growing list of contributors.

license

This software is available under the terms of the MIT license.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.