rubypython 0.2.11 → 0.3.0

data/lib/rubypython/pyobject.rb

@@ -0,0 +1,203 @@
+require 'rubypython/python'
+require 'rubypython/macros'
+require 'rubypython/conversion'
+require 'ffi'
+
+module RubyPython
+  #This object is an opaque wrapper around the C PyObject\* type used by the
+  #python C API. This class **should not** be used by the end user. They
+  #should instead make use of the {RubyPyProxy} class and its
+  #subclasses.
+  class PyObject
+
+    #@private
+    #
+    #This class wraps C PyObject\*s so that the Python reference count is
+    #automatically decreased when the Ruby object referencing them 
+    #goes out of scope.
+    class AutoPyPointer < FFI::AutoPointer
+      class << self
+        #Keeps track of which objects are associated with the currently running
+        #Python interpreter, so that RubyPython knows not to try to decrease the
+        #reference counts of the others when garbage collecting.
+        attr_accessor :current_pointers
+
+        #When used along with the FFI Library method is executed whenever a
+        #pointer is garbage collected so that cleanup can be done. In our case
+        #we decrease the reference count of the held pointer as long as the
+        #object is still good. There is really no reason the end-user would need
+        #to the use this method directly.
+        def release(pointer)
+          obj_id = pointer.object_id
+          if (Python.Py_IsInitialized != 0) and @current_pointers.delete(obj_id)
+            Python.Py_DecRef pointer 
+          end
+        end
+      end
+
+      self.current_pointers = {}
+    end
+
+    #The FFI::Pointer object which represents the Python PyObject\*.
+    attr_reader :pointer
+
+    #@param [FFI::Pointer, other] pointer objects passed in to the constructor
+    #   are just assigned to the pointer attribute of the instance. All other
+    #   objects are converted via {Conversion.rtopObject} before being assigned.
+    def initialize(rObject)
+      if rObject.kind_of? FFI::AutoPointer 
+        new_pointer = FFI::Pointer.new rObject
+        @pointer = AutoPyPointer.new new_pointer
+        xIncref
+      elsif rObject.kind_of? FFI::Pointer
+        @pointer = AutoPyPointer.new rObject
+      else
+        @pointer = AutoPyPointer.new Conversion.rtopObject(rObject)
+      end
+      AutoPyPointer.current_pointers[@pointer.object_id] = true
+    end
+
+    #Attempts to convert the wrapped object to a native ruby type.
+    #@return a ruby version of the wrapped object
+    def rubify
+      Conversion.ptorObject @pointer
+    end
+
+    #Tests whether the wrapped object has a given attribute
+    #@param [String] the name of the attribute to look up
+    #@return [Boolean]
+    def hasAttr(attrName)
+      Python.PyObject_HasAttrString(@pointer, attrName) == 1
+    end
+
+    #Retrieves an object from the wrapped python object
+    #@param [String] the name of attribute to fetch
+    #@return [PyObject] a Ruby wrapper around the fetched attribute
+    def getAttr(attrName)
+      pyAttr = Python.PyObject_GetAttrString @pointer, attrName
+      self.class.new pyAttr
+    end
+
+    #Sets the an attribute of the wrapped Python object
+    #@param [String] attrName the name of of attribute to set
+    #@param [PyObject] rbPyAttr a {PyObject} wrapper around the value we wish to
+    #set the attribute to.
+    #@return [Boolean] returns true if the attribute is sucessfully set.
+    def setAttr(attrName, rbPyAttr)
+      Python.PyObject_SetAttrString(@pointer, attrName, rbPyAttr.pointer) != -1
+    end
+
+    #Calls the wrapped Python object with the supplied arguments.
+    #@param [PyObject] rbPyArgs a {PyObject} wrapping a tuple of the supplied
+    #arguments
+    #@return [PyObject] a {PyObject} wrapper around the returned
+    #object (this may be NULL).
+    def callObject(rbPyArgs)
+      pyReturn = Python.PyObject_CallObject(@pointer, rbPyArgs.pointer)
+      self.class.new pyReturn
+    end
+
+    #Decrease the reference count of the wrapped object
+    #@return [void]
+    def xDecref
+      AutoPyPointer.release(@pointer)
+      @pointer.free
+    end
+
+    #Increase the reference count of the wrapped object
+    #@return [void]
+    def xIncref
+      Python.Py_IncRef @pointer
+    end
+
+    #Tests whether the wrapped object is NULL.
+    def null?
+      @pointer.null?
+    end
+
+    #@return [Number]
+    def cmp(other)
+      Python.PyObject_Compare @pointer, other.pointer 
+    end
+
+    #Tests whether the wrapped object is a function or a method. This is not the
+    #same as {#callable?} as many other Python objects are callable.
+    def function_or_method?
+      isFunc = (Macros.PyObject_TypeCheck(@pointer, Python.PyFunction_Type.to_ptr) != 0)
+      isMethod = (Macros.PyObject_TypeCheck(@pointer, Python.PyMethod_Type.to_ptr) != 0)
+      isFunc or isMethod
+    end
+
+    #Is the wrapped object callable?
+    def callable?
+      Python.PyCallable_Check(@pointer) != 0
+    end
+
+    #Tests whether the wrapped object is a Python class (both new and old
+    #style).
+    def class?
+      isClassObj = (Macros.PyObject_TypeCheck(@pointer, Python.PyClass_Type.to_ptr) == 1)
+      isTypeObj = (Macros.PyObject_TypeCheck(@pointer, Python.PyType_Type.to_ptr) == 1)
+      isTypeObj or isClassObj
+    end
+
+    #Manipulates the supplied {PyObject} instance such that it is suitable to
+    #passed to {#callObject}. If `rbObject` is a tuple then the argument passed
+    #in is returned. If it is a list then the list is converted to a tuple.
+    #Otherwise returns a tuple with one element: `rbObject`.
+    #@param [PyObject] rbObject the argment to be turned into a tuple.
+    #@return [PyObject<tuple>]
+    def self.makeTuple(rbObject)
+      pTuple = nil
+
+      if Macros.PyObject_TypeCheck(rbObject.pointer, Python.PyList_Type.to_ptr) != 0
+        pTuple = Python.PySequence_Tuple(rbObject.pointer)
+      elsif Macros.PyObject_TypeCheck(rbObject.pointer, Python.PyTuple_Type.to_ptr) != 0
+        pTuple = rbObject.pointer
+      else
+        pTuple = Python.PyTuple_Pack(1, :pointer, rbObject.pointer)
+      end
+
+      self.new pTuple
+    end
+
+    #Wraps up the supplied arguments in Python list.
+    #@return [PyObject<list>]
+    def self.newList(*args)
+      rbList = self.new Python.PyList_New(args.length)
+
+      args.each_with_index do |el, i|
+        Python.PyList_SetItem rbList.pointer, i, el.pointer
+      end
+
+      rbList
+    end
+
+    #Converts the supplied arguments to PyObject instances.
+    #@return [Array<PyObject>]
+    def self.convert(*args)
+      args.map! do |arg|
+        if arg.kind_of? PyObject
+          arg
+        elsif arg.kind_of? RubyPyProxy
+          arg.pObject
+        else
+          PyObject.new arg
+        end
+      end
+    end
+
+    #Takes an array of wrapped Python objects and wraps them in a tuple such
+    #that they may be passed to {#callObject}.
+    #@param [Array<PyObject>] args the arguments to be inserted into the tuple.
+    #@return [PyObject<tuple>]
+    def self.buildArgTuple(*args)
+      pList = PyObject.newList(*args)
+      pTuple = PyObject.makeTuple(pList)
+      pList.xDecref
+      pTuple
+    end
+
+  end
+
+end

