Module: RubyPython

Defined in:
lib/rubypython.rb,
lib/rubypython/macros.rb,
lib/rubypython/python.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

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) 


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

def legacy_mode
  @legacy_mode
end

Class Method Details

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



100
101
102
103
104
105
106
107
 
# File 'lib/rubypython.rb', line 100

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

.run(&block) ⇒ Object

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



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

def run(&block)
  start
  result = module_eval(&block)
  stop
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



115
116
117
118
119
120
 
# File 'lib/rubypython.rb', line 115

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.

Returns:

  • (Boolean) —

    returns true if the interpreter was started here and false otherwise



70
71
72
73
74
75
76
 
# File 'lib/rubypython.rb', line 70

def start
  if Python.Py_IsInitialized != 0
    return false
  end
  Python.Py_Initialize
  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



83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/rubypython.rb', line 83

def stop
  if Python.Py_IsInitialized !=0
    PyMain.main = nil
    PyMain.builtin = nil
    RubyPython::Operators.send :class_variable_set, '@@operator', nil
    Python.Py_Finalize
    RubyPython::PyObject::AutoPyPointer.current_pointers.clear
    return true
  end
  false
end