rubypython 0.3.2 → 0.5.0

data/lib/rubypython/pygenerator.rb

@@ -0,0 +1,61 @@
+require "rubypython/python"
+require "rubypython/conversion"
+require 'rubypython/macros'
+require 'rubypython/conversion'
+require 'rubypython/pyobject'
+require "rubypython/pymainclass"
+require "rubypython/rubypyproxy"
+
+if defined? Fiber
+  module RubyPython
+    class << self
+      # Creates a \Python generator object called +rubypython_generator+
+      # that accepts a callback and yields to it.
+      #
+      # *Note*: This method only exists in the RubyPython if the Fiber
+      # exists.
+      def generator_type
+        @generator_type ||= lambda do
+          code = <<-EOM
+def rubypython_generator(callback):
+  while True:
+    yield callback()
+          EOM
+
+          globals = PyObject.new({ "__builtins__" => PyMain.builtin.pObject, })
+          empty_hash = PyObject.new({})
+          ptr = Python.PyRun_String(code, Python::PY_FILE_INPUT, globals.pointer, empty_hash.pointer)
+          ptr = Python.PyRun_String("rubypython_generator", Python::PY_EVAL_INPUT, globals.pointer, empty_hash.pointer)
+          raise PythonError.handle_error if PythonError.error?
+          RubyPyProxy.new(PyObject.new(ptr))
+        end.call
+      end
+
+      # Creates a Ruby lambda that acts like a \Python generator. Uses
+      # +RubyPython.generator_type+ and Fiber to work the generator as a
+      # coroutine.
+      #
+      # *Note*: This method only exists in the RubyPython if the Fiber
+      # exists.
+      def generator
+        return lambda do |*args|
+          fib = Fiber.new do
+            yield *args
+            Python.PyErr_SetNone(Python.PyExc_StopIteration)
+            FFI::Pointer::NULL
+          end
+          generator_type.__call__(lambda { fib.resume })
+        end
+      end
+
+      # Performs a +Fiber.yield+ with the provided arguments, continuing the
+      # coroutine execution of the generator.
+      #
+      # *Note*: This method only exists in the RubyPython if the Fiber
+      # exists.
+      def yield(*args)
+        Fiber.yield(*args)
+      end
+    end
+  end
+end

data/lib/rubypython/pymainclass.rb

@@ -2,35 +2,46 @@ require 'rubypython/blankobject'
 require 'singleton'
 
 module RubyPython
-  # A singleton object providing access to the python \_\_main\_\_ and
-  # \_\_builtin\_\_ modules.  This can be conveniently accessed through the
-  # already instaniated PyMain constant.  The \_\_main\_\_ namespace is
-  # searched before the \_\_builtin\_\_ namespace. As such, naming clashes will
-  # be resolved in that order.
+  # A singleton object providing access to the \Python <tt>__main__</tt> and
+  # <tt>__builtin__</tt> modules. This can be conveniently accessed through
+  # +PyMain+. The <tt>__main__</tt> namespace is searched before the
+  # <tt>__builtin__</tt> namespace. As such, naming clashes will be resolved
+  # in that order.
   #
-  # ## Block Syntax
-  # The PyMainClass object provides somewhat experimental block support.  A
+  #   RubyPython::PyMain.dir("dir") # => ['__add__', '__class__', … ]
+  #
+  # === Block Syntax
+  # PyMainClass provides experimental block support for called methods. A
   # block may be passed to a method call and the object returned by the
   # function call will be passed as an argument to the block.
-  class PyMainClass < BlankObject
+  #
+  #   RubyPython::PyMain.dir("dir") { |a| a.rubify.map { |e| e.to_sym } }
+  #     # => [:__add__, :__class__, :__contains__, … ]
+  class PyMainClass < RubyPython::BlankObject
     include Singleton
