Mercurial > pydertron
view docs.html @ 21:cb73bb169b67
Added html docs.
| author | Atul Varma <varmaa@toolness.com> |
|---|---|
| date | Thu, 10 Sep 2009 16:37:33 -0700 |
| parents | |
| children | 915fdf283ac5 |
line wrap: on
line source
<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> <title></title> <link rel="stylesheet" href="docs.css" type="text/css" /> </head> <body> <div class="document"> <blockquote> <p>Pydertron is a high-level wrapper for <a class="reference" href="http://code.google.com/p/pydermonkey">Pydermonkey</a> that provides convenient, secure object wrapping between JS and Python space.</p> <p>The <tt class="docutils literal"><span class="pre">JsSandbox</span></tt> class encapsulates a JavaScript runtime, context, global object, and a simple <a class="reference" href="http://wiki.commonjs.org/wiki/CommonJS/Modules/SecurableModules">SecurableModule</a> implementation that complies with the <a class="reference" href="http://wiki.commonjs.org/wiki/CommonJS">CommonJS</a> standard. It also provides a high-level bridge between Python and JavaScript so that you don't need to deal with any of the low-level details of the Pydermonkey API.</p> <p>For instance, here we'll create a <tt class="docutils literal"><span class="pre">JsSandbox</span></tt> whose module root points to the <tt class="docutils literal"><span class="pre">monkeys</span></tt> SecurableModule compliance test over HTTP:</p> <blockquote> <pre class="doctest-block"> >>> url = ("http://interoperablejs.googlecode.com/svn/trunk/" ... "compliance/monkeys/") >>> sandbox = JsSandbox(HttpFileSystem(url)) </pre> </blockquote> <p>This compliance test requires a global <tt class="docutils literal"><span class="pre">sys</span></tt> object that contains one method, <tt class="docutils literal"><span class="pre">print()</span></tt>, that takes two arguments. First, we'll create the <tt class="docutils literal"><span class="pre">print()</span></tt> function and prepare it for exposure to JS code:</p> <blockquote> <pre class="doctest-block"> >>> @jsexposed ... def jsprint(message, label): ... print message, label </pre> </blockquote> <p>Note the use of the <tt class="docutils literal"><span class="pre">@jsexposed</span></tt> decorator: all this does is set 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 done for security purposes: only Python callables satisfying this criteria will be exposed to JavaScript code, to ensure that untrusted JS can't accidentally gain access to privileged Python functionality.</p> <p>Creating a JS object can be done like this:</p> <blockquote> <pre class="doctest-block"> >>> system = sandbox.new_object() </pre> </blockquote> <p>We can now access and set properties on this object via either item or attribute lookup, just like in JavaScript. Because <tt class="docutils literal"><span class="pre">print</span></tt> is a reserved word in Python, though, we'll use item lookup to set the property here:</p> <blockquote> <pre class="doctest-block"> >>> system['print'] = jsprint </pre> </blockquote> <p>Now we tell the sandbox that we want the <tt class="docutils literal"><span class="pre">sys</span></tt> object to be a global:</p> <blockquote> <pre class="doctest-block"> >>> sandbox.set_globals(sys = system) </pre> </blockquote> <p>And finally, we execute the compliance test by running a one-line script that imports the 'program' module, like so:</p> <blockquote> <pre class="doctest-block"> >>> sandbox.run_script("require('program');") PASS monkeys permitted pass DONE info 0 </pre> </blockquote> <p>Note the <tt class="docutils literal"><span class="pre">0</span></tt> in the last line: this is the return value of <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 <tt class="docutils literal"><span class="pre">-1</span></tt> if an exception was raised. For instance, the output of bad code looks like this:</p> <blockquote> <pre class="doctest-block"> >>> sandbox.run_script("(function foo() { bar(); })();", ... stderr=sys.stdout) Traceback (most recent call last): File "<string>", line 1, in <module> File "<string>", line 1, in foo ReferenceError: bar is not defined -1 </pre> </blockquote> <p>Note that the traceback displayed is actually referring to JavaScript code: one of Pydertron's helpful conveniences is that it makes debugging JS code as much like debugging Python code as possible.</p> </blockquote> </div> </body> </html>