= rubypython

== 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:

* Inherit from Python classes.
* Configure callbacks from Python.
* Run Python generators (on Ruby 1.9.2 or later).

== Where

* {RubyForge}[http://rubypython.rubyforge.org/]
* {RubyGems}[http://rubygems.org/gems/rubypython]
* {Bitbucket}[http://raineszm.bitbucket.org/rubypython/]
* {GitHub}[https://github.com/halostatue/rubypython]

The RubyPython homepage, project description, and main downloads can be found
on {RubyForge}[http://rubypython.rubyforge.org/].

Source is kept in sync between
{Bitbucket}[http://raineszm.bitbucket.org/rubypython/] and
{GitHub}[https://github.com/halostatue/rubypython], but the Bitbucket
repository is the canonical repository and where the {issue
tracker}[https://bitbucket.org/raineszm/rubypython/issues?status=new&status=open]
resides. We use {Hg-Git}[http://hg-git.github.com/] 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

* Simple two-way conversion of built-in types between Ruby and Python.
* Python module import and arbitrary method execution.
* Python objects can be treated as Ruby objects.
* Python's standard library available from within Ruby.
* Pass Ruby methods and procs as callbacks and call them from within Python
  code.
* Specify the Python executable to be loaded, including using virtualenv.

==== Experimental Features

* Calling Python methods or functions that expect keyword arguments, or call
  any Python method or function with named parameters.

    # Python
    def func(a, b, c):
      pass

    # Ruby
    func!(:b => 2, :c => 3, :a => 1) # => [ 1, 2, 3 ]

  While we are committed to keeping this feature in place, we have not yet
  determined that the form (+method!+) is the best way to achieve this
  functionality.

  This mechanism is experimental because the use of the bang at the end of the
  method to indicate the use of keyword arguments may not be the best use of
  that feature of Ruby naming.

* Changing Python interpreters in a single Ruby program. Under some
  circumstances, this will partially work. If a native Python extension has
  been imported (such as +cPickle+), there is a very high likelihood that there
  will be a segmentation fault because the newly loaded DLL will still refer to
  the other version's loaded extension. This is not a recommended workflow.

=== Known Problems

* Built-in Python methods requiring a top-level frame object (such as eval(),
  dir(), and the like) do not work properly at present.
* There is no support for passing complicated (non-basic) Ruby types to Python.

== 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 >= 2.4, < 3.0
* Ruby >= 1.8.6, or JRuby >= 1.6.0
* You must either have the ability to build the Ruby
  {FFI}[https://github.com/ffi/ffi] gem, version 1.0.7 or better in your
  environment or have a pre-built one that you can install.

=== 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
* Ruby 1.8.7 and 1.9.2 (MRI)
* JRuby 1.6.0

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

:include: Contributors.rdoc

:include: License.rdoc