rubypython 0.3.2 → 0.5.0

data/lib/rubypython/legacy.rb

@@ -1,39 +1,38 @@
 require 'rubypython'
 
-#A quick way to activate legacy mode for your project. Requiring 
-#'rubypython/legacy' automatically activates legacy_mode as described 
-#in the documentation for {RubyPython}. If you wish to run your 
-#project in legacy mode you can require 'rubypython/legacy' instead of 
-#'rubypython'
+# A quick way to active <em>Legacy Mode</em> for a project. Requiring
+# +'rubypython/legacy' automatically activates +RubyPython.legacy_mode+ on
+# the project.
 #
-#@example Default Behavior
-#  irb(main):001:0> require 'rubypython'
-#  => true
-#  irb(main):002:0> RubyPython.start
-#  => true
-#  irb(main):003:0> RubyPython::PyMain.float(42).is_a? RubyPython::RubyPyProxy
-#  => true
-#  irb(main):004:0> RubyPython.stop
-#  => true
-# 
-#@example Legacy Mode
-#  irb(main):001:0> require 'rubypython/legacy'
-#  => true
-#  irb(main):002:0> RubyPython.start
-#  => true
-#  irb(main):003:0> RubyPython::PyMain.float(42).is_a? Float
-#  => true
-#  irb(main):004:0> RubyPython.stop
-#  => true
+# This mode may be phased out for RubyPython 1.0.
+#
+# === Default
+#   require 'rubypython'
+#
+#   RubyPython.session do
+#     string = RubyPython.import 'string'
+#     ascii_letters = string.ascii_letters
+#     puts ascii_letters.isalpha # => True
+#     puts ascii_letters.rubify.isalpha # throws NoMethodError
+#   end
+#
+# === Legacy Mode
+#   require 'rubypython/legacy'
+#
+#   RubyPython.session do
+#     string = RubyPython.import 'string'
+#     ascii_letters = string.ascii_letters
+#     puts ascii_letters.isalpha # throws NoMethodError
+#   end
 module RubyPython::LegacyMode
-  class << self
-    def setup_legacy
-      RubyPython.legacy_mode = true
-    end
+  # Enables +RubyPython.legacy_mode+.
+  def self.setup_legacy
+    RubyPython.legacy_mode = true
+  end
 
-    def teardown_legacy
-      RubyPython.legacy_mode = false
-    end
+  # Disables +RubyPython.legacy_mode+.
+  def self.teardown_legacy
+    RubyPython.legacy_mode = false
   end
 end
 

data/lib/rubypython/macros.rb

@@ -1,47 +1,56 @@
 require 'ffi'
 require 'rubypython/python'
 
-module RubyPython
-  #Contains Python C API macros reimplmented in Ruby. For internal use only.
-  module Macros
-    def self.Py_TYPE(pObjPointer)
-      pStruct = Python::PyObjectStruct.new pObjPointer
-      pStruct[:ob_type]
-    end
+# Contains Python C API macros reimplemented in Ruby. For internal use only.
+module RubyPython::Macros #:nodoc:
+  # Returns the reference count for the provided pointer.
+  def self.Py_REFCNT(pObjPointer)
+    pStruct = RubyPython::Python::PyObjectStruct.new pObjPointer
+    pStruct[:ob_refcnt]
+  end
 
-    def self.PyObject_TypeCheck(pObject, pTypePointer)
-      if Py_TYPE(pObject) == pTypePointer
-        1
-      else
-        0
-      end
-    end
+  # Returns the object type for the provided pointer.
+  def self.Py_TYPE(pObjPointer)
+    pStruct = RubyPython::Python::PyObjectStruct.new pObjPointer
+    pStruct[:ob_type]
+  end
 
-    def self.Py_True
-      Python.Py_TrueStruct.to_ptr
-    end
+  # This has been modified from the C API macro to allow for multiple
+  # pointer objects to be passed. It simplifies a number of checks.
+  def self.PyObject_TypeCheck(pObject, pTypePointer)
+    type = self.Py_TYPE(pObject)
 
-    def self.Py_False
-      Python.Py_ZeroStruct.to_ptr
+    [ pTypePointer ].flatten.each do |pointer|
+      return 1 if type == pointer
     end
 
-    def self.Py_None
-      Python.Py_NoneStruct.to_ptr
-    end
+    return 0
+  end
 
-    def self.Py_RETURN_FALSE
-      Python.Py_IncRef(self.Py_False)
-      self.Py_False
-    end
+  def self.Py_True
+    RubyPython::Python.Py_TrueStruct.to_ptr
+  end
 
-    def self.Py_RETURN_TRUE
-      Python.Py_IncRef(self.Py_True)
-      self.Py_True
-    end
+  def self.Py_False
+    RubyPython::Python.Py_ZeroStruct.to_ptr
+  end
 