-    attr_writer :main, :builtin
-    
-    #@return [RubyPyModule] a proxy object wrapping the Python \__main\__
-    #  namespace.
-    def main 
-      @main||=RubyPython.import "__main__"
+
+    # Returns a proxy object wrapping the \Python <tt>__main__</tt> namespace.
+    def main
+      @main ||= RubyPython.import "__main__"
     end
-    
-    #@return [RubyPyModule] a proxy object wrapping the Python \__builtin\__
-    #  namespace.
+
+    # Returns a proxy object wrapping the \Python <tt>__builtin__</tt>
+    # namespace.
     def builtin
-      @builtin||=RubyPython.import "__builtin__"
+      @builtin ||= RubyPython.import "__builtin__"
     end
 
-    #Delegates any method calls on this object to the Python \__main\__ or
-    #\__builtin\__ namespaces. Method call resolution occurs in that order.
-    def method_missing(name,*args,&block)
+    # Delegates any method calls on this object to the \Python
+    # <tt>__main__</tt> or <tt>__builtin__</tt> namespaces, in that order. If
+    # a block is provided, the result of calling the \Python method will be
+    # yielded as an argument to the block.
+    #
+    # [name] The name of the \Python method or function to call.
+    # [args] The arguments to pass to the \Python method.
+    # [block] A block to execute with the result of calling the \Python
+    # method. If a block is provided, the result of the block is returned,
+    # not the result of the \Python method.
+    def method_missing(name, *args, &block)
       proxy = if main.respond_to?(name)
                 main
               elsif builtin.respond_to?(name)
@@ -41,22 +52,28 @@ module RubyPython
       result = if proxy.is_real_method?(name)
                  proxy.__send__(name, *args)
                else
-                 proxy.__send__(:method_missing, name,*args)
+                 proxy.__send__(:method_missing, name, *args)
                end
-      block ? block.call(result) : result
+
+      if block
+        block.call(result)
+      else
+        result
+      end
     end
 
-    #For internal use only. Called by {RubyPython} when the 
-    #interpreter is started or stopped so that the neccesary 
-    #preperation or cleanup can be done.
+    # Called by RubyPython when the interpreter is started or stopped so
+    # that the neccesary preperation or cleanup can be done. For internal
+    # use only.
     def update(status)
-      if status.equal? :stop
+      case status
+      when :stop
         @main = nil
         @builtin = nil
       end
     end
-
   end
 
-  PyMain = PyMainClass.instance
+  # The accessible instance of PyMainClass.
+  PyMain = RubyPython::PyMainClass.instance
 end

data/lib/rubypython/pyobject.rb

@@ -3,213 +3,229 @@ 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
-
-    #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
+# This object is an opaque wrapper around the C Py…Object types used by the
+# \Python C API.
+#
+# This class is *only* for RubyPython internal use.
+class RubyPython::PyObject # :nodoc: all
+  # This class wraps C <tt>Py…Object</tt>s so that the RubyPython::Python
+  # reference count is automatically decreased when the Ruby object
+  # referencing them goes out of scope.
+  class AutoPyPointer < FFI::AutoPointer # :nodoc:
+    class << self
+      # Keeps track of which objects are associated with the currently
+      # running RubyPython::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
+        deleted = @current_pointers.delete(obj_id)
+        if deleted and (RubyPython::Python.Py_IsInitialized != 0)
+          RubyPython::Python.Py_DecRef pointer
         end
+      end
 
-
-        #For internal use only. Called by {RubyPython} when the 
-        #interpreter is started or stopped so that the neccesary 
-        #preperation or cleanup can be done.
-        def update(status)
-          current_pointers.clear if status.equal? :stop
+      # Called by RubyPython when the interpreter is started or stopped so
+      # that the necessary preparation or cleanup can be done. For internal
+      # use only.
+      def update(status)
+        case status
+        when :stop
+          current_pointers.clear
         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