data/lib/rubypython/python.rb

@@ -0,0 +1,111 @@
+require 'ffi'
+require 'open3'
+
+module RubyPython
+  #This module provides access to the Python C API functions via the Ruby ffi
+  #gem. Documentation for these functions may be found [here](http://docs.python.org/c-api/). Likewise the FFI gem documentation may be found [here](http://rdoc.info/projects/ffi/ffi).
+  module Python
+    extend FFI::Library
+    PYTHON_VERSION = Open3.popen3("python --version") { |i,o,e| e.read}.chomp.split[1].to_f
+    PYTHON_NAME = "python#{PYTHON_VERSION}"
+    LIB_NAME = "lib#{PYTHON_NAME}"
+    LIB_EXT = FFI::Platform::LIBSUFFIX
+    LIB = File.join(`python -c "import sys; print(sys.prefix)"`.chomp,
+      "lib", "#{PYTHON_NAME}", "config", "#{LIB_NAME}.#{LIB_EXT}")
+    @ffi_libs = [FFI::DynamicLibrary.open(LIB, FFI::DynamicLibrary::RTLD_LAZY|FFI::DynamicLibrary::RTLD_GLOBAL)]
+
+    #The class is a little bit of a hack to extract the address of global
+    #structs. If someone knows a better way please let me know.
+    class DummyStruct < FFI::Struct
+      layout :dummy_var, :int
+    end
+
+    #Python interpreter startup and shutdown
+    attach_function :Py_IsInitialized, [], :int
+    attach_function :Py_Initialize, [], :void
+    attach_function :Py_Finalize, [], :void
+
+    #Module methods
+    attach_function :PyImport_ImportModule, [:string], :pointer
+
+    #Object Methods
+    attach_function :PyObject_HasAttrString, [:pointer, :string], :int
+    attach_function :PyObject_GetAttrString, [:pointer, :string], :pointer
+    attach_function :PyObject_SetAttrString, [:pointer, :string, :pointer], :int
+
+    attach_function :PyObject_Compare, [:pointer, :pointer], :int
+
+    attach_function :PyObject_CallObject, [:pointer, :pointer], :pointer
+    attach_function :PyCallable_Check, [:pointer], :int
+
+    ###Python To Ruby Conversion
+    #String Methods
+    attach_function :PyString_AsString, [:pointer], :string
+    attach_function :PyString_FromString, [:string], :pointer
+
+    #List Methods
+    attach_function :PyList_GetItem, [:pointer, :int], :pointer
+    attach_function :PyList_Size, [:pointer], :int
+    attach_function :PyList_New, [:int], :pointer
+    attach_function :PyList_SetItem, [:pointer, :int, :pointer], :void
+
+    #Integer Methods
+    attach_function :PyInt_AsLong, [:pointer], :long
+    attach_function :PyInt_FromLong, [:long], :pointer
+
+    attach_function :PyLong_AsLong, [:pointer], :long
+    attach_function :PyLong_FromLong, [:pointer], :long
+
+    #Float Methods
+    attach_function :PyFloat_AsDouble, [:pointer], :double
+    attach_function :PyFloat_FromDouble, [:double], :pointer
+
+    #Tuple Methods
+    attach_function :PySequence_List, [:pointer], :pointer
+    attach_function :PySequence_Tuple, [:pointer], :pointer
+    attach_function :PyTuple_Pack, [:int, :varargs], :pointer
+
+    #Dict/Hash Methods
+    attach_function :PyDict_Next, [:pointer, :pointer, :pointer, :pointer], :int
+    attach_function :PyDict_New, [], :pointer
+    attach_function :PyDict_SetItem, [:pointer, :pointer, :pointer], :int
+    attach_function :PyDict_Contains, [:pointer, :pointer], :int
+    attach_function :PyDict_GetItem, [:pointer, :pointer], :pointer
+
+    #Error Methods
+    attach_function :PyErr_Fetch, [:pointer, :pointer, :pointer], :void
+    attach_function :PyErr_Occurred, [], :pointer
+    attach_function :PyErr_Clear, [], :void
+
+    #Reference Counting
+    attach_function :Py_IncRef, [:pointer], :void
+    attach_function :Py_DecRef, [:pointer], :void
+
+    #Type Objects
+    attach_variable :PyString_Type, DummyStruct.by_value
+    attach_variable :PyList_Type, DummyStruct.by_value
+    attach_variable :PyInt_Type, DummyStruct.by_value
+    attach_variable :PyLong_Type, DummyStruct.by_value
+    attach_variable :PyFloat_Type, DummyStruct.by_value
+    attach_variable :PyTuple_Type, DummyStruct.by_value
+    attach_variable :PyDict_Type, DummyStruct.by_value
+    attach_variable :PyFunction_Type, DummyStruct.by_value
+    attach_variable :PyMethod_Type, DummyStruct.by_value
+    attach_variable :PyType_Type, DummyStruct.by_value
+    attach_variable :PyClass_Type, DummyStruct.by_value
+
+    attach_variable :Py_TrueStruct, :_Py_TrueStruct, DummyStruct.by_value
+    attach_variable :Py_ZeroStruct, :_Py_ZeroStruct, DummyStruct.by_value
+    attach_variable :Py_NoneStruct, :_Py_NoneStruct, DummyStruct.by_value
+
+    #This is an implementation of the basic structure of a Python PyObject
+    #struct. The C struct is actually much larger, but since we only access
+    #the first two data members via FFI and always deal with struct pointers
+    #there is no need to mess around with the rest of the object.
+    class PyObjectStruct < FFI::Struct
+      layout :ob_refcnt, :int,
+        :ob_type, :pointer
+    end
+
+  end
+end