-    def self.Py_RETURN_NONE
-      Python.Py_IncRef(self.Py_None)
-      self.Py_None
-    end
+  def self.Py_None
+    RubyPython::Python.Py_NoneStruct.to_ptr
+  end
+
+  def self.Py_RETURN_FALSE
+    RubyPython::Python.Py_IncRef(self.Py_False)
+    self.Py_False
+  end
+
+  def self.Py_RETURN_TRUE
+    RubyPython::Python.Py_IncRef(self.Py_True)
+    self.Py_True
+  end
+
+  def self.Py_RETURN_NONE
+    RubyPython::Python.Py_IncRef(self.Py_None)
+    self.Py_None
   end
 end

data/lib/rubypython/operators.rb

@@ -1,118 +1,120 @@
-module RubyPython
-  #A mixin module to provide method delegation to a proxy class. This is done
-  #either by delegating to methods defined on the wrapped object or by using the
-  #Python _operator_ module. A large number of the methods are dynamically
-  #generated and so their documentation is not provided here. In general all
-  #operators that can be overloaded are delegated.
-  module Operators
-    #Provides access to the Python _operator_ module.
-    #@return[RubyPython::RubyPyModule]
-    def self.operator_
-      @@operator ||= RubyPython.import('operator')
-    end
-
-    #Creates a method to delegate a binary operation. The result of the
-    #operation will follow the conversion rules appropriate to the current mode
-    #of operation as set by {RubyPython.legacy_mode}.
-    #@param[Symbol, String] rname The name of the Ruby method for this operation
-    #@param[String] pname The name of the Python magic method to which this
-    #method should be delegated.
-    def self.bin_op rname, pname
-      define_method rname.to_sym do |other|
-        self.__send__ pname, other
-      end
-    end
+# A mixin module to provide method delegation to a proxy class. This is done
+# either by delegating to methods defined on the wrapped object or by using
+# the \Python _operator_ module. A large number of the methods are
+# dynamically generated and so their documentation is not provided here. In
+# general all operators that can be overloaded are delegated.
+module RubyPython::Operators
+  # Provides access to the \Python _operator_ module.
+  def self.operator_
+    @@operator ||= RubyPython.import('operator')
+  end
 
-    #Creates a method to delegate a relational operator. The result of the
-    #delegated method will always be converted to a Ruby type so that simple
-    #boolean testing may occur. These methods are implemented with calls the
-    #_operator_ module.
-    #@param[Symbol, String] rname The name of the Ruby method for this operation
-    #@param[String] pname The name of the Python magic method to which this
-    #method should be delegated.
-    def self.rel_op rname, pname
-      define_method rname.to_sym do |other|
-        Operators.operator_.__send__(pname, self, other).rubify
-      end
+  # Creates a method to delegate a binary operation. The result of the
+  # operation will follow the conversion rules appropriate to the current
+  # mode of operation as set by {RubyPython.legacy_mode}.
+  # [rname] The name of the Ruby method for this operation. Can be either a
+  # Symbol or a String.
+  # [pname] The name of the \Python magic method to which this method should
+  # be delegated.
+  def self.bin_op(rname, pname)
+    define_method rname.to_sym do |other|
+      self.__send__(pname, other)
     end
+  end
 
-    #Creates a method to delegate a relational operator. The result of the
-    #operation will follow the conversion rules appropriate to the current mode
-    #of operation as set by {RubyPython.legacy_mode}. These methods are
-    #implemented with calls the _operator_ module.
-    #@param[Symbol, String] rname The name of the Ruby method for this operation
-    #@param[String] pname The name of the Python magic method to which this
-    #method should be delegated.
-    def self.unary_op rname, pname
-      define_method rname.to_sym do 
-        Operators.operator_.__send__(pname, self)
-      end
+  # Creates a method to delegate a relational operator. The result of the
+  # delegated method will always be converted to a Ruby type so that simple
+  # boolean testing may occur. These methods are implemented with calls the
+  # _operator_ module.
+  #
+  # [rname] The name of the Ruby method for this operation. Can be a Symbol
+  # or a String.
+  # [pname] The name of the \Python magic method to which this method should
+  # be delegated.
+  def self.rel_op(rname, pname)
+    define_method rname.to_sym do |other|
+      RubyPython::Operators.operator_.__send__(pname, self, other).rubify
     end
+  end
 
-
-    [
-      [:+, '__add__'],
-      [:-, '__sub__'],
-      [:*, '__mul__'],
-      [:/, '__div__'],
-      [:&, '__and__'],
-      [:^, '__xor__'],
-      [:%, '__mod__'],
-      [:**, '__pow__'],
-      [:>>, '__rshift__'],
-      [:<<, '__lshift__'],
-      [:|, '__or__']
-    ].each do |args|
-      bin_op *args
+  # Creates a method to delegate a relational operator. The result of the
+  # operation will follow the conversion rules appropriate to the current
+  # mode of operation as set by {RubyPython.legacy_mode}. These methods are
+  # implemented with calls the _operator_ module.
+  # [rname] The name of the Ruby method for this operation. Can be a Symbol
+  # or a String.
+  # [pname] The name of the \Python magic method to which this method should
+  # be delegated.
+  def self.unary_op(rname, pname)
+    define_method rname.to_sym do
+      RubyPython::Operators.operator_.__send__(pname, self)
     end
+  end
 
