rubypython 0.2.11 → 0.3.0

data/{History.txt → History.markdown}

@@ -1,49 +1,56 @@
-== 0.2.11 2010-07-12
-* Bug Fixes
-	* Fixed some issues with building the extension under ruby 1.9. Sould now be truly 1.9 compatible.
+## 0.3.0 2010-09-xx
+* Major Enhancements
+  * Version 0.3.0 represents an almost complete rewrite of the RubyPython codebase.
+  * A native C extension is no longer required. RubyPython uses the 'ffi' gem.
+  * RubyPython by default now returns proxy instances for all Ruby objects. See the documentation for more information.
+* Compatibility Updates
+  * Version 0.3.0 was created with the goal of being compatible with as many Ruby versions as possible. It should at the very least run on MRI 1.8.6 - 1.9.1.
+  * A legacy mode option has been added to provide partial compatibility with version 0.2.x.
 
-== 0.2.10 2010-07-08
+## 0.2.10 2010-07-08
 * Bug Fixes
 	* Made some changes to how the native extension is configured and build.
-== 0.2.9 2009-10-19
+
+## 0.2.9 2009-10-19
 * Minor Enhancements
 	* Updated the C code to make it cleaner, more readable, and more maintainable.
-== 0.2.8 2009-10-05
+
+## 0.2.8 2009-10-05
 * Bug Fixes
 	* Some test files were improperly formatted (minor bug fix).
-== 0.2.7 2009-3-30
+
+## 0.2.7 2009-3-30
 * Bug Fixes
 	* Fixed some bugs which caused rubypython to be unable to determine python version correctly.
-== 0.2.6 2009-3-19
+
+## 0.2.6 2009-3-19
 * Bug Fixes
 	* Further updates to increase compatibility with 1.9.
-== 0.2.5 2009-3-18
+
+## 0.2.5 2009-3-18
 * Bug Fixes
 	* Updated to build and run under Ruby 1.9.
 
-== 0.2.4 2008-10-24
+## 0.2.4 2008-10-24
 * Major Enhancements
-	* Provided setter methods for object attributes. Python object attributes can now be set 
-		from within ruby.
-	* Made wrapper classes a subclass of custom made blank object class to try to avoid name 	
-		collisions.
+	* Provided setter methods for object attributes. Python object attributes can now be set from within ruby.
+	* Made wrapper classes a subclass of custom made blank object class to try to avoid name collisions.
 * Bug Fix
 	* Changed part of extconf.rb file that would not work under windows.
-== 0.2.3 2008-08-29
+
+## 0.2.3 2008-08-29
 * 2 Major Enhancements
-	* Introduced PyMain object as a singleton wrapper for the Python __main__ and 
-		__builtin__ modules.
+	* Introduced PyMain object as a singleton wrapper for the Python __main__ and __builtin__ modules.
 	* Introduced block functionality for PyMain object.
 	
 * Compatibility Updates
-	* Changed some declarations in the C code to make RubyPython more compatible with the 	
-		style conventions of the Ruby C API.
+	* Changed some declarations in the C code to make RubyPython more compatible with the style conventions of the Ruby C API.
 	* Update how RubyPython locates the Python headers and library.
 * 1 Bug Fix
-	* Fixed an error in ptor.c that might have prevented RubyPython from building correctly 	
-		on certain systems.
+	* Fixed an error in ptor.c that might have prevented RubyPython from building correctly on certain systems.
 		
-== 0.2.2 2008-08-07
+
+## 0.2.2 2008-08-07
 * Major Enhancements
 	* Wrapped classes and instances should now behave as expected.
 	* Gave RubyPyClasses a "new" method for creating instances.
@@ -51,15 +58,14 @@
 	* A wrapped object's respond_to? method now has some relation to its actual methods.
 	
 * Bug fixes
-	* Fixed bug with inspect method of RubyPyObject that caused a bus error when inspecting
-		certain objects
+	* Fixed bug with inspect method of RubyPyObject that caused a bus error when inspecting certain objects
 
 
-== 0.2.1 2008-08-02
+## 0.2.1 2008-08-02
 * 1 Bug Fix
 	* Incorrect require fixed
 
-== 0.2.0 2008-08-02
+## 0.2.0 2008-08-02
 * 3 major enhancements
 	* RubyPython can now effectively convert or wrap most types from Python.
 	* Errors in the Python interpreter are relayed to Ruby errors.
@@ -68,11 +74,11 @@
 	* RubyPython.run did not work correctly. This is fixed now.
 	* Cleanup in RubyPython.stop fixes some issues in RubyPythonBridge.stop
 
-== 0.1.0 2008-08-01
+## 0.1.0 2008-08-01
 * A lot of major enhancements
 	* Too many to name. Hey I'm still developing
 
