Mercurial > pydertron
annotate docs.html @ 35:6ddc83bb61f8 default tip
added another gc test
| author | Atul Varma <avarma@mozilla.com> |
|---|---|
| date | Mon, 10 May 2010 21:01:58 -0700 |
| parents | d28100e071a7 |
| children |
| 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" /> | |
| 28 | 6 <meta name="generator" content="Docutils 0.6: 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> |
| 28 | 13 |
| 14 <p>Pydertron is an experimental high-level wrapper for <a class="reference external" href="http://code.google.com/p/pydermonkey">Pydermonkey</a> | |
| 25 | 15 that provides convenient, secure object wrapping between JS and Python |
| 21 | 16 space.</p> |
|
24
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
17 <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
|
18 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
|
19 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
|
20 inter-language interaction.</p> |
| 25 | 21 <p>Pydertron is currently hosted at |
| 28 | 22 <a class="reference external" href="http://hg.toolness.com/pydertron">http://hg.toolness.com/pydertron</a>. Please feel free to send any |
| 23 questions or comments to <a class="reference external" href="mailto:atul@mozilla.com">atul@mozilla.com</a>.</p> | |
| 24 <div class="section" id="the-basics"> | |
| 25 <h1>The Basics</h1> | |
| 26 <p>The <tt class="docutils literal">JsSandbox</tt> class encapsulates a JavaScript runtime, context, global | |
| 27 object, and a simple <a class="reference external" href="http://wiki.commonjs.org/wiki/CommonJS/Modules/SecurableModules">SecurableModule</a> implementation that complies | |
| 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 | |
| 21 | 29 Python and JavaScript so that you don't need to deal with any of the |
| 30 low-level details of the Pydermonkey API.</p> | |
| 28 | 31 <p>For instance, here we'll create a <tt class="docutils literal">JsSandbox</tt> whose module root |
| 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> | |
| 21 | 33 <blockquote> |
| 34 <pre class="doctest-block"> | |
| 35 >>> url = ("http://interoperablejs.googlecode.com/svn/trunk/" | |
| 36 ... "compliance/monkeys/") | |
| 37 >>> sandbox = JsSandbox(HttpFileSystem(url)) | |
| 38 </pre> | |
| 39 </blockquote> | |
| 28 | 40 <p>This compliance test requires a global <tt class="docutils literal">sys</tt> object that contains one |
| 41 method, <tt class="docutils literal">print()</tt>, that takes two arguments. First, we'll create the | |
| 42 <tt class="docutils literal">print()</tt> function and prepare it for exposure to JS code:</p> | |
| 21 | 43 <blockquote> |
| 44 <pre class="doctest-block"> | |
| 45 >>> @jsexposed | |
| 46 ... def jsprint(message, label): | |
| 47 ... print message, label | |
| 48 </pre> | |
| 49 </blockquote> | |
| 28 | 50 <p>Note the use of the <tt class="docutils literal">@jsexposed</tt> decorator: all this does is set |
| 51 the function's <tt class="docutils literal">__jsexposed__</tt> attribute to <tt class="docutils literal">True</tt>. This is | |
| 21 | 52 done for security purposes: only Python callables satisfying this |
| 53 criteria will be exposed to JavaScript code, to ensure that | |
| 54 untrusted JS can't accidentally gain access to privileged Python | |
| 55 functionality.</p> | |
| 56 <p>Creating a JS object can be done like this:</p> | |
| 57 <blockquote> | |
| 58 <pre class="doctest-block"> | |
| 59 >>> system = sandbox.new_object() | |
| 60 </pre> | |
| 61 </blockquote> | |
| 62 <p>We can now access and set properties on this object via either | |
| 63 item or attribute lookup, just like in JavaScript. Because | |
| 28 | 64 <tt class="docutils literal">print</tt> is a reserved word in Python, though, we'll use item |
| 21 | 65 lookup to set the property here:</p> |
| 66 <blockquote> | |
| 67 <pre class="doctest-block"> | |
| 68 >>> system['print'] = jsprint | |
| 69 </pre> | |
| 70 </blockquote> | |
| 28 | 71 <p>Now we tell the sandbox that we want the <tt class="docutils literal">sys</tt> object to be a |
| 21 | 72 global:</p> |
| 73 <blockquote> | |
| 74 <pre class="doctest-block"> | |
| 75 >>> sandbox.set_globals(sys = system) | |
| 76 </pre> | |
| 77 </blockquote> | |
| 78 <p>And finally, we execute the compliance test by running a one-line | |
| 79 script that imports the 'program' module, like so:</p> | |
| 80 <blockquote> | |
| 81 <pre class="doctest-block"> | |
| 82 >>> sandbox.run_script("require('program');") | |
| 83 PASS monkeys permitted pass | |
| 84 DONE info | |
| 85 0 | |
| 86 </pre> | |
| 87 </blockquote> | |
| 28 | 88 <p>Note the <tt class="docutils literal">0</tt> in the last line: this is the return value of |
| 89 <tt class="docutils literal">sandbox.run_script()</tt>, which returns <tt class="docutils literal">0</tt> on success, and | |
| 21 | 90 <tt class="docutils literal"><span class="pre">-1</span></tt> if an exception was raised. For instance, the output of bad |
| 91 code looks like this:</p> | |
| 92 <blockquote> | |
| 93 <pre class="doctest-block"> | |
| 94 >>> sandbox.run_script("(function foo() { bar(); })();", | |
| 95 ... stderr=sys.stdout) | |
| 96 Traceback (most recent call last): | |
| 97 File "<string>", line 1, in <module> | |
| 98 File "<string>", line 1, in foo | |
| 99 ReferenceError: bar is not defined | |
| 100 -1 | |
| 101 </pre> | |
| 102 </blockquote> | |
|
24
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
103 <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
|
104 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
|
105 like debugging Python code as possible.</p> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
106 </div> |
| 28 | 107 <div class="section" id="exceptions"> |
| 108 <h1>Exceptions</h1> | |
|
24
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
109 <p>Any exceptions raised by wrapped Python functions need to be of type |
| 28 | 110 <tt class="docutils literal">pydermonkey.ScriptError</tt> to be propagated into calling JavaScript code; |
|
24
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
111 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
|
112 stack is unrolled.</p> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
113 <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
|
114 <blockquote> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
115 <pre class="doctest-block"> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
116 >>> @jsexposed |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
117 ... def fail(): |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
118 ... o() |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
119 >>> sandbox.root.fail = fail |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
120 </pre> |
|
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 <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
|
123 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
|
124 is simply halted:</p> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
125 <blockquote> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
126 <pre class="doctest-block"> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
127 >>> sandbox.run_script("try { fail(); } catch (e) {}", |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
128 ... stderr=sys.stdout) #doctest: +ELLIPSIS |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
129 An internal error occurred. |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
130 Traceback (most recent call last): |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
131 ... |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
132 NameError: global name 'o' is not defined |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
133 -1 |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
134 </pre> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
135 </blockquote> |
| 28 | 136 <p>Note that a <tt class="docutils literal">KeyboardInterrupt</tt> triggered while JS is executing will |
|
24
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
137 have similar effect.</p> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
138 </div> |
|
22
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
139 </div> |
|
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
140 <div class="footer"> |
|
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
141 <hr class="footer" /> |
| 28 | 142 <a class="reference external" href="docs.txt">View document source</a>. |
|
22
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
143 |
| 21 | 144 </div> |
| 145 </body> | |
| 146 </html> |