Module: RubyPython

Defined in:
lib/rubypython.rb,
lib/rubypython/macros.rb,
lib/rubypython/python.rb,
lib/rubypython/options.rb,
lib/rubypython/version.rb,
lib/rubypython/pyobject.rb,
lib/rubypython/operators.rb,
lib/rubypython/conversion.rb,
lib/rubypython/blankobject.rb,
lib/rubypython/pymainclass.rb,
lib/rubypython/pythonerror.rb,
lib/rubypython/rubypyproxy.rb

Overview

This module provides the direct user interface for the RubyPython extension.

RubyPython interfaces to the Python C API via the Python module using the Ruby FFI gem. However, the end user should only worry about dealing with the methods made avaiable via the RubyPython module.

Usage

It is important to remember that the Python Interpreter must be started before the bridge is functional. This will start the embedded interpreter. If this approach is used, the user should remember to call RubyPython.stop when they are finished with Python. Legacy Mode vs Normal Mode

By default RubyPython always returns a proxy class which refers method calls to the wrapped Python object. If you instead would like RubyPython to aggressively attempt conversion of return values, as it did in RubyPython 0.2.x, then you should set RubyPython.legacy_mode to true. In this case RubyPython will attempt to convert any return value from Python to a native Ruby type, and only return a proxy if conversion is not possible. For further examples see RubyPython.legacy_mode.

Examples:

RubyPython.start
cPickle = RubyPython.import "cPickle"
puts cPickle.dumps("RubyPython is awesome!").rubify
RubyPython.stop

Defined Under Namespace

Modules: Conversion, LegacyMode, Macros, Operators, Python, VERSION Classes: BlankObject, PyMainClass, PyObject, PythonError, RubyPyClass, RubyPyInstance, RubyPyModule, RubyPyProxy

Constant Summary collapse

NEED_RELOAD =

A list of options which require the Python library to be reloaded.

[
  :python_exe,
  :python_lib
]
PyMain = 
PyMainClass.instance

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.legacy_mode ⇒ Boolean

Determines whether RubyPython is operating in Normal Mode or Legacy Mode. If legacy_mode is true, RubyPython switches into a mode compatible with versions < 0.3.0. All Python objects returned by method invocations are automatically converted to natve Ruby Types if RubyPython knows how to do this. Only if no such conversion is known are the objects wrapped in proxy objects. Otherwise RubyPython automatically wraps all returned objects as an instance of RubyPyProxy or one of its subclasses.

Examples:

Normal Mode

RubyPython.start
string = RubyPython.import 'string'
ascii_letters = string.ascii_letters # Here ascii_letters is a proxy object
puts ascii_letters.rubify # we use the rubify method to convert it to a
                          # native type
RubyPython.stop

Legacy Mode

RubyPython.legacy_mode = true
RubyPython.start
string = RubyPython.import 'string'
ascii_letters = string.ascii_letters # Here ascii_letters is a native ruby string
puts ascii_letters # No explicit conversion is neccessary
RubyPython.stop

Returns:

  • (Boolean) 


65
66
67
 
# File 'lib/rubypython.rb', line 65

def legacy_mode
  @legacy_mode
end

Class Method Details

.clear_options ⇒ void

This method returns an undefined value.

Reset the options hash.



64
65
66
 
# File 'lib/rubypython/options.rb', line 64

def clear_options
  @options.clear
end

.configure(opts = {}) ⇒ Hash

Allows one to set options for RubyPython’s execution. Parameters may be set either by supplying a hash argument or by supplying a block and calling setters on the provided OpenStruct.

Examples:

irb(main):001:0> RubyPython.run do
irb(main):002:1*   RubyPython.import('sys').version.rubify.to_f
irb(main):003:1> end
=> 2.7
irb(main):004:0> RubyPython.configure :python_exe => 'python2.6'
=> {:python_exe=>"python2.6"}
irb(main):005:0> RubyPython.run do
irb(main):006:1*   RubyPython.import('sys').version.rubify.to_f
irb(main):007:1> end
=> 2.6

Parameters:

  • opts (Hash) (defaults to: {}) —

    a hash of options to set

Options Hash (opts):

  • :python_exe (String) —

    The python executable for the python version you wish to use. Can be anything in your execution path as well as a local or relative path.

  • :python_lib (String) —

    The full path to the python library you wish to load.

Returns:

  • (Hash) —

    a copy of the new options hash



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/rubypython/options.rb', line 35

def configure(opts={})
  old_values = @options.select { |k,v| NEED_RELOAD.include? k }

  if block_given?
    ostruct = OpenStruct.new @options
    yield ostruct
    @options = Hash[*ostruct.instance_eval do 
      @table.map do |k, v|
        [k.to_sym, v]
      end.flatten
    end]
  end
  @options.merge!(opts)

  @reload = true if NEED_RELOAD.any? { |k| @options[k] != old_values[k] } 
  options
end

.import(mod_name) ⇒ RubyPyModule

Import a Python module into the interpreter and return a proxy object for it. This is the preferred way to gain access to Python object. module

Parameters:

  • mod_name (String) —

    the name of the module to import

Returns:



109
110
111
112
113
114
115
116
 
# File 'lib/rubypython.rb', line 109

def import(mod_name)
  pModule = Python.PyImport_ImportModule mod_name
  if(PythonError.error?)
    raise PythonError.handle_error
  end
  pymod = PyObject.new pModule
  RubyPyModule.new(pymod)
end

.options ⇒ Hash

Returns a copy of the hash currently being used to determine run options. This allows the user to determine what options have been set. Modification of options should be done via the configure method.

Returns:

  • (Hash) —

    a copy of the current options hash



58
59
60
 
# File 'lib/rubypython/options.rb', line 58

def options
  @options.dup
end

.run(&block) ⇒ Object

The same as session except that the block is executed within the scope of the RubyPython module.

Returns:

  • the result of evaluating the given block.



134
135
136
137
138
139
 
# File 'lib/rubypython.rb', line 134

def run(&block)
  start
  result = module_eval(&block)
  stop
  result
end

.session ⇒ Object

Execute the given block, starting the Python interperter before its execution and stopping the interpreter after its execution. The last expression of the block is returned; be careful that this is not a Python object as it will become invalid when the interpreter is stopped.

Parameters:

  • block (Block) —

    the code to be executed while the interpreter is running

Returns:

  • the result of evaluating the given block



124
125
126
127
128
129
 
# File 'lib/rubypython.rb', line 124

def session
  start
  result = yield
  stop
  result
end

.start ⇒ Boolean

Starts ups the Python interpreter. This method must be run before using any Python code. The only alternatives are use of the session and run methods. If the Python interpreter needs to be loaded or reloaded, it will be done here.

Returns:

  • (Boolean) —

    returns true if the interpreter was started here and false otherwise



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/rubypython.rb', line 73

def start
  unless @loaded
    @loaded = true
    reload_library
  end
  if Python.Py_IsInitialized != 0
    return false
  end
  if @reload
    reload_library
    @reload = false
  end
  Python.Py_Initialize
  notify :start
  true
end

.stop ⇒ Boolean

Stops the Python interpreter if it is running. Returns true if the intepreter is stopped by this invocation. All wrapped Python objects should be considered invalid after invocation of this method.

Returns:

  • (Boolean) —

    returns true if the interpreter was stopped here and false otherwise



95
96
97
98
99
100
101
102
 
# File 'lib/rubypython.rb', line 95

def stop
  if Python.Py_IsInitialized !=0
    Python.Py_Finalize
    notify :stop
    return true
  end
  false
end