diff pydertron.py @ 22:915fdf283ac5

Moved docs out to a separate file.
author Atul Varma <varmaa@toolness.com>
date Thu, 10 Sep 2009 16:59:18 -0700
parents cb73bb169b67
children c2c369402a2e
line wrap: on
line diff
--- a/pydertron.py	Thu Sep 10 16:37:33 2009 -0700
+++ b/pydertron.py	Thu Sep 10 16:59:18 2009 -0700
@@ -35,83 +35,9 @@
 # ***** END LICENSE BLOCK *****
 
 """
-    Pydertron is a high-level wrapper for `Pydermonkey`__ that
+    Pydertron is a high-level wrapper for Pydermonkey that
     provides convenient, secure object wrapping between JS and Python
     space.
-
-    The ``JsSandbox`` class encapsulates a JavaScript runtime, context, global
-    object, and a simple `SecurableModule`__ implementation that complies
-    with the `CommonJS`__ standard. It also provides a high-level bridge between
-    Python and JavaScript so that you don't need to deal with any of the
-    low-level details of the Pydermonkey API.
-
-    __ http://code.google.com/p/pydermonkey
-    __ http://wiki.commonjs.org/wiki/CommonJS/Modules/SecurableModules
-    __ http://wiki.commonjs.org/wiki/CommonJS
-
-    For instance, here we'll create a ``JsSandbox`` whose module root
-    points to the ``monkeys`` SecurableModule compliance test over HTTP:
-
-      >>> url = ("http://interoperablejs.googlecode.com/svn/trunk/"
-      ...        "compliance/monkeys/")
-      >>> sandbox = JsSandbox(HttpFileSystem(url))
-
-    This compliance test requires a global ``sys`` object that contains one
-    method, ``print()``, that takes two arguments. First, we'll create the
-    ``print()`` function and prepare it for exposure to JS code:
-
-      >>> @jsexposed
-      ... def jsprint(message, label):
-      ...   print message, label
-
-    Note the use of the ``@jsexposed`` decorator: all this does is set
-    the function's ``__jsexposed__`` attribute to ``True``. This is
-    done for security purposes: only Python callables satisfying this
-    criteria will be exposed to JavaScript code, to ensure that
-    untrusted JS can't accidentally gain access to privileged Python
-    functionality.
-
-    Creating a JS object can be done like this:
-
-      >>> system = sandbox.new_object()
-
-    We can now access and set properties on this object via either
-    item or attribute lookup, just like in JavaScript. Because
-    ``print`` is a reserved word in Python, though, we'll use item
-    lookup to set the property here:
-
-      >>> system['print'] = jsprint
-
-    Now we tell the sandbox that we want the ``sys`` object to be a
-    global:
-
-      >>> sandbox.set_globals(sys = system)
-
-    And finally, we execute the compliance test by running a one-line
-    script that imports the 'program' module, like so:
-
-      >>> sandbox.run_script("require('program');")
-      PASS monkeys permitted pass
-      DONE info
-      0
-
-    Note the ``0`` in the last line: this is the return value of
-    ``sandbox.run_script()``, which returns ``0`` on success, and
-    ``-1`` if an exception was raised. For instance, the output of bad
-    code looks like this:
-
-      >>> sandbox.run_script("(function foo() { bar(); })();",
-      ...                    stderr=sys.stdout)
-      Traceback (most recent call last):
-        File "<string>", line 1, in <module>
-        File "<string>", line 1, in foo
-      ReferenceError: bar is not defined
-      -1
-
-    Note that the traceback displayed is actually referring to
-    JavaScript code: one of Pydertron's helpful conveniences is that
-    it makes debugging JS code as much like debugging Python code as
-    possible.
 """
 
 import sys