Mercurial > pydertron

comparison pydertron.py @ 21:cb73bb169b67

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added html docs.
author Atul Varma <varmaa@toolness.com>
date Thu, 10 Sep 2009 16:37:33 -0700
parents d382ca63d43f
children 915fdf283ac5
comparison
equal deleted inserted replaced
20:d382ca63d43f 21:cb73bb169b67
33 # the terms of any one of the MPL, the GPL or the LGPL. 33 # the terms of any one of the MPL, the GPL or the LGPL.
34 # 34 #
35 # ***** END LICENSE BLOCK ***** 35 # ***** END LICENSE BLOCK *****
36 36
37 """ 37 """
38 Pydertron is a high-level wrapper for Pydermonkey that provides convenient, 38 Pydertron is a high-level wrapper for `Pydermonkey`__ that
39 secure object wrapping between JS and Python space. 39 provides convenient, secure object wrapping between JS and Python
40 40 space.
41 The JsSandbox class encapsulates a JavaScript runtime, context, global 41
42 object, and a simple SecurableModule implementation that complies 42 The ``JsSandbox`` class encapsulates a JavaScript runtime, context, global
43 with the CommonJS standard. It also provides a high-level bridge between 43 object, and a simple `SecurableModule`__ implementation that complies
44 with the `CommonJS`__ standard. It also provides a high-level bridge between
44 Python and JavaScript so that you don't need to deal with any of the 45 Python and JavaScript so that you don't need to deal with any of the
45 low-level details of the Pydermonkey API. 46 low-level details of the Pydermonkey API.
46 47
47 For instance, here we'll create a JsSandbox whose module root 48 __ http://code.google.com/p/pydermonkey
48 points to the 'monkeys' SecurableModule compliance test over HTTP: 49 __ http://wiki.commonjs.org/wiki/CommonJS/Modules/SecurableModules
50 __ http://wiki.commonjs.org/wiki/CommonJS
51
52 For instance, here we'll create a ``JsSandbox`` whose module root
53 points to the ``monkeys`` SecurableModule compliance test over HTTP:
49 54
50 >>> url = ("http://interoperablejs.googlecode.com/svn/trunk/" 55 >>> url = ("http://interoperablejs.googlecode.com/svn/trunk/"
51 ... "compliance/monkeys/") 56 ... "compliance/monkeys/")
52 >>> sandbox = JsSandbox(HttpFileSystem(url)) 57 >>> sandbox = JsSandbox(HttpFileSystem(url))
53 58
54 This compliance test requires a global 'sys' object that contains one 59 This compliance test requires a global ``sys`` object that contains one
55 method, print(), that takes two arguments. First, we'll create the 60 method, ``print()``, that takes two arguments. First, we'll create the
56 print() function and prepare it for exposure to JS code: 61 ``print()`` function and prepare it for exposure to JS code:
57 62
58 >>> @jsexposed 63 >>> @jsexposed
59 ... def jsprint(message, label): 64 ... def jsprint(message, label):
60 ... print message, label 65 ... print message, label
61 66
62 Note the use of the @jsexposed decorator: all this does is set the 67 Note the use of the ``@jsexposed`` decorator: all this does is set
63 function's __jsexposed__ attribute to True. This is done for security 68 the function's ``__jsexposed__`` attribute to ``True``. This is
64 purposes: only Python callables satisfying this criteria will be 69 done for security purposes: only Python callables satisfying this
65 exposed to JavaScript code, to ensure that untrusted JS can't 70 criteria will be exposed to JavaScript code, to ensure that
66 accidentally gain access to privileged Python functionality. 71 untrusted JS can't accidentally gain access to privileged Python
72 functionality.
67 73
68 Creating a JS object can be done like this: 74 Creating a JS object can be done like this:
69 75
70 >>> system = sandbox.new_object() 76 >>> system = sandbox.new_object()
71 77
72 We can now access and set properties on this object via either 78 We can now access and set properties on this object via either
73 item or attribute lookup, just like in JavaScript. Because 'print' 79 item or attribute lookup, just like in JavaScript. Because
74 is a reserved word in Python, though, we'll use item lookup to set 80 ``print`` is a reserved word in Python, though, we'll use item
75 the property here: 81 lookup to set the property here:
76 82
77 >>> system['print'] = jsprint 83 >>> system['print'] = jsprint
78 84
79 Now we tell the sandbox that we want the 'sys' object to be a 85 Now we tell the sandbox that we want the ``sys`` object to be a
80 global: 86 global:
81 87
82 >>> sandbox.set_globals(sys = system) 88 >>> sandbox.set_globals(sys = system)
83 89
84 And finally, we execute the compliance test by running a one-line 90 And finally, we execute the compliance test by running a one-line
87 >>> sandbox.run_script("require('program');") 93 >>> sandbox.run_script("require('program');")
88 PASS monkeys permitted pass 94 PASS monkeys permitted pass
89 DONE info 95 DONE info
90 0 96 0
91 97
92 Note the '0' in the last line: this is the return value of 98 Note the ``0`` in the last line: this is the return value of
93 sandbox.run_script(), which returns 0 on success, and -1 if an 99 ``sandbox.run_script()``, which returns ``0`` on success, and
94 exception was raised. For instance, the output of bad 100 ``-1`` if an exception was raised. For instance, the output of bad
95 code looks like this: 101 code looks like this:
96 102
97 >>> sandbox.run_script("(function foo() { bar(); })();", 103 >>> sandbox.run_script("(function foo() { bar(); })();",
98 ... stderr=sys.stdout) 104 ... stderr=sys.stdout)
99 Traceback (most recent call last): 105 Traceback (most recent call last):