rubypython 0.5.3 → 0.6.0

data/History.rdoc

@@ -1,3 +1,35 @@
+=== 0.6 / 2011-04-17
+* Major Enhancements:
+  * Previous versions of RubyPython theoretically allowed the loading of
+    different Python interpreters during a single Ruby session. Because of the
+    likelihood of crashes, this functionality has been removed. Now, if you
+    attempt to start RubyPython more than once while specifying different
+    Python interpreters, RubyPython will print a warning and continue working
+    with the already loaded interpreter.
+  * The Python interpreter DLL will only be loaded once. It is configured with
+    a self-removing method, Interpreter#infect! instead of require/load reload
+    hacks.
+  * Removed RubyPython.configure; since the interpreter can only be configured
+    once, independent configuration no longer makes sense.
+* Minor Enhancements:
+  * RubyPython interpreter initialization is done with a Mutex synchronization
+    to ensure that only one Python interpreter DLL is loaded.
+  * Added RubyPython::Tuple, a simple subclass of ::Array that will correctly
+    be converted to a Python tuple object such that isinstance(x, tuple)
+    returns True.
+  * Renamed RubyPython::PythonExec to RubyPython::Interpreter. Added some
+    helper methods to assist with comparison. Construction is with an options
+    hash.
+  * The #update methods on Python interpreter observers are now private. This
+    is an implementation detail, not a public interface. (The methods have also
+    been renamed to #python_interpreter_update.)
+* Deprecation:
+  * RubyPython's legacy mode (automatic unboxing of Python proxy objects where
+    possible) has been deprecated and will be removed in the next non-bugfix
+    release after this version. Introduced a new private method
+    (RubyPython.legacy_mode?) to check if legacy mode is turned on so that the
+    deprecation warning is not printed in all uses of RubyPython.
+
 === 0.5.3 / 2011-10-22
 * Bug Fixes:
   * Improved 64-bit Python detection on Unixes with Linux-like semantics (e.g.,

data/Manifest.txt

@@ -1,7 +1,4 @@
 .autotest
-.gitignore
-.hgignore
-.hgtags
 .rspec
 Contributors.rdoc
 History.rdoc
@@ -14,17 +11,17 @@ autotest/discover.rb
 lib/rubypython.rb
 lib/rubypython/blankobject.rb
 lib/rubypython/conversion.rb
+lib/rubypython/interpreter.rb
 lib/rubypython/legacy.rb
 lib/rubypython/macros.rb
 lib/rubypython/operators.rb
-lib/rubypython/options.rb
 lib/rubypython/pygenerator.rb
 lib/rubypython/pymainclass.rb
 lib/rubypython/pyobject.rb
 lib/rubypython/python.rb
 lib/rubypython/pythonerror.rb
-lib/rubypython/pythonexec.rb
 lib/rubypython/rubypyproxy.rb
+lib/rubypython/tuple.rb
 lib/rubypython/type.rb
 spec/basic_spec.rb
 spec/callback_spec.rb

data/lib/rubypython.rb

@@ -15,39 +15,34 @@
 #   puts cPickle.dumps("RubyPython is awesome!").rubify
 #   RubyPython.stop
 module RubyPython
-  VERSION = '0.5.3' #:nodoc:
-
-  # Do not load the FFI interface by default. Wait until the user asks for
-  # it.
-  @load_ffi = false
-
-  # Indicates whether the \Python DLL has been loaded. For internal use
-  # only.
-  def self.load_ffi? #:nodoc:
-    @load_ffi
-  end
+  VERSION = '0.6.0'
 end
 
 require 'rubypython/blankobject'
-require 'rubypython/options'
+require 'rubypython/interpreter'
 require 'rubypython/python'
 require 'rubypython/pythonerror'
 require 'rubypython/pyobject'
 require 'rubypython/rubypyproxy'
 require 'rubypython/pymainclass'
 require 'rubypython/pygenerator'
+require 'rubypython/tuple'
+require 'thread'
 
 module RubyPython
   class << self
-    # Controls whether RubyPython is operating in <em>Normal Mode</em> or
-    # <em>Legacy Mode</em>.
+    ##
+    # :attr_accessor:
+    # Controls whether RubyPython is operating in <em>Proxy Mode</em> or
+    # <em>Legacy Mode</em>. This behavioural difference is deprecated as of
+    # RubyPython 0.6 and will be removed in a subsequent release.
     #
-    # === Normal Mode
+    # === Proxy Mode
     # By default, +legacy_mode+ is +false+, meaning that any object returned
-    # from a \Python function call will be wrapped in an instance of
-    # +RubyPyProxy+ or one of its subclasses. This allows \Python method
-    # calls to be forwarded to the \Python object, even if it would otherwise
-    # be a native Ruby object.
+    # from a \Python function call will be wrapped in a Ruby-Python proxy
+    # (an instance of +RubyPyProxy+ or one of its subclasses). This allows
+    # \Python method calls to be forwarded to the \Python object, even if it
+    # would otherwise be a native Ruby object.
     #
     #   RubyPython.session do
     #     string = RubyPython.import 'string'
@@ -60,8 +55,8 @@ module RubyPython
     # If +legacy_mode+ is +true+, RubyPython automatically tries to convert
     # returned objects to native Ruby object types. If there is no such
     # conversion, the object remains wrapped in +RubyPyProxy+. This
-    # behaviour is the same as RubyPython 0.2 and earlier. This mode is not
-    # recommended and may be phased out for RubyPython 1.0.
+    # behaviour is the same as RubyPython 0.2 and earlier. This mode is
+    # deprecated as of RubyPython 0.6 and will be removed.
     #
     #   RubyPython.legacy_mode = true
     #   RubyPython.session do
@@ -69,10 +64,32 @@ module RubyPython
     #     ascii_letters = string.ascii_letters
     #     puts ascii_letters.isalpha # throws NoMethodError
     #   end
-    attr_accessor :legacy_mode
+    def legacy_mode=(value)
+      warn_legacy_mode_deprecation unless defined? @legacy_mode
+      @legacy_mode = value
+    end
+
+    def legacy_mode
+      unless defined? @legacy_mode
+        warn_legacy_mode_deprecation
+        @legacy_mode = nil
+      end
+      @legacy_mode
+    end
 
-    # Starts the \Python interpreter. Either +RubyPython.start+,
-    # +RubyPython.session+, or +RubyPython.run+ must be run before using any
+    def legacy_mode?
+      @legacy_mode = nil unless defined? @legacy_mode
+      @legacy_mode
+    end
+    private :legacy_mode?
+
+    def warn_legacy_mode_deprecation
+      warn "RubyPython's Legacy Mode is deprecated and will be removed after version #{VERSION}."
+    end
+    private :warn_legacy_mode_deprecation
+
+    ## Starts the \Python interpreter. One of +RubyPython.start+,
+    # RubyPython.session+, or +RubyPython.run+ must be run before using any
     # \Python code. Returns +true+ if the interpreter was started; +false+
     # otherwise.
     #
@@ -90,27 +107,30 @@ module RubyPython
     #   sys = RubyPython.import 'sys'
     #   p sys.version # => "2.7.1"
     #   RubyPython.stop
-    #
-    # *NOTE*: In the current version of RubyPython, it _is_ possible to
-    # change \Python interpreters in a single Ruby process execution, but it
-    # is *strongly* discouraged as this may lead to segmentation faults.
-    # This feature is highly experimental and may be disabled in the future.
     def start(options = {})
-      RubyPython.configure(options)
+      Mutex.new.synchronize do
+        # Has the Runtime interpreter been defined?
+        if self.const_defined?(:Runtime)
+          # If this constant is defined, then yes it is. Since it is, let's
+          # see if we should print a warning to the user.
+          unless Runtime == options
+            warn "The Python interpreter has already been loaded from #{Runtime.python} and cannot be changed in this process. Continuing with the current runtime."
+          end
+        else
+          interp = RubyPython::Interpreter.new(options)
+          if interp.valid?
+            self.const_set(:Runtime, interp)
+          else
+            raise RubyPython::InvalidInterpreter, "An invalid interpreter was specified."
+          end
+        end
 
-      unless @load_ffi
-        @load_ffi = true
-        @reload = false
-        reload_library
+        unless defined? RubyPython::Python.ffi_libraries
+          Runtime.__send__(:infect!, RubyPython::Python)
+        end
       end
 
       return false if RubyPython::Python.Py_IsInitialized != 0
-
-      if @reload
-        reload_library
-        @reload = false
-      end
-
       RubyPython::Python.Py_Initialize
       notify :start
       true
@@ -195,7 +215,7 @@ module RubyPython
     # run(options = {}) { block to execute in RubyPython context }
     def run(options = {}, &block)
       start(options)
-      module_eval(&block)
+      self.module_eval(&block)
     ensure
       stop
     end
@@ -218,23 +238,28 @@ module RubyPython
     # This feature is highly experimental and may be disabled in the future.
     def start_from_virtualenv(virtualenv)
       result = start(:python_exe => File.join(virtualenv, "bin", "python"))
-      activate
+      activate_virtualenv
       result
     end
 
-    # Returns an object describing the currently active Python interpreter.
+    # Returns an object describing the active Python interpreter. Returns
+    # +nil+ if there is no active interpreter.
     def python
-      RubyPython::Python::EXEC
+      if self.const_defined? :Runtime
+        self::Runtime
+      else
+        nil
+      end
     end
 
     # Used to activate the virtualenv.
-    def activate
+    def activate_virtualenv
       imp = import("imp")
       imp.load_source("activate_this",
-                      File.join(File.dirname(RubyPython::Python::EXEC.python),
+                      File.join(File.dirname(RubyPython::Runtime.python),
                       "activate_this.py"))
     end
-    private :activate
+    private :activate_virtualenv
 
     def add_observer(object)
       @observers ||= []
@@ -247,21 +272,10 @@ module RubyPython
       @observers ||= []
       @observers.each do |o|
         next if nil === o
-        o.update status
+        o.__send__ :python_interpreter_update, status
       end
     end
     private :notify
-
-    def reload_library
-      # Invalidate the current Python instance, if defined.
-      if defined? RubyPython::Python::EXEC and RubyPython::Python::EXEC
-        RubyPython::Python::EXEC.instance_eval { invalidate! }
-      end
-      remove_const :Python
-      load RubyPython::PYTHON_RB
-      true
-    end
-    private :reload_library
   end
 
   add_observer PyMain

data/lib/rubypython/conversion.rb

@@ -30,8 +30,8 @@ module RubyPython::Conversion
     pList
   end
 
-  # Convert a Ruby Array to \Python Tuple. Returns an FFI::Pointer to a
-  # PyTupleObject.
+  # Convert a Ruby Array (including the subclass RubyPython::Tuple) to
+  # \Python \tuple. Returns an FFI::Pointer to a PyTupleObject.
   def self.rtopArrayToTuple(rArray)
     pList = rtopArrayToList(rArray)
     pTuple = RubyPython::Python.PySequence_Tuple(pList)
@@ -126,6 +126,8 @@ module RubyPython::Conversion
     case rObj
     when String
       rtopString rObj
+    when RubyPython::Tuple
+      rtopArrayToTuple rObj
     when Array
       # If this object is going to be used as a hash key we should make it a
       # tuple instead of a list
@@ -221,13 +223,13 @@ module RubyPython::Conversion
     RubyPython::Python.PyFloat_AsDouble(pNum)
   end
 
-  # Convert an FFI::Pointer to a \Python Tuple (PyTupleObject) to a Ruby
-  # Array.
+  # Convert an FFI::Pointer to a \Python Tuple (PyTupleObject) to an
+  # instance of RubyPython::Tuple, a subclass of the Ruby Array class.
   def self.ptorTuple(pTuple)
     pList = RubyPython::Python.PySequence_List pTuple
     rArray = ptorList pList
     RubyPython::Python.Py_DecRef pList
-    rArray
+    RubyPython::Tuple.tuple(rArray)
   end
 
   # Convert an FFI::Pointer to a \Python Dictionary (PyDictObject) to a Ruby

data/lib/rubypython/interpreter.rb

@@ -0,0 +1,250 @@
+# -*- ruby encoding: utf-8 -*-
+
+class RubyPython::InvalidInterpreter < Exception
+end
+
+##
+# An instance of this class represents information about a particular
+# \Python interpreter.
+#
+# This class represents the current Python interpreter.
+# A class that represents a \Python executable.
+#
+# End users may get the instance that represents the current running \Python
+# interpreter (from +RubyPython.python+), but should not directly
+# instantiate this class.
+class RubyPython::Interpreter
+
+  ##
+  # Compare the current Interpreter to the provided Interpreter or
+  # configuration hash. A configuration hash will be converted to an
+  # Interpreter object before being compared.
+  # :python_exe basename is used. If comparing against another Interpreter
+  # object, the Interpreter basename and version are used.
+  def ==(other)
+    other = self.class.new(other) if other.kind_of? Hash
+    return false unless other.kind_of? self.class
+    (self.version == other.version) && (self.version_name == other.version_name)
+  end
+
+  ##
+  # Create a new instance of an Interpreter instance describing a particular
+  # \Python executable and shared library.
+  #
+  # Expects a hash that matches the configuration options provided to
+  # RubyPython.start; currently only one value is recognized in that hash:
+  #
+  # * <tt>:python_exe</tt>: Specifies the name of the python executable to
+  #   run.
+  def initialize(options = {})
+    @python_exe = options[:python_exe]
+    # Windows: 'C:\\Python27\python.exe'
+    # Mac OS X: '/usr/bin/
+    rc, @python     = runpy "import sys; print sys.executable"
+    if rc.exitstatus.nonzero?
+      raise RubyPython::InvalidInterpreter, "An invalid interpreter was specified."
+    end
+    rc, @version    = runpy "import sys; print '%d.%d' % sys.version_info[:2]"
+    rc, @sys_prefix = runpy "import sys; print sys.prefix"
+
+    if FFI::Platform.windows?
+      flat_version  = @version.tr('.', '')
+      basename      = File.basename(@python, '.exe')
+
+      if basename =~ /(?:#{@version}|#{flat_version})$/
+        @version_name = basename
+      else
+        @version_name = "#{basename}#{flat_version}"
+      end
+    else
+      basename = File.basename(@python)
+
+      if basename =~ /#{@version}/
+        @version_name = basename
+      else
+        @version_name = "#{basename}#{@version}"
+      end
+    end
+
+    @library = find_python_lib
+  end
+
+  def find_python_lib
+    # By default, the library name will be something like
+    # libpython2.6.so, but that won't always work.
+    @libbase = "#{FFI::Platform::LIBPREFIX}#{@version_name}"
+    @libext = FFI::Platform::LIBSUFFIX
+    @libname = "#{@libbase}.#{@libext}"
+
+    # We may need to look in multiple locations for Python, so let's
+    # build this as an array.
+    @locations = [ File.join(@sys_prefix, "lib", @libname) ]
+
+    if FFI::Platform.mac?
+      # On the Mac, let's add a special case that has even a different
+      # @libname. This may not be fully useful on future versions of OS
+      # X, but it should work on 10.5 and 10.6. Even if it doesn't, the
+      # next step will (/usr/lib/libpython<version>.dylib is a symlink
+      # to the correct location).
+      @locations << File.join(@sys_prefix, "Python")
+      # Let's also look in the location that was originally set in this
+      # library:
+      File.join(@sys_prefix, "lib", "#{@realname}", "config", @libname)
+    end
+
+    if FFI::Platform.unix?
+      # On Unixes, let's look in some standard alternative places, too.
+      # Just in case. Some Unixes don't include a .so symlink when they
+      # should, so let's look for the base case of .so.1, too.
+      [ @libname, "#{@libname}.1" ].each do |name|
+        @locations << File.join("/opt/local/lib", name)
+        @locations << File.join("/opt/lib", name)
+        @locations << File.join("/usr/local/lib", name)
+        @locations << File.join("/usr/lib", name)
+        @locations << File.join("/opt/local/lib64", name)
+        @locations << File.join("/opt/lib64", name)
+        @locations << File.join("/usr/local/lib64", name)
+        @locations << File.join("/usr/lib64", name)
+      end
+    end
+
+    if FFI::Platform.windows?
+      # On Windows, the appropriate DLL is usually be found in
+      # %SYSTEMROOT%\system or %SYSTEMROOT%\system32; as a fallback we'll
+      # use C:\Windows\system{,32} as well as the install directory and the
+      # install directory + libs.
+      system_root = File.expand_path(ENV['SYSTEMROOT']).gsub(/\\/, '/')
+      @locations << File.join(system_root, 'system', @libname)
+      @locations << File.join(system_root, 'system32', @libname)
+      @locations << File.join("C:/WINDOWS", "System", @libname)
+      @locations << File.join("C:/WINDOWS", "System32", @libname)
+      @locations << File.join(sys_prefix, @libname)
+      @locations << File.join(sys_prefix, 'libs', @libname)
+      @locations << File.join(system_root, "SysWOW64", @libname)
+      @locations << File.join("C:/WINDOWS", "SysWOW64", @libname)
+    end
+
+    # Let's add alternative extensions; again, just in case.
+    @locations.dup.each do |location|
+      path = File.dirname(location)
+      base = File.basename(location, ".#{@libext}")
+      @locations << File.join(path, "#{base}.so")    # Standard Unix
+      @locations << File.join(path, "#{base}.dylib") # Mac OS X
+      @locations << File.join(path, "#{base}.dll")   # Windows
+    end
+
+    # Remove redundant locations
+    @locations.uniq!
+
+    library = nil
+
+    @locations.each do |location|
+      if File.exists? location
+        library = location
+        break
+      end
+    end
+
+    library
+  end
+  private :find_python_lib
+
+  def valid?
+    if @python.nil? or @python.empty?
+      false
+    elsif @library.nil? or @library.empty?
+      false
+    else
+      true
+    end
+  end
+
+  ##
+  # The name of the \Python executable that is used. This is the value of
+  # 'sys.executable' for the \Python interpreter provided in
+  # <tt>:python_exe</tt> or 'python' if it is not provided.
+  #
+  # On Mac OS X Lion (10.7), this value is '/usr/bin/python' for 'python'.
+  attr_reader :python
+  ##
+  # The version of the \Python interpreter. This is a decimalized version of
+  # 'sys.version_info[:2]' (such that \Python 2.7.1 is reported as '2.7').
+  attr_reader :version
+  ##
+  # The system prefix for the \Python interpreter. This is the value of
+  # 'sys.prefix'.
+  attr_reader :sys_prefix
+  ##
+  # The basename of the \Python interpreter with a version number. This is
+  # mostly an intermediate value used to find the shared \Python library,
+  # but /usr/bin/python is often a link to /usr/bin/python2.7 so it may be
+  # of value. Note that this does *not* include the full path to the
+  # interpreter.
+  attr_reader :version_name
+
+  # The \Python library.
+  attr_reader :library
+
+  # Run a Python command-line command.
+  def runpy(command)
+    i = @python || @python_exe || 'python'
+    if FFI::Platform.windows?
+      o = %x(#{i} -c "#{command}" 2> NUL:)
+    else
+      o = %x(#{i} -c "#{command}" 2> /dev/null)
+    end
+
+    [ $?, o.chomp ]
+  end
+  private :runpy
+
+  def inspect(debug = false)
+    if debug
+      debug_s
+    elsif @python
+      "#<#{self.class}: #{python} v#{version} #{sys_prefix} #{version_name}>"
+    else
+      "#<#{self.class}: invalid interpreter>"
+    end
+  end
+
+  def debug_s(format = nil)
+    system = ""
+    system << "windows " if FFI::Platform.windows?
+    system << "mac " if FFI::Platform.mac?
+    system << "unix " if FFI::Platform.unix?
+    system << "unknown " if system.empty?
+
+    case format
+    when :report
+      s = <<-EOS
+python_exe:   #{@python_exe}
+python:       #{@python}
+version:      #{@version}
+sys_prefix:   #{@sys_prefix}
+version_name: #{@version_name}
+platform:     #{system.chomp}
+library:      #{@library.inspect}
+  libbase:    #{@libbase}
+  libext:     #{@libext}
+  libname:    #{@libname}
+  locations:  #{@locations.inspect}
+      EOS
+    else
+      s = "#<#{self.class}: "
+      s << "python_exe=#{@python_exe.inspect} "
+      s << "python=#{@python.inspect} "
+      s << "version=#{@version.inspect} "
+      s << "sys_prefix=#{@sys_prefix.inspect} "
+      s << "version_name=#{@version_name.inspect} "
+      s << system
+      s << "library=#{@library.inspect} "
+      s << "libbase=#{@libbase.inspect} "
+      s << "libext=#{@libext.inspect} "
+      s << "libname=#{@libname.inspect} "
+      s << "locations=#{@locations.inspect}"
+    end
+
+    s
+  end
+end