Mercurial > pydertron

comparison docs.html @ 28:d28100e071a7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Rebuilt HTML docs.
author Atul Varma <avarma@mozilla.com>
date Mon, 10 May 2010 00:59:19 -0700
parents 351819baecd1
children
comparison
equal deleted inserted replaced
27:0b00162939ae 28:d28100e071a7
1 <?xml version="1.0" encoding="utf-8" ?> 1 <?xml version="1.0" encoding="utf-8" ?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4 <head> 4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> 6 <meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
7 <title>Pydertron</title> 7 <title>Pydertron</title>
8 <link rel="stylesheet" href="docs.css" type="text/css" /> 8 <link rel="stylesheet" href="docs.css" type="text/css" />
9 </head> 9 </head>
10 <body> 10 <body>
11 <div class="document" id="pydertron"> 11 <div class="document" id="pydertron">
12 <h1 class="title">Pydertron</h1> 12 <h1 class="title">Pydertron</h1>
13 <p>Pydertron is an experimental high-level wrapper for <a class="reference" href="http://code.google.com/p/pydermonkey">Pydermonkey</a> 13
14 <p>Pydertron is an experimental high-level wrapper for <a class="reference external" href="http://code.google.com/p/pydermonkey">Pydermonkey</a>
14 that provides convenient, secure object wrapping between JS and Python 15 that provides convenient, secure object wrapping between JS and Python
15 space.</p> 16 space.</p>
16 <p>Note that Pydertron is just one example of a high-level interface 17 <p>Note that Pydertron is just one example of a high-level interface
17 between Python and JavaScript: it assumes, for instance, that the JS 18 between Python and JavaScript: it assumes, for instance, that the JS
18 code it executes isn't trusted, which affects the nature of the 19 code it executes isn't trusted, which affects the nature of the
19 inter-language interaction.</p> 20 inter-language interaction.</p>
20 <p>Pydertron is currently hosted at 21 <p>Pydertron is currently hosted at
21 <a class="reference" href="http://hg.toolness.com/pydertron">http://hg.toolness.com/pydertron</a>. Please feel free to send any 22 <a class="reference external" href="http://hg.toolness.com/pydertron">http://hg.toolness.com/pydertron</a>. Please feel free to send any
22 questions or comments to <a class="reference" href="mailto:atul&#64;mozilla.com">atul&#64;mozilla.com</a>.</p> 23 questions or comments to <a class="reference external" href="mailto:atul&#64;mozilla.com">atul&#64;mozilla.com</a>.</p>
23 <div class="section"> 24 <div class="section" id="the-basics">
24 <h1><a id="the-basics" name="the-basics">The Basics</a></h1> 25 <h1>The Basics</h1>
25 <p>The <tt class="docutils literal"><span class="pre">JsSandbox</span></tt> class encapsulates a JavaScript runtime, context, global 26 <p>The <tt class="docutils literal">JsSandbox</tt> class encapsulates a JavaScript runtime, context, global
26 object, and a simple <a class="reference" href="http://wiki.commonjs.org/wiki/CommonJS/Modules/SecurableModules">SecurableModule</a> implementation that complies 27 object, and a simple <a class="reference external" href="http://wiki.commonjs.org/wiki/CommonJS/Modules/SecurableModules">SecurableModule</a> implementation that complies
27 with the <a class="reference" href="http://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> standard. It also provides a high-level bridge between 28 with the <a class="reference external" href="http://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> standard. It also provides a high-level bridge between
28 Python and JavaScript so that you don't need to deal with any of the 29 Python and JavaScript so that you don't need to deal with any of the
29 low-level details of the Pydermonkey API.</p> 30 low-level details of the Pydermonkey API.</p>
30 <p>For instance, here we'll create a <tt class="docutils literal"><span class="pre">JsSandbox</span></tt> whose module root 31 <p>For instance, here we'll create a <tt class="docutils literal">JsSandbox</tt> whose module root
31 points to the <a class="reference" href="http://interoperablejs.googlecode.com/svn/trunk/compliance/monkeys/">monkeys</a> SecurableModule compliance test over HTTP:</p> 32 points to the <a class="reference external" href="http://interoperablejs.googlecode.com/svn/trunk/compliance/monkeys/">monkeys</a> SecurableModule compliance test over HTTP:</p>
32 <blockquote> 33 <blockquote>
33 <pre class="doctest-block"> 34 <pre class="doctest-block">
34 &gt;&gt;&gt; url = (&quot;http://interoperablejs.googlecode.com/svn/trunk/&quot; 35 &gt;&gt;&gt; url = (&quot;http://interoperablejs.googlecode.com/svn/trunk/&quot;
35 ... &quot;compliance/monkeys/&quot;) 36 ... &quot;compliance/monkeys/&quot;)
36 &gt;&gt;&gt; sandbox = JsSandbox(HttpFileSystem(url)) 37 &gt;&gt;&gt; sandbox = JsSandbox(HttpFileSystem(url))
37 </pre> 38 </pre>
38 </blockquote> 39 </blockquote>
39 <p>This compliance test requires a global <tt class="docutils literal"><span class="pre">sys</span></tt> object that contains one 40 <p>This compliance test requires a global <tt class="docutils literal">sys</tt> object that contains one
40 method, <tt class="docutils literal"><span class="pre">print()</span></tt>, that takes two arguments. First, we'll create the 41 method, <tt class="docutils literal">print()</tt>, that takes two arguments. First, we'll create the
41 <tt class="docutils literal"><span class="pre">print()</span></tt> function and prepare it for exposure to JS code:</p> 42 <tt class="docutils literal">print()</tt> function and prepare it for exposure to JS code:</p>
42 <blockquote> 43 <blockquote>
43 <pre class="doctest-block"> 44 <pre class="doctest-block">
44 &gt;&gt;&gt; &#64;jsexposed 45 &gt;&gt;&gt; &#64;jsexposed
45 ... def jsprint(message, label): 46 ... def jsprint(message, label):
46 ... print message, label 47 ... print message, label
47 </pre> 48 </pre>
48 </blockquote> 49 </blockquote>
49 <p>Note the use of the <tt class="docutils literal"><span class="pre">&#64;jsexposed</span></tt> decorator: all this does is set 50 <p>Note the use of the <tt class="docutils literal">&#64;jsexposed</tt> decorator: all this does is set
50 the function's <tt class="docutils literal"><span class="pre">__jsexposed__</span></tt> attribute to <tt class="docutils literal"><span class="pre">True</span></tt>. This is 51 the function's <tt class="docutils literal">__jsexposed__</tt> attribute to <tt class="docutils literal">True</tt>. This is
51 done for security purposes: only Python callables satisfying this 52 done for security purposes: only Python callables satisfying this
52 criteria will be exposed to JavaScript code, to ensure that 53 criteria will be exposed to JavaScript code, to ensure that
53 untrusted JS can't accidentally gain access to privileged Python 54 untrusted JS can't accidentally gain access to privileged Python
54 functionality.</p> 55 functionality.</p>
55 <p>Creating a JS object can be done like this:</p> 56 <p>Creating a JS object can be done like this:</p>
58 &gt;&gt;&gt; system = sandbox.new_object() 59 &gt;&gt;&gt; system = sandbox.new_object()
59 </pre> 60 </pre>
60 </blockquote> 61 </blockquote>
61 <p>We can now access and set properties on this object via either 62 <p>We can now access and set properties on this object via either
62 item or attribute lookup, just like in JavaScript. Because 63 item or attribute lookup, just like in JavaScript. Because
63 <tt class="docutils literal"><span class="pre">print</span></tt> is a reserved word in Python, though, we'll use item 64 <tt class="docutils literal">print</tt> is a reserved word in Python, though, we'll use item
64 lookup to set the property here:</p> 65 lookup to set the property here:</p>
65 <blockquote> 66 <blockquote>
66 <pre class="doctest-block"> 67 <pre class="doctest-block">
67 &gt;&gt;&gt; system['print'] = jsprint 68 &gt;&gt;&gt; system['print'] = jsprint
68 </pre> 69 </pre>
69 </blockquote> 70 </blockquote>
70 <p>Now we tell the sandbox that we want the <tt class="docutils literal"><span class="pre">sys</span></tt> object to be a 71 <p>Now we tell the sandbox that we want the <tt class="docutils literal">sys</tt> object to be a
71 global:</p> 72 global:</p>
72 <blockquote> 73 <blockquote>
73 <pre class="doctest-block"> 74 <pre class="doctest-block">
74 &gt;&gt;&gt; sandbox.set_globals(sys = system) 75 &gt;&gt;&gt; sandbox.set_globals(sys = system)
75 </pre> 76 </pre>
82 PASS monkeys permitted pass 83 PASS monkeys permitted pass
83 DONE info 84 DONE info
84 0 85 0
85 </pre> 86 </pre>
86 </blockquote> 87 </blockquote>
87 <p>Note the <tt class="docutils literal"><span class="pre">0</span></tt> in the last line: this is the return value of 88 <p>Note the <tt class="docutils literal">0</tt> in the last line: this is the return value of
88 <tt class="docutils literal"><span class="pre">sandbox.run_script()</span></tt>, which returns <tt class="docutils literal"><span class="pre">0</span></tt> on success, and 89 <tt class="docutils literal">sandbox.run_script()</tt>, which returns <tt class="docutils literal">0</tt> on success, and
89 <tt class="docutils literal"><span class="pre">-1</span></tt> if an exception was raised. For instance, the output of bad 90 <tt class="docutils literal"><span class="pre">-1</span></tt> if an exception was raised. For instance, the output of bad
90 code looks like this:</p> 91 code looks like this:</p>
91 <blockquote> 92 <blockquote>
92 <pre class="doctest-block"> 93 <pre class="doctest-block">
93 &gt;&gt;&gt; sandbox.run_script(&quot;(function foo() { bar(); })();&quot;, 94 &gt;&gt;&gt; sandbox.run_script(&quot;(function foo() { bar(); })();&quot;,
101 </blockquote> 102 </blockquote>
102 <p>Note that the traceback displayed is actually referring to JavaScript 103 <p>Note that the traceback displayed is actually referring to JavaScript
103 code: one of Pydertron's aims is to make debugging JS code as much 104 code: one of Pydertron's aims is to make debugging JS code as much
104 like debugging Python code as possible.</p> 105 like debugging Python code as possible.</p>
105 </div> 106 </div>
106 <div class="section"> 107 <div class="section" id="exceptions">
107 <h1><a id="exceptions" name="exceptions">Exceptions</a></h1> 108 <h1>Exceptions</h1>
108 <p>Any exceptions raised by wrapped Python functions need to be of type 109 <p>Any exceptions raised by wrapped Python functions need to be of type
109 <tt class="docutils literal"><span class="pre">pydermonkey.error</span></tt> to be propagated into calling JavaScript code; 110 <tt class="docutils literal">pydermonkey.ScriptError</tt> to be propagated into calling JavaScript code;
110 if they're not, then for security purposes, the entire JavaScript call 111 if they're not, then for security purposes, the entire JavaScript call
111 stack is unrolled.</p> 112 stack is unrolled.</p>
112 <p>For example, here's a function that's bound to fail:</p> 113 <p>For example, here's a function that's bound to fail:</p>
113 <blockquote> 114 <blockquote>
114 <pre class="doctest-block"> 115 <pre class="doctest-block">
130 ... 131 ...
131 NameError: global name 'o' is not defined 132 NameError: global name 'o' is not defined
132 -1 133 -1
133 </pre> 134 </pre>
134 </blockquote> 135 </blockquote>
135 <p>Note that a <tt class="docutils literal"><span class="pre">KeyboardInterrupt</span></tt> triggered while JS is executing will 136 <p>Note that a <tt class="docutils literal">KeyboardInterrupt</tt> triggered while JS is executing will
136 have similar effect.</p> 137 have similar effect.</p>
137 </div> 138 </div>
138 </div> 139 </div>
139 <div class="footer"> 140 <div class="footer">
140 <hr class="footer" /> 141 <hr class="footer" />
141 <a class="reference" href="docs.txt">View document source</a>. 142 <a class="reference external" href="docs.txt">View document source</a>.
142 143
143 </div> 144 </div>
144 </body> 145 </body>
145 </html> 146 </html>