Mercurial > pydertron

comparison docs.txt @ 22:915fdf283ac5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Moved docs out to a separate file.
author Atul Varma <varmaa@toolness.com>
date Thu, 10 Sep 2009 16:59:18 -0700
parents
children 7cbbec55aef6
comparison
equal deleted inserted replaced
21:cb73bb169b67 22:915fdf283ac5
1 =========
2 Pydertron
3 =========
4
5 Pydertron is a high-level wrapper for `Pydermonkey`__ that
6 provides convenient, secure object wrapping between JS and Python
7 space.
8
9 The ``JsSandbox`` class encapsulates a JavaScript runtime, context, global
10 object, and a simple `SecurableModule`__ implementation that complies
11 with the `CommonJS`__ standard. It also provides a high-level bridge between
12 Python and JavaScript so that you don't need to deal with any of the
13 low-level details of the Pydermonkey API.
14
15 __ http://code.google.com/p/pydermonkey
16 __ http://wiki.commonjs.org/wiki/CommonJS/Modules/SecurableModules
17 __ http://wiki.commonjs.org/wiki/CommonJS
18
19 For instance, here we'll create a ``JsSandbox`` whose module root
20 points to the ``monkeys`` SecurableModule compliance test over HTTP:
21
22 >>> url = ("http://interoperablejs.googlecode.com/svn/trunk/"
23 ... "compliance/monkeys/")
24 >>> sandbox = JsSandbox(HttpFileSystem(url))
25
26 This compliance test requires a global ``sys`` object that contains one
27 method, ``print()``, that takes two arguments. First, we'll create the
28 ``print()`` function and prepare it for exposure to JS code:
29
30 >>> @jsexposed
31 ... def jsprint(message, label):
32 ... print message, label
33
34 Note the use of the ``@jsexposed`` decorator: all this does is set
35 the function's ``__jsexposed__`` attribute to ``True``. This is
36 done for security purposes: only Python callables satisfying this
37 criteria will be exposed to JavaScript code, to ensure that
38 untrusted JS can't accidentally gain access to privileged Python
39 functionality.
40
41 Creating a JS object can be done like this:
42
43 >>> system = sandbox.new_object()
44
45 We can now access and set properties on this object via either
46 item or attribute lookup, just like in JavaScript. Because
47 ``print`` is a reserved word in Python, though, we'll use item
48 lookup to set the property here:
49
50 >>> system['print'] = jsprint
51
52 Now we tell the sandbox that we want the ``sys`` object to be a
53 global:
54
55 >>> sandbox.set_globals(sys = system)
56
57 And finally, we execute the compliance test by running a one-line
58 script that imports the 'program' module, like so:
59
60 >>> sandbox.run_script("require('program');")
61 PASS monkeys permitted pass
62 DONE info
63 0
64
65 Note the ``0`` in the last line: this is the return value of
66 ``sandbox.run_script()``, which returns ``0`` on success, and
67 ``-1`` if an exception was raised. For instance, the output of bad
68 code looks like this:
69
70 >>> sandbox.run_script("(function foo() { bar(); })();",
71 ... stderr=sys.stdout)
72 Traceback (most recent call last):
73 File "<string>", line 1, in <module>
74 File "<string>", line 1, in foo
75 ReferenceError: bar is not defined
76 -1
77
78 Note that the traceback displayed is actually referring to
79 JavaScript code: one of Pydertron's helpful conveniences is that
80 it makes debugging JS code as much like debugging Python code as
81 possible.