data/lib/rubypython/pythonerror.rb

@@ -0,0 +1,78 @@
+require 'rubypython/python'
+require 'rubypython/macros'
+
+
+module RubyPython
+  
+  #Raised when an error occurs in the Python interpreter.
+  class PythonError < Exception
+    
+    #@param [String] typeName the class name of the Python error
+    #@param [String] msg the message attached to the Python error
+    def initialize(typeName, msg)
+      @type = typeName
+      super([typeName, msg].join(': '))
+    end
+
+    #This method should be called when an error has occured in the
+    #Python interpreter. This acts as factory function for PythonError
+    #objects. The function fetchs calls {fetch} to get the error
+    #information from the Python interpreter and uses this to build
+    #a PythonError object. It then calls {clear} to clear the error
+    #flag of the python interpreter
+    #@return [PythonError] an error enscapsulating the Python error
+    def self.handle_error
+      rbType, rbValue, rbTraceback = fetch()
+
+      if not rbValue.null?
+        msg = rbValue.getAttr("__str__").callObject PyObject.buildArgTuple
+        msg = msg.rubify
+      else
+        msg = nil
+      end
+      
+      #Decrease the reference count. This will happen anyway when they go
+      #out of scope but might as well.
+      rbValue.xDecref
+      rbTraceback.xDecref
+      pyName = rbType.getAttr("__name__")
+
+      rbType.xDecref
+      rbName = pyName.rubify
+      pyName.xDecref
+
+      PythonError.clear
+
+      PythonError.new(rbName, msg)
+    end
+
+    #A wrapper to the Python C API PyErr_Fetch function.
+    #@return [Array<PyObject>] an array containing three {PyObject} instances.
+    #   representing the Type, Value, and stacktrace of the python
+    #   error respectively.
+    def self.fetch
+      typePointer = FFI::MemoryPointer.new :pointer
+      valuePointer = FFI::MemoryPointer.new :pointer
+      tracebackPointer = FFI::MemoryPointer.new :pointer
+
+      Python.PyErr_Fetch typePointer, valuePointer, tracebackPointer
+
+      rbType = PyObject.new typePointer.read_pointer
+      rbValue = PyObject.new valuePointer.read_pointer
+      rbTraceback = PyObject.new tracebackPointer.read_pointer
+      [rbType, rbValue, rbTraceback]
+    end
+
+    #Determines whether an error has occured in the python interpreter.
+    def self.error?
+      !Python.PyErr_Occurred.null?
+    end
+
+    #Resets the Python interpreter error flag
+    #@return [void]
+    def self.clear
+      Python.PyErr_Clear
+    end
+
+  end
+end

