Mercurial > pydertron
diff 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 diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs.html Thu Sep 10 16:37:33 2009 -0700 @@ -0,0 +1,100 @@ +<?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>