Mercurial > pydertron
annotate docs.html @ 26:c4181cc0771d
Fixed a bug whereby pydermonkey.Object instances couldn't be passed from python-space into JS-space. I think.
| author | Atul Varma <varmaa@toolness.com> |
|---|---|
| date | Sun, 21 Mar 2010 22:11:51 -0700 |
| parents | 351819baecd1 |
| children | d28100e071a7 |
| 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> |
| 25 | 13 <p>Pydertron is an experimental high-level wrapper for <a class="reference" href="http://code.google.com/p/pydermonkey">Pydermonkey</a> |
| 14 that provides convenient, secure object wrapping between JS and Python | |
| 21 | 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> |
| 25 | 20 <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 questions or comments to <a class="reference" href="mailto:atul@mozilla.com">atul@mozilla.com</a>.</p> | |
|
24
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
23 <div class="section"> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
24 <h1><a id="the-basics" name="the-basics">The Basics</a></h1> |
| 21 | 25 <p>The <tt class="docutils literal"><span class="pre">JsSandbox</span></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 with the <a class="reference" 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 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 | |
| 23 | 31 points to the <a class="reference" href="http://interoperablejs.googlecode.com/svn/trunk/compliance/monkeys/">monkeys</a> SecurableModule compliance test over HTTP:</p> |
| 21 | 32 <blockquote> |
| 33 <pre class="doctest-block"> | |
| 34 >>> url = ("http://interoperablejs.googlecode.com/svn/trunk/" | |
| 35 ... "compliance/monkeys/") | |
| 36 >>> sandbox = JsSandbox(HttpFileSystem(url)) | |
| 37 </pre> | |
| 38 </blockquote> | |
| 39 <p>This compliance test requires a global <tt class="docutils literal"><span class="pre">sys</span></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 <tt class="docutils literal"><span class="pre">print()</span></tt> function and prepare it for exposure to JS code:</p> | |
| 42 <blockquote> | |
| 43 <pre class="doctest-block"> | |
| 44 >>> @jsexposed | |
| 45 ... def jsprint(message, label): | |
| 46 ... print message, label | |
| 47 </pre> | |
| 48 </blockquote> | |
| 49 <p>Note the use of the <tt class="docutils literal"><span class="pre">@jsexposed</span></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 done for security purposes: only Python callables satisfying this | |
| 52 criteria will be exposed to JavaScript code, to ensure that | |
| 53 untrusted JS can't accidentally gain access to privileged Python | |
| 54 functionality.</p> | |
| 55 <p>Creating a JS object can be done like this:</p> | |
| 56 <blockquote> | |
| 57 <pre class="doctest-block"> | |
| 58 >>> system = sandbox.new_object() | |
| 59 </pre> | |
| 60 </blockquote> | |
| 61 <p>We can now access and set properties on this object via either | |
| 62 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 lookup to set the property here:</p> | |
| 65 <blockquote> | |
| 66 <pre class="doctest-block"> | |
| 67 >>> system['print'] = jsprint | |
| 68 </pre> | |
| 69 </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 global:</p> | |
| 72 <blockquote> | |
| 73 <pre class="doctest-block"> | |
| 74 >>> sandbox.set_globals(sys = system) | |
| 75 </pre> | |
| 76 </blockquote> | |
| 77 <p>And finally, we execute the compliance test by running a one-line | |
| 78 script that imports the 'program' module, like so:</p> | |
| 79 <blockquote> | |
| 80 <pre class="doctest-block"> | |
| 81 >>> sandbox.run_script("require('program');") | |
| 82 PASS monkeys permitted pass | |
| 83 DONE info | |
| 84 0 | |
| 85 </pre> | |
| 86 </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 <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"><span class="pre">-1</span></tt> if an exception was raised. For instance, the output of bad | |
| 90 code looks like this:</p> | |
| 91 <blockquote> | |
| 92 <pre class="doctest-block"> | |
| 93 >>> sandbox.run_script("(function foo() { bar(); })();", | |
| 94 ... stderr=sys.stdout) | |
| 95 Traceback (most recent call last): | |
| 96 File "<string>", line 1, in <module> | |
| 97 File "<string>", line 1, in foo | |
| 98 ReferenceError: bar is not defined | |
| 99 -1 | |
| 100 </pre> | |
| 101 </blockquote> | |
|
24
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
102 <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
|
103 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
|
104 like debugging Python code as possible.</p> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
105 </div> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
106 <div class="section"> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
107 <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
|
108 <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
|
109 <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
|
110 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
|
111 stack is unrolled.</p> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
112 <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
|
113 <blockquote> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
114 <pre class="doctest-block"> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
115 >>> @jsexposed |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
116 ... def fail(): |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
117 ... o() |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
118 >>> sandbox.root.fail = fail |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
119 </pre> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
120 </blockquote> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
121 <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
|
122 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
|
123 is simply halted:</p> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
124 <blockquote> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
125 <pre class="doctest-block"> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
126 >>> sandbox.run_script("try { fail(); } catch (e) {}", |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
127 ... stderr=sys.stdout) #doctest: +ELLIPSIS |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
128 An internal error occurred. |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
129 Traceback (most recent call last): |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
130 ... |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
131 NameError: global name 'o' is not defined |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
132 -1 |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
133 </pre> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
134 </blockquote> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
135 <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
|
136 have similar effect.</p> |
|
c2c369402a2e
Added more docs, fixed edge cases.
Atul Varma <varmaa@toolness.com>
parents:
23
diff
changeset
|
137 </div> |
|
22
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
138 </div> |
|
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
139 <div class="footer"> |
|
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
140 <hr class="footer" /> |
|
915fdf283ac5
Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
21
diff
changeset
|
141 <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
|
142 |
| 21 | 143 </div> |
| 144 </body> | |
| 145 </html> |