data/lib/rubypython/rubypyproxy.rb

@@ -0,0 +1,214 @@
+require 'rubypython/pythonerror'
+require 'rubypython/pyobject'
+require 'rubypython/conversion'
+require 'rubypython/operators'
+require 'rubypython/blankobject'
+
+module RubyPython
+  #This is the object that the end user will most often be interacting
+  #with. It holds a reference to an object in the Python VM an delegates
+  #method calls to it, wrapping and returning the results. The user should
+  #not worry about reference counting of this object an instance
+  #will decrement its objects reference count when it is garbage collected.
+  #
+  #Note: All RubyPyProxy objects become invalid when the Python interpreter
+  #is halted.
+  class RubyPyProxy < BlankObject
+    include Operators
+
+    attr_reader :pObject
+
+    def initialize(pObject)
+      if pObject.kind_of? PyObject
+        @pObject = pObject
+      else
+        @pObject = PyObject.new pObject
+      end
+    end
+
+    #Handles the job of wrapping up anything returned by a {RubyPyProxy}
+    #instance. The behavior differs depending on the value of
+    #{RubyPython.legacy_mode}. If legacy mode is inactive, every returned
+    #object is wrapped by an instance of {RubyPyProxy}. If legacy mode is
+    #active, RubyPython first attempts to convert the returned object to a
+    #native Ruby type, and then only wraps the object if this fails.
+    def _wrap(pyobject)
+      if pyobject.class?
+        RubyPyClass.new(pyobject)
+      elsif RubyPython.legacy_mode
+        pyobject.rubify
+      else
+        RubyPyProxy.new(pyobject)
+      end
+    rescue Conversion::UnsupportedConversion => exc
+      RubyPyProxy.new pyobject
+    end
+
+    reveal(:respond_to?)
+
+    #Moves the old respond_to? method to is_real_method?
+    alias :is_real_method? :respond_to?
+
+    #RubyPython checks the attribute dictionary of the wrapped object
+    #to check whether it will respond to a method call. This should not
+    #return false positives but it may return false negatives. The builitin Ruby
+    #respond_to? method has been aliased to is_real_method?. 
+    def respond_to?(mname)
+      return true if is_real_method?(mname)
+      mname = mname.to_s
+      return true if mname.end_with? '='
+      @pObject.hasAttr(mname)
+    end
+
+    #Implements the method call delegation.
+    def method_missing(name, *args, &block)
+      name = name.to_s
+
+      if(name.end_with? "?")
+        begin
+          RubyPyProxy.reveal(name.to_sym)
+          return self.__send__(name.to_sym, *args, &block)
+        rescue RuntimeError => exc
+          raise NoMethodError.new(name) if exc.message =~ /Don't know how to reveal/
+          raise
+        end
+      end
+
+
+      if(name.end_with? "=")
+        setter = true
+        name.chomp! "="
+      else
+        setter=false
+      end
+
+      if(!@pObject.hasAttr(name) and !setter)
+        raise NoMethodError.new(name)
+      end
+
+
+      args = PyObject.convert(*args)
+
+      if setter
+        return @pObject.setAttr(name, args[0]) 
+      end
+
+      pFunc = @pObject.getAttr(name)
+
+      if pFunc.callable?
+        if args.empty? and pFunc.class?
+          pReturn = pFunc
+        else
+          pTuple = PyObject.buildArgTuple(*args)
+          pReturn = pFunc.callObject(pTuple)
+          if(PythonError.error?)
+            raise PythonError.handle_error
+          end
+        end
+      else
+        pReturn = pFunc
+      end
+
+      return _wrap(pReturn)
+    end
+
+    #RubyPython will attempt to translate the wrapped object into a native
+    #Ruby object. This will only succeed for simple builtin type.
+    def rubify
+      @pObject.rubify
+    end
+
+    #Returns the string representation of the wrapped object via a call to the
+    #object's \_\_repr\_\_ method. Falls back on the default Ruby behavior when
+    #this method cannot be found.
+    #
+    #@return [String]
+    def inspect
+      self.__repr__.rubify rescue _inspect
+    rescue
+      class << self; define_method :_inspect, RubyPyProxy.find_hidden_method(:inspect); end
+      _inspect
+    end
+
+    #Returns the string representation of the wrapped object via a call to the
+    #object's \_\_str\_\_ method. Falls back on the default Ruby behavior when
+    #this method cannot be found.
+    #
+    #@return [String]
+    def to_s
+      self.__str__.rubify rescue _to_s
+    rescue
+      class << self; define_method :_to_s, RubyPyProxy.find_hidden_method(:to_s); end
+      _to_s
+    end
+
+    #Converts the wrapped Python object to a Ruby Array. Note that this only converts
+    #one level, so a nested array will remain a proxy object. Only wrapped
+    #objects which have an \_\_iter\_\_ method may be converted using to_a.
+    #
+    #Note that for Dict objects, this method returns what you would get in
+    #Python, not in Ruby i.e. a_dict.to_a returns an array of the
+    #dictionary's keys.
+    #@return [Array<RubyPyProxy>]
+    #@example List
+    #    irb(main):001:0> RubyPython.start
+    #    => true
+    #    irb(main):002:0> a_list = RubyPython::RubyPyProxy.new [1, 'a', 2, 'b']
+    #    => [1, 'a', 2, 'b']
+    #    irb(main):003:0> a_list.kind_of? RubyPython::RubyPyProxy
+    #    => true
+    #    irb(main):004:0> a_list.to_a
+    #    => [1, 'a', 2, 'b']
+    #    irb(main):005:0> RubyPython.stop
+    #    => true
+    #    
+    #@example Dict
+    #    irb(main):001:0> RubyPython.start
+    #    => true
+    #    irb(main):002:0> a_dict = RubyPython::RubyPyProxy.new({1 => '2', :three => [4,5]})
+    #    => {1: '2', 'three': [4, 5]}
+    #    irb(main):003:0> a_dict.kind_of? RubyPython::RubyPyProxy
+    #    => true
+    #    irb(main):004:0> a_dict.to_a
+    #    => [1, 'three']
+    #    irb(main):005:0> RubyPython.stop
+    #    => true
+    
+    def to_a
+      iter = self.__iter__
+      ary = []
+      loop do
+        ary << iter.next()
+      end
+    rescue PythonError => exc
+      raise if exc.message !~ /StopIteration/
+      ary
+    end
+
+  end
+
+  #A class to wrap Python Modules. It behaves exactly the same as {RubyPyProxy}.
+  #It is just here for Bookkeeping and aesthetics.
+  class RubyPyModule < RubyPyProxy
+  end
+
+  #A class to wrap Python Classes.
+  class RubyPyClass < RubyPyProxy
+
+    #Create an instance of the wrapped class. This is a workaround for the fact
+    #that Python classes are meant to be callable.
+    def new(*args)
+      args = PyObject.convert(*args)
+      pTuple = PyObject.buildArgTuple(*args)
+      pReturn = @pObject.callObject(pTuple)
+      if PythonError.error?
+        raise PythonError.handle_error
+      end
+      RubyPyInstance.new pReturn
+    end
+  end
+
+  #An object representing an instance of a Python Class.
+  class RubyPyInstance < RubyPyProxy
+  end
+end