-    [
-      [:~, :__invert__],
-      [:+@, :__pos__],
-      [:-@, :__neg__]
-    ].each do |args|
-      unary_op *args
-    end
+  [
+    [:+, '__add__'],
+    [:-, '__sub__'],
+    [:*, '__mul__'],
+    [:/, '__div__'],
+    [:&, '__and__'],
+    [:^, '__xor__'],
+    [:%, '__mod__'],
+    [:**, '__pow__'],
+    [:>>, '__rshift__'],
+    [:<<, '__lshift__'],
+    [:|, '__or__']
+  ].each do |args|
+    bin_op *args
+  end
 
-    [
-      [:==, 'eq'],
-      [:<, 'lt'],
-      [:<=, 'le'],
-      [:>, 'gt'],
-      [:>=, 'ge'],
-      [:equal?, 'is_']
-    ].each do |args|
-      rel_op *args
-    end
+  [
+    [:~, :__invert__],
+    [:+@, :__pos__],
+    [:-@, :__neg__]
+  ].each do |args|
+    unary_op *args
+  end
 
-    alias :eql? :==
+  [
+    [:==, 'eq'],
+    [:<, 'lt'],
+    [:<=, 'le'],
+    [:>, 'gt'],
+    [:>=, 'ge'],
+    [:equal?, 'is_']
+  ].each do |args|
+    rel_op *args
+  end
 
-    #Delegates object indexed access to the wrapped Python object.
-    def [](index)
-      self.__getitem__ index
-    end
+  # Delegates object indexed access to the wrapped \Python object.
+  def [](index)
+    self.__getitem__ index
+  end
 
-    #Delegates setting of various indices to the wrapped Python object.
-    def []=(index, value)
-      self.__setitem__ index, value
-    end
+  # Delegates setting of various indices to the wrapped \Python object.
+  def []=(index, value)
+    self.__setitem__ index, value
+  end
 
-    #Delegates membership testing to Python.
-    def include?(item)
-      self.__contains__(item).rubify
-    end
+  # Delegates membership testing to \Python.
+  def include?(item)
+    self.__contains__(item).rubify
+  end
 
-    #Delegates Comparison to Python.
-    def <=>(other)
-      PyMain.cmp(self, other)
-    end
+  # Delegates Comparison to \Python.
+  def <=>(other)
+    RubyPython::PyMain.cmp(self, other)
+  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 self.update(status)
-      @@operator = nil 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 self.update(status)
+    case status
+    when :stop
+      @@operator = nil
     end
-
   end
+
+  # Aliases eql? to == for Python objects.
+  alias_method :eql?, :==
 end

data/lib/rubypython/options.rb

@@ -1,69 +1,66 @@
+require 'ostruct'
+
 module RubyPython
-  #A hash for storing RubyPython execution options.
+  # A hash for storing RubyPython execution options.
   @options = {}
 
-  #A list of options which require the Python library to be reloaded.
-  NEED_RELOAD = [
-    :python_exe,
-    :python_lib
-  ]
+  # A list of options which require the \Python library to be reloaded.
+  NEED_RELOAD = [ :python_exe ] #:nodoc
+  # 20110316 AZ: This option has been removed because it isn't supported in
+  # the current code.
+  # :python_lib -> The full path to the python library you wish to load.
 
   class << self
-    #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.
-    #@param [Hash] opts a hash of options to set
-    #@option opts [String] :python_exe 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.
-    #@option opts [String] :python_lib The full path to the python 
-    #  library you wish to load.
-    #@return [Hash] a copy of the new options 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. Returns a copy of the
+    # updated options hash.
+    #
+    # [options] A Hash of options to set.
     #
-    #@example
-    #  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
-    #  
-    def configure(opts={})
-      old_values = @options.select { |k,v| NEED_RELOAD.include? k }
+    # The option currently supported is:
+    # [:python_exe] The name of or path to the \Python executable for the
+    # version of \Python you wish to use.
+    # 
+    #   RubyPython.run do
+    #     RubyPython.import('sys').version.rubify.to_f # => 2.7
+    #   end
+    #
+    #   RubyPython.configure :python_exe => 'python2.6'
+    #   # => { :python_exe => "python2.6" }
+    #   RubyPython.run do
+    #     RubyPython.import('sys').version.rubify.to_f # => 2.6
+    #   end
+    #   
+    # The options hash can also be passed directly to +RubyPython.start+,
+    # +RubyPython.session+, or +RubyPython.run+.
+    def configure(options = {})
+      old_values = Hash[*@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]
+        olist = ostruct.instance_variable_get('@table').map { |k, v| [ k.to_sym, v ] }
+        @options = Hash[*olist]
       end
-      @options.merge!(opts)
+      @options.merge!(options)
 
       @reload = true if NEED_RELOAD.any? { |k| @options[k] != old_values[k] } 
       options
     end
 
-    #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.
-    #@return [Hash] a copy of the current 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.
     def options
       @options.dup
     end
 
-    #Reset the options hash.
-    #@return [void]
+    # Reset the options hash.
+    # @return [void]
     def clear_options
+      @reload = @options.keys.any? { |k| NEED_RELOAD.include? k }
       @options.clear
     end
-
   end
 end