+    self.current_pointers = {}
+  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
+  # The AutoPyPointer object which represents the RubyPython::Python
+  # Py…Object.
+  attr_reader :pointer
+
+  # [rObject] FFI Pointer objects passed into the constructor are wrapped in
+  # an AutoPyPointer and assigned to the +#pointer+ attribute. Other objects
+  # are converted, if possible, from their Ruby types to their \Python types
+  # and wrapped in an AutoPyPointer. The conversion is done with
+  # +RubyPython::Conversion.rtopObject+.
+  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 RubyPython::Conversion.rtopObject(rObject)
+    end
+    AutoPyPointer.current_pointers[@pointer.object_id] = true
+  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
+  # Attempts to convert the wrapped object to a native ruby type. Returns
+  # either the Ruby object or the unmodified \Python object.
+  def rubify
+    RubyPython::Conversion.ptorObject @pointer
+  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
+  # Tests whether the wrapped \Python object has a given attribute. Returns
+  # +true+ if the attribute exists.
+  # [attrName] The name of the attribute to look up.
+  def hasAttr(attrName)
+    RubyPython::Python.PyObject_HasAttrString(@pointer, attrName) == 1
+  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
+  # Retrieves an object from the wrapped \Python object.
+  # [attrName] The name of the attribute to fetch.
+  def getAttr(attrName)
+    pyAttr = RubyPython::Python.PyObject_GetAttrString(@pointer, attrName)
+    self.class.new pyAttr
+  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
+  # Sets an attribute of the wrapped \Python object. Returns +true+ if the
+  # attribute was successfully set.
+  # [attrName] The name of the attribute to set.
+  # [rbPyAttr] A PyObject wrapper around the value that we wish to set the
+  # attribute to.
+  def setAttr(attrName, rbPyAttr)
+    RubyPython::Python.PyObject_SetAttrString(@pointer, attrName, rbPyAttr.pointer) != -1
+  end
 
-    #Decrease the reference count of the wrapped object
-    #@return [void]
-    def xDecref
-      AutoPyPointer.release(@pointer)
-      @pointer.free
-    end
+  # Calls the wrapped \Python object with the supplied arguments and keyword
+  # arguments. Returns a PyObject wrapper around the returned object, which
+  # may be +NULL+.
+  # [rbPyArgs]      A PyObject wrapping a Tuple of the supplied arguments.
+  # [rbPyKeywords]  A PyObject wrapping a Dict of keyword arguments.
+  def callObjectKeywords(rbPyArgs, rbPyKeywords)
+    pyReturn = RubyPython::Python.PyObject_Call(@pointer, rbPyArgs.pointer, rbPyKeywords.pointer)
+    self.class.new pyReturn
+  end
 
-    #Increase the reference count of the wrapped object
-    #@return [void]
-    def xIncref
-      Python.Py_IncRef @pointer
-    end
+  # Calls the wrapped \Python object with the supplied arguments. Returns a
+  # PyObject wrapper around the returned object, which may be +NULL+.
+  # [rbPyArgs]  A PyObject wrapping a Tuple of the supplied arguments.
+  def callObject(rbPyArgs)
+    pyReturn = RubyPython::Python.PyObject_CallObject(@pointer, rbPyArgs.pointer)
+    self.class.new pyReturn
+  end
 
-    #Tests whether the wrapped object is NULL.
-    def null?
-      @pointer.null?
-    end
+  # Decrease the reference count of the wrapped object.
+  def xDecref
+    AutoPyPointer.release(@pointer)
+    @pointer.free
+    nil
+  end
 
-    #@return [Number]
-    def cmp(other)
-      Python.PyObject_Compare @pointer, other.pointer 
-    end
+  # Increase the reference count of the wrapped object
+  def xIncref
+    RubyPython::Python.Py_IncRef @pointer
+    nil
+  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?
-      [
-        Python.PyFunction_Type,
-        Python.PyMethod_Type,
-        Python.PyCFunction_Type
-      ].each do |type|
-        return true if Macros.PyObject_TypeCheck(@pointer, type.to_ptr) != 0
-      end
+  # Tests whether the wrapped object is +NULL+.
+  def null?
+    @pointer.null?
+  end
 
