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.
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
-
.legacy_mode ⇒ Boolean
Determines whether RubyPython is operating in Normal Mode or Legacy Mode.
Class Method Summary collapse
-
.clear_options ⇒ void
Reset the options hash.
-
.configure(opts = {}) ⇒ Hash
Allows one to set options for RubyPython’s execution.
-
.import(mod_name) ⇒ RubyPyModule
Import a Python module into the interpreter and return a proxy object for it.
-
.options ⇒ Hash
Returns a copy of the hash currently being used to determine run options.
-
.run(&block) ⇒ Object
The same as RubyPython.session except that the block is executed within the scope of the RubyPython module.
-
.session ⇒ Object
Execute the given block, starting the Python interperter before its execution and stopping the interpreter after its execution.
-
.start ⇒ Boolean
Starts ups the Python interpreter.
-
.stop ⇒ Boolean
Stops the Python interpreter if it is running.
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.
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 @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.
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] } 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
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.
58 59 60 |
# File 'lib/rubypython/options.rb', line 58 def @options.dup end |
.run(&block) ⇒ Object
The same as session except that the block is executed within the scope of the RubyPython module.
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.
124 125 126 127 128 129 |
# File 'lib/rubypython.rb', line 124 def session start result = yield stop result end |
.start ⇒ Boolean
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.
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 |