-== 0.0.1 2008-07-30
+## 0.0.1 2008-07-30
 
 * 1 major enhancement:
   * Initial release

data/Manifest.txt

@@ -1,46 +1,32 @@
-History.txt
+History.markdown
 License.txt
 Manifest.txt
 PostInstall.txt
-README.txt
+README.markdown
 Rakefile
-ext/rubypython_bridge/cbridge.c
-ext/rubypython_bridge/cbridge.h
-ext/rubypython_bridge/config.h
-ext/rubypython_bridge/extconf.rb
-ext/rubypython_bridge/ptor.c
-ext/rubypython_bridge/ptor.h
-ext/rubypython_bridge/rp_blankobject.c
-ext/rubypython_bridge/rp_blankobject.h
-ext/rubypython_bridge/rp_class.c
-ext/rubypython_bridge/rp_class.h
-ext/rubypython_bridge/rp_error.c
-ext/rubypython_bridge/rp_error.h
-ext/rubypython_bridge/rp_function.c
-ext/rubypython_bridge/rp_function.h
-ext/rubypython_bridge/rp_instance.c
-ext/rubypython_bridge/rp_instance.h
-ext/rubypython_bridge/rp_module.c
-ext/rubypython_bridge/rp_module.h
-ext/rubypython_bridge/rp_object.c
-ext/rubypython_bridge/rp_object.h
-ext/rubypython_bridge/rp_util.c
-ext/rubypython_bridge/rp_util.h
-ext/rubypython_bridge/rtop.c
-ext/rubypython_bridge/rtop.h
-ext/rubypython_bridge/rubypython_bridge.c
-ext/rubypython_bridge/rubypython_bridge.h
 lib/rubypython.rb
-lib/rubypython/session.rb
+lib/rubypython/blankobject.rb
+lib/rubypython/core_ext/string.rb
+lib/rubypython/pythonerror.rb
+lib/rubypython/macros.rb
+lib/rubypython/conversion.rb
+lib/rubypython/operators.rb
+lib/rubypython/pyobject.rb
+lib/rubypython/pymainclass.rb
+lib/rubypython/python.rb
+lib/rubypython/rubypyproxy.rb
 lib/rubypython/version.rb
-lib/rubypython/wrapper_extensions.rb
-setup.rb
-tasks/environment.rake
-tasks/extconf.rake
-tasks/extconf/rubypython_bridge.rake
-test/python_helpers/objects.py
-test/test.wav
-test/test_helper.rb
-test/test_rubypython.rb
-test/test_rubypython_bridge_extn.rb
-test/test_session.rb
+lib/rubypython/legacy.rb
+spec/pymainclass_spec.rb
+spec/pyobject_spec.rb
+spec/python_helpers
+spec/python_helpers/objects.py
+spec/pythonerror_spec.rb
+spec/rubypyclass_spec.rb
+spec/rubypyproxy_spec.rb
+spec/rubypython_spec.rb
+spec/refcnt_spec.rb
+spec/conversion_spec.rb
+spec/legacy_spec.rb
+spec/spec.opts
+spec/spec_helper.rb

data/PostInstall.txt

@@ -1,5 +1,6 @@
+A number of things have changed with version 0.3.0. If you are upgrading from a previous version of RubyPython, you should check the docs for instructions on how to get your code working with the new version of RubyPython.
 
-For more information on RubyPython, see http://rubypython.rubyforge.org
+For more information on RubyPython, see http://raineszm.bitbucket.org/rubypython/index.html
 
 If you find a bug, or have any suggestions, email me at: raineszm+rubypython@gmail.com
 

data/README.markdown

