Mercurial > pydertron
changeset 21:cb73bb169b67
Added html docs.
| author | Atul Varma <varmaa@toolness.com> |
|---|---|
| date | Thu, 10 Sep 2009 16:37:33 -0700 |
| parents | d382ca63d43f |
| children | 915fdf283ac5 |
| files | build_docs docs.css docs.html pydertron.py |
| diffstat | 4 files changed, 160 insertions(+), 22 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build_docs Thu Sep 10 16:37:33 2009 -0700 @@ -0,0 +1,5 @@ +#! /bin/bash + +export DOCS=docs.html +python -c "import pydertron; print pydertron.__doc__" | rst2html.py --link-stylesheet --stylesheet-path=docs.css > $DOCS +echo Documentation written to $DOCS.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs.css Thu Sep 10 16:37:33 2009 -0700 @@ -0,0 +1,27 @@ +body { + font-family: palatino, georgia, verdana, arial, sans-serif; + font-size: 12pt; +} + +.doctest-block { + font-family: monaco, andale mono, lucidatypewriter, courier, + courier new, monospace; + font-size: 10pt; + background-color: #eeeeee; +} + +.literal { + font-family: monaco, andale mono, lucidatypewriter, courier, + courier new, monospace; + font-size: 10pt; + background-color: #eeeeee; +} + +a { + color: black; +} + +.document { + width: 50em; + margin: 0 auto; +}
--- /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>
--- a/pydertron.py Thu Sep 10 15:44:18 2009 -0700 +++ b/pydertron.py Thu Sep 10 16:37:33 2009 -0700 @@ -35,48 +35,54 @@ # ***** END LICENSE BLOCK ***** """ - Pydertron is a high-level wrapper for Pydermonkey that provides convenient, - secure object wrapping between JS and Python space. + Pydertron is a high-level wrapper for `Pydermonkey`__ that + provides convenient, secure object wrapping between JS and Python + space. - The JsSandbox class encapsulates a JavaScript runtime, context, global - object, and a simple SecurableModule implementation that complies - with the CommonJS standard. It also provides a high-level bridge between + The ``JsSandbox`` class encapsulates a JavaScript runtime, context, global + object, and a simple `SecurableModule`__ implementation that complies + with the `CommonJS`__ 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. - For instance, here we'll create a JsSandbox whose module root - points to the 'monkeys' SecurableModule compliance test over HTTP: + __ http://code.google.com/p/pydermonkey + __ http://wiki.commonjs.org/wiki/CommonJS/Modules/SecurableModules + __ http://wiki.commonjs.org/wiki/CommonJS + + For instance, here we'll create a ``JsSandbox`` whose module root + points to the ``monkeys`` SecurableModule compliance test over HTTP: >>> url = ("http://interoperablejs.googlecode.com/svn/trunk/" ... "compliance/monkeys/") >>> sandbox = JsSandbox(HttpFileSystem(url)) - This compliance test requires a global 'sys' object that contains one - method, print(), that takes two arguments. First, we'll create the - print() function and prepare it for exposure to JS code: + This compliance test requires a global ``sys`` object that contains one + method, ``print()``, that takes two arguments. First, we'll create the + ``print()`` function and prepare it for exposure to JS code: >>> @jsexposed ... def jsprint(message, label): ... print message, label - Note the use of the @jsexposed decorator: all this does is set the - function's __jsexposed__ attribute to True. 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. + Note the use of the ``@jsexposed`` decorator: all this does is set + the function's ``__jsexposed__`` attribute to ``True``. 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. Creating a JS object can be done like this: >>> system = sandbox.new_object() We can now access and set properties on this object via either - item or attribute lookup, just like in JavaScript. Because 'print' - is a reserved word in Python, though, we'll use item lookup to set - the property here: + item or attribute lookup, just like in JavaScript. Because + ``print`` is a reserved word in Python, though, we'll use item + lookup to set the property here: >>> system['print'] = jsprint - Now we tell the sandbox that we want the 'sys' object to be a + Now we tell the sandbox that we want the ``sys`` object to be a global: >>> sandbox.set_globals(sys = system) @@ -89,9 +95,9 @@ DONE info 0 - Note the '0' in the last line: this is the return value of - sandbox.run_script(), which returns 0 on success, and -1 if an - exception was raised. For instance, the output of bad + Note the ``0`` in the last line: this is the return value of + ``sandbox.run_script()``, which returns ``0`` on success, and + ``-1`` if an exception was raised. For instance, the output of bad code looks like this: >>> sandbox.run_script("(function foo() { bar(); })();",