-      false
-    end
+  # Performs a compare on two Python objects. Returns a value similar to
+  # that of the spaceship operator (<=>).
+  def cmp(other)
+    RubyPython::Python.PyObject_Compare @pointer, other.pointer
+  end
 
-    #Is the wrapped object callable?
-    def callable?
-      Python.PyCallable_Check(@pointer) != 0
-    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?
+    check = RubyPython::Macros.PyObject_TypeCheck(@pointer, [
+                                                  RubyPython::Python.PyFunction_Type.to_ptr,
+                                                  RubyPython::Python.PyCFunction_Type.to_ptr,
+                                                  RubyPython::Python.PyMethod_Type.to_ptr
+    ])
+    check != 0
+  end
+
+  # Is the wrapped object callable?
+  def callable?
+    RubyPython::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
+  # Returns the 'directory' of the RubyPython::Python object; similar to #methods in
+  # Ruby.
+  def dir
+    return self.class.new(RubyPython::Python.PyObject_Dir(@pointer)).rubify.map do |x|
+      x.to_sym
     end
+  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
+  # Tests whether the wrapped object is a RubyPython::Python class (both new
+  # and old style).
+  def class?
+    check = RubyPython::Macros.PyObject_TypeCheck(@pointer, [
+                                                  RubyPython::Python.PyClass_Type.to_ptr,
+                                                  RubyPython::Python.PyType_Type.to_ptr
+    ])
+    check != 0
+  end
+
+  # Manipulates the supplied PyObject instance such that it is suitable to
+  # passed to #callObject or #callObjectKeywords. 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+.
+  # [rbObject]  The argument to be turned into a Tuple.
+  def self.makeTuple(rbObject)
+    pTuple = nil
 
-      self.new pTuple
+    if RubyPython::Macros.PyObject_TypeCheck(rbObject.pointer, RubyPython::Python.PyList_Type.to_ptr) != 0
+      pTuple = RubyPython::Python.PySequence_Tuple(rbObject.pointer)
+    elsif RubyPython::Macros.PyObject_TypeCheck(rbObject.pointer, RubyPython::Python.PyTuple_Type.to_ptr) != 0
+      pTuple = rbObject.pointer
+    else
+      pTuple = RubyPython::Python.PyTuple_Pack(1, :pointer, rbObject.pointer)
     end
 
-    #Wraps up the supplied arguments in Python list.
-    #@return [PyObject<list>]
-    def self.newList(*args)
-      rbList = self.new Python.PyList_New(args.length)
+    self.new pTuple
+  end
 
-      args.each_with_index do |el, i|
-        Python.PyList_SetItem rbList.pointer, i, el.pointer
-      end
+  # Wraps up the supplied arguments in a \Python List.
+  def self.newList(*args)
+    rbList = self.new RubyPython::Python.PyList_New(args.length)
 
-      rbList
+    args.each_with_index do |el, i|
+      el.xIncref # PyList_SetItem steals references!
+      RubyPython::Python.PyList_SetItem rbList.pointer, i, el.pointer
     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
+    rbList
+  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
+  # Converts the supplied arguments to PyObject instances.
+  def self.convert(*args)
+    args.map do |arg|
+      if arg.kind_of? RubyPython::PyObject
+        arg
+      elsif arg.kind_of? RubyPython::RubyPyProxy
+        arg.pObject
+      else
+        RubyPython::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.
+  # [args] An array of PyObjects; the arguments to be inserted into the
+  # Tuple.
+  def self.buildArgTuple(*args)
+    pList = newList(*args)
+    pTuple = makeTuple(pList)
+    pList.xDecref
+    pTuple
+  end
 end