@@ -0,0 +1,103 @@
+# RubyPython
+
+* [RubyPython](http://raineszm.bitbucket.org/rubypython/)
+
+## DESCRIPTION:
+
+RubyPython is a bridge between the Ruby and Python interpreters. It embeds a
+running Python interpreter in the application's process using FFI and
+provides a means for wrapping and converting Python objects.
+ 
+## FEATURES/PROBLEMS:
+
+### Features
+
+* Can handle simple conversion of Python builtin types to Ruby builtin types and vice versa
+* Can import Python modules
+* Can execute arbitrary methods on imported modules and return the result
+* Python objects can be treated as Ruby objects!
+* Python's standard library available to you from within Ruby.
+
+### Known Problems
+
+* Builtin Python methods which require a top level frame object (eval, dir, ...) do not work properly at present.
+* There is no support for passing more complicated Ruby types to Python.
+
+## SYNOPSIS:
+RubyPython lets you leverage the power of the Python standard library while
+using the syntactical power of ruby. Using RubyPython you can write code such
+as:
+
+    RubyPython.start
+    cPickle = RubyPython.import("cPickle")
+    p cPickle.dumps("RubyPython is awesome!").rubify
+    RubyPython.stop
+
+The main point of the gem is to allow access to tools that are not readily availible in Ruby. However, it is clear that many people may wish to use Ruby tools with Python code bases using this library. The largest problem in this case is that there is no support for passing Ruby classes, procs, or methods to Python. That being said, with some creative coding it is still possible to do a lot.
+
+One caveat is that it may be tempting to try to translate Python code to Ruby code directly using RubyPython. However, it often makes much more sense to use idiomatic Ruby code where possible. For example if we have the following Python code:
+
+    import library
+    for i in library.a_list:
+      print(library.function_call(i))
+
+If we wanted for some reason to migrate this to RubyPython, we could do it as follows:
+
+    RubyPython.start
+    library = RubyPython.import 'library'
+    library.a_list.to_a.each { |i| puts library.function_call(i).rubify }
+    RubyPython.stop
+
+There are several things to note about the code above:
+
+1. We made sure to call RubyPython.start before doing anything with the Python interpreter.
+1. We manually bound our imported library to a local variable. RubyPython will not do that for us.
+1. We used to\_a to convert a python iterable type to a Ruby array.
+1. We called rubify before we printed the objects so that they would be displayed as native Ruby objects.
+1. We stopped the interpreter after we were done with RubyPython.stop.
+	
+## REQUIREMENTS:
+	
+* Python >= 2.4, < 3.0
+* Ruby >= 1.8.6
+* You must be able to build the ffi gem under your environment.
+
+Note: RubyPython has been tested on Mac OS 10.5.x
+	
+	
+## INSTALL:
+
+[sudo] gem install rubypython
+
+## DOCUMENTATION:
+
+The documentation should provide a reasonable description of how to use RubyPython.
+Starting with version 0.3.x there are two modes of operation: normal and
+legacy. These are described in the docs.
+
+The most useful to check out [docs](http://raineszm.bitbucket.org/rubypython/) will be those for RubyPython and RubyPython::RubyPyProxy.
+	
+## LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Zach Raines
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -1,4 +1,20 @@
-require 'config/requirements'
-require 'config/hoe' # setup Hoe + all gem configuration
+require 'spec/rake/spectask'
+require 'yard'
 
-Dir['tasks/**/*.rake'].each { |rake| load rake }
+desc "Run all examples"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+desc "Run all examples with RCov"
+Spec::Rake::SpecTask.new('spec:rcov') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec']
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.options = [ '--markup','markdown', '--title', 'RubyPython Documentation' ]
+end
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/lib/rubypython.rb

@@ -1,126 +1,130 @@
-require 'rubypython_bridge'
-require 'rubypython/wrapper_extensions'
+require 'rubypython/core_ext/string'
+require 'rubypython/python'
+require 'rubypython/pythonerror'
+require 'rubypython/pyobject'
+require 'rubypython/rubypyproxy'
+require 'rubypython/pymainclass'
 
 
-=begin rdoc
-This module provides the direct user interface for the RubyPython extension.
+#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.
+#@example
+#    RubyPython.start
+#    cPickle = RubyPython.import "cPickle"
+#    puts cPickle.dumps("RubyPython is awesome!").rubify
+#    RubyPython.stop
+#
+#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}.
+module RubyPython
 
-The majority of the functionality lies in the _RubyPythonBridge_ module, which is provided
-by the C extension. However, the end user should only worry about dealing with the RubyPython
-module as that is designed for user interaction. Furthermore the RubyPythonBridge is somewhat
-bad with memory management and using it directly may result in some strange crashes.
+  class << self
 
-==Usage  
-It is important to remember that the Python Interpreter must be started before the bridge
-is functional. This may be done by two methods. One is to use the +start+ function.
-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.
-Example:
-  RubyPython.start
-  cPickle=RubyPython.import "cPickle"
-  puts cPickle.dumps "RubyPython is awesome!"
-  RubyPython.stop
-  
-The other method is preferable if one wants a simpler approach. This other method is to use
-<tt>RubyPython.run</tt>. run takes a block which is evaluated in the scope of the RubyPython module.
-In addition, the interpreter is started before the block is run and halted at its completion.
-This allows one to do something like the following:
-  RubyPython.run do
-    cPickle=import "cPickle"
-    puts cPickle.dumps "RubyPython is still awesome!"
-  end
+    #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.
+    #@return [Boolean]
+    #@example Normal Mode
+    #    RubyPython.start
+    #    string = RubyPython.import 'string'
+    #    ascii_letters = string.ascii_letters # Here ascii_letters is a proxy object
+    #    puts ascii_letters.rubify # we use the rubify method to convert it to a
+    #                              # native type
+    #    RubyPython.stop
+    #
+    #@example Legacy Mode
+    #    RubyPython.legacy_mode = true
+    #    RubyPython.start
+    #    string = RubyPython.import 'string'
+    #    ascii_letters = string.ascii_letters # Here ascii_letters is a native ruby string
+    #    puts ascii_letters # No explicit conversion is neccessary
+    #    RubyPython.stop
+    attr_accessor :legacy_mode
 
-The downside to the above method is that the block has no access to the encompassing scope. An
-alternative is to use <tt>RubyPython.session</tt>. The downside to this approach is that the module
-methods are not available by their unqualified names: i.e.
-  irb(main):001:0>   RubyPython.session do
-  irb(main):002:1*     cPickle=import "cPickle"
-  irb(main):003:1>   end
-  NoMethodError: undefined method `import' for main:Object
-  	from (irb):2
-  	from ./rubypython.rb:93:in `call'
-  	from ./rubypython.rb:93:in `session'
-  	from (irb):1
-  	
-However:
-  irb(main):001:0> RubyPython.session do
-  irb(main):002:1*   cPickle=RubyPython.import "cPickle"
-  irb(main):003:1>   puts cPickle.dumps "RubyPython is still awesome!"
-  irb(main):004:1> end
-  S'RubyPython is still awesome!'
-  .
-  => nil
+    #Starts ups the Python interpreter. This method **must** be run
+    #before using any Python code. The only alternatives are use of the
+    #{session} and {run} methods.
+    #@return [Boolean] returns true if the interpreter was started here
+    #    and false otherwise
+    def start
+      if Python.Py_IsInitialized != 0
+        return false
+      end
+      Python.Py_Initialize
+      true
+    end
 
-A compromise can be achieved by just including the RubyPython module into the scope you're
-working in.
+    #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.
+    #@return [Boolean] returns true if the interpreter was stopped here
+    #    and false otherwise
+    def stop
+      if Python.Py_IsInitialized !=0
+        PyMain.main = nil
+        PyMain.builtin = nil
+        RubyPython::Operators.send :class_variable_set, '@@operator', nil
+        Python.Py_Finalize
+        RubyPython::PyObject::AutoPyPointer.current_pointers.clear
+        return true
+      end
+      false
+    end
 
-If you really wish to be free of dealing with the interpreter, just import 'rubypython/session'.
-This will start the interpreter on import and will halt it when execution ends.
-  
-==Errors
-The RubyPythonModule defines a new error object, PythonError. Should any error occur within
-the Python interpreter, the class and value of the error will be passed back into ruby within
-the text of the raised PythonError.
-  irb(main):001:0> RubyPython.start
-  => true
-  irb(main):002:0> RubyPython.import "does not exist"
-  PythonError: ImportError:(No module named does not exist)
+    #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.
+    #@param [String] mod_name the name of the module to import
+    #@return [RubyPyModule] a proxy object wrapping the requested
+    #module
+    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
 
-  	from ./rubypython.rb:66:in `initialize'
-  	from ./rubypython.rb:66:in `import'
-  	from ./rubypython.rb:66:in `import'
-  	from (irb):2
-=end
-module RubyPython
-  
-  # Used to started the python interpreter. Delegates to RubyPythonBridge
-  # 
-  #   RubyPython.start
-  #   --Some python code--
-  #   RubyPython.stop
-  #   
-  # Also see, _stop_
-  def self.start() #=> true||false
-    RubyPythonBridge.start
-  end
-  
-  
+    #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.
+    #@param [Block] block the code to be executed while the interpreter is running
+    #@return the result of evaluating the given block
+    def session
+      start
+      result = yield
+      stop
+      result
+    end
 
-  # Used to end the python session. Adds some cleanup on top of RubyPythonBridge.stop
-  def self.stop() #=> true,false
-    ObjectSpace.each_object(RubyPythonBridge::RubyPyObject) do |o|
-      o.free_pobj
+    #The same as {session} except that the block is executed within the scope 
+    #of the RubyPython module.
+    def run(&block)
+      start
+      result = module_eval(&block)
+      stop
     end
-    PyMain.main=nil
-    PyMain.builtin=nil
-    RubyPythonBridge.stop
-  end
-  
-  # Import the python module +mod+ and return it wrapped as a ruby object
-  def self.import(mod)
-    RubyPythonBridge.import(mod)
-  end
-  
-  # Handles the setup and cleanup involved with using the interpreter for you.
-  # Note that all Python object will be effectively scope to within the block
-  # as the embedded interpreter will be halted at its end. The supplied block is
-  # run within the scope of the RubyPython module.
-  #
-  # Alternatively the user may prefer RubyPython.session which simples handles
-  # initialization and cleanup of the interpreter.
-  def self.run(&block)
-    start
-      module_eval(&block)
-    stop
-  end
-  
-  # Simply starts the interpreter, runs the supplied block, and stops the interpreter.
-  def self.session(&block)
-    start
-    retval = block.call
-    stop
-    return retval
   end
 end
-
-