Mercurial > pydertron
annotate docs.html @ 24:c2c369402a2e
Added more docs, fixed edge cases.
| author | Atul Varma <varmaa@toolness.com> |
|---|---|
| date | Thu, 10 Sep 2009 22:32:45 -0700 |
| parents | 7cbbec55aef6 |
| children | 351819baecd1 |
| rev | line source |
|---|---|
| 21 | 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"> | |
| 3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> | |
| 4 <head> | |
| 5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> | |
| 6 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> | |
|
22
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
7 <title>Pydertron</title> |
| 21 | 8 <link rel="stylesheet" href="docs.css" type="text/css" /> |
| 9 </head> | |
| 10 <body> | |
|
22
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
11 <div class="document" id="pydertron"> |
|
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
12 <h1 class="title">Pydertron</h1> |
| 21 | 13 <p>Pydertron is a high-level wrapper for <a class="reference" href="http://code.google.com/p/pydermonkey">Pydermonkey</a> that |
| 14 provides convenient, secure object wrapping between JS and Python | |
| 15 space.</p> | |
|
24
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
16 <p>Note that Pydertron is just one example of a high-level interface |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
17 between Python and JavaScript: it assumes, for instance, that the JS |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
18 code it executes isn't trusted, which affects the nature of the |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
19 inter-language interaction.</p> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
20 <div class="section"> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
21 <h1><a id="the-basics" name="the-basics">The Basics</a></h1> |
| 21 | 22 <p>The <tt class="docutils literal"><span class="pre">JsSandbox</span></tt> class encapsulates a JavaScript runtime, context, global |
| 23 object, and a simple <a class="reference" href="http://wiki.commonjs.org/wiki/CommonJS/Modules/SecurableModules">SecurableModule</a> implementation that complies | |
| 24 with the <a class="reference" href="http://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> standard. It also provides a high-level bridge between | |
| 25 Python and JavaScript so that you don't need to deal with any of the | |
| 26 low-level details of the Pydermonkey API.</p> | |
| 27 <p>For instance, here we'll create a <tt class="docutils literal"><span class="pre">JsSandbox</span></tt> whose module root | |
| 23 | 28 points to the <a class="reference" href="http://interoperablejs.googlecode.com/svn/trunk/compliance/monkeys/">monkeys</a> SecurableModule compliance test over HTTP:</p> |
| 21 | 29 <blockquote> |
| 30 <pre class="doctest-block"> | |
| 31 >>> url = ("http://interoperablejs.googlecode.com/svn/trunk/" | |
| 32 ... "compliance/monkeys/") | |
| 33 >>> sandbox = JsSandbox(HttpFileSystem(url)) | |
| 34 </pre> | |
| 35 </blockquote> | |
| 36 <p>This compliance test requires a global <tt class="docutils literal"><span class="pre">sys</span></tt> object that contains one | |
| 37 method, <tt class="docutils literal"><span class="pre">print()</span></tt>, that takes two arguments. First, we'll create the | |
| 38 <tt class="docutils literal"><span class="pre">print()</span></tt> function and prepare it for exposure to JS code:</p> | |
| 39 <blockquote> | |
| 40 <pre class="doctest-block"> | |
| 41 >>> @jsexposed | |
| 42 ... def jsprint(message, label): | |
| 43 ... print message, label | |
| 44 </pre> | |
| 45 </blockquote> | |
| 46 <p>Note the use of the <tt class="docutils literal"><span class="pre">@jsexposed</span></tt> decorator: all this does is set | |
| 47 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 | |
| 48 done for security purposes: only Python callables satisfying this | |
| 49 criteria will be exposed to JavaScript code, to ensure that | |
| 50 untrusted JS can't accidentally gain access to privileged Python | |
| 51 functionality.</p> | |
| 52 <p>Creating a JS object can be done like this:</p> | |
| 53 <blockquote> | |
| 54 <pre class="doctest-block"> | |
| 55 >>> system = sandbox.new_object() | |
| 56 </pre> | |
| 57 </blockquote> | |
| 58 <p>We can now access and set properties on this object via either | |
| 59 item or attribute lookup, just like in JavaScript. Because | |
| 60 <tt class="docutils literal"><span class="pre">print</span></tt> is a reserved word in Python, though, we'll use item | |
| 61 lookup to set the property here:</p> | |
| 62 <blockquote> | |
| 63 <pre class="doctest-block"> | |
| 64 >>> system['print'] = jsprint | |
| 65 </pre> | |
| 66 </blockquote> | |
| 67 <p>Now we tell the sandbox that we want the <tt class="docutils literal"><span class="pre">sys</span></tt> object to be a | |
| 68 global:</p> | |
| 69 <blockquote> | |
| 70 <pre class="doctest-block"> | |
| 71 >>> sandbox.set_globals(sys = system) | |
| 72 </pre> | |
| 73 </blockquote> | |
| 74 <p>And finally, we execute the compliance test by running a one-line | |
| 75 script that imports the 'program' module, like so:</p> | |
| 76 <blockquote> | |
| 77 <pre class="doctest-block"> | |
| 78 >>> sandbox.run_script("require('program');") | |
| 79 PASS monkeys permitted pass | |
| 80 DONE info | |
| 81 0 | |
| 82 </pre> | |
| 83 </blockquote> | |
| 84 <p>Note the <tt class="docutils literal"><span class="pre">0</span></tt> in the last line: this is the return value of | |
| 85 <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 | |
| 86 <tt class="docutils literal"><span class="pre">-1</span></tt> if an exception was raised. For instance, the output of bad | |
| 87 code looks like this:</p> | |
| 88 <blockquote> | |
| 89 <pre class="doctest-block"> | |
| 90 >>> sandbox.run_script("(function foo() { bar(); })();", | |
| 91 ... stderr=sys.stdout) | |
| 92 Traceback (most recent call last): | |
| 93 File "<string>", line 1, in <module> | |
| 94 File "<string>", line 1, in foo | |
| 95 ReferenceError: bar is not defined | |
| 96 -1 | |
| 97 </pre> | |
| 98 </blockquote> | |
|
24
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
99 <p>Note that the traceback displayed is actually referring to JavaScript |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
100 code: one of Pydertron's aims is to make debugging JS code as much |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
101 like debugging Python code as possible.</p> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
102 </div> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
103 <div class="section"> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
104 <h1><a id="exceptions" name="exceptions">Exceptions</a></h1> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
105 <p>Any exceptions raised by wrapped Python functions need to be of type |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
106 <tt class="docutils literal"><span class="pre">pydermonkey.error</span></tt> to be propagated into calling JavaScript code; |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
107 if they're not, then for security purposes, the entire JavaScript call |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
108 stack is unrolled.</p> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
109 <p>For example, here's a function that's bound to fail:</p> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
110 <blockquote> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
111 <pre class="doctest-block"> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
112 >>> @jsexposed |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
113 ... def fail(): |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
114 ... o() |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
115 >>> sandbox.root.fail = fail |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
116 </pre> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
117 </blockquote> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
118 <p>Now, even though the following JS code calls the function in a |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
119 try-catch block, the JS code doesn't catch anything and its execution |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
120 is simply halted:</p> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
121 <blockquote> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
122 <pre class="doctest-block"> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
123 >>> sandbox.run_script("try { fail(); } catch (e) {}", |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
124 ... stderr=sys.stdout) #doctest: +ELLIPSIS |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
125 An internal error occurred. |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
126 Traceback (most recent call last): |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
127 ... |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
128 NameError: global name 'o' is not defined |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
129 -1 |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
130 </pre> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
131 </blockquote> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
132 <p>Note that a <tt class="docutils literal"><span class="pre">KeyboardInterrupt</span></tt> triggered while JS is executing will |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
133 have similar effect.</p> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
134 </div> |
|
22
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
135 </div> |
|
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
136 <div class="footer"> |
|
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
137 <hr class="footer" /> |
|
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
138 <a class="reference" href="docs.txt">View document source</a>. |
|
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
139 |
| 21 | 140 </div> |
| 141 </body> | |
| 142 </html> |