Mercurial > pydertron
changeset 22:915fdf283ac5
Moved docs out to a separate file.
| author | Atul Varma <varmaa@toolness.com> |
|---|---|
| date | Thu, 10 Sep 2009 16:59:18 -0700 |
| parents | cb73bb169b67 |
| children | 7cbbec55aef6 |
| files | build_docs docs.css docs.html docs.txt pydertron.py test_docs.py |
| diffstat | 6 files changed, 108 insertions(+), 81 deletions(-) [+] |
line wrap: on
line diff
--- a/build_docs Thu Sep 10 16:37:33 2009 -0700 +++ b/build_docs Thu Sep 10 16:59:18 2009 -0700 @@ -1,5 +1,5 @@ #! /bin/bash export DOCS=docs.html -python -c "import pydertron; print pydertron.__doc__" | rst2html.py --link-stylesheet --stylesheet-path=docs.css > $DOCS +rst2html.py docs.txt $DOCS -s --link-stylesheet --stylesheet-path=docs.css echo Documentation written to $DOCS.
--- a/docs.css Thu Sep 10 16:37:33 2009 -0700 +++ b/docs.css Thu Sep 10 16:59:18 2009 -0700 @@ -3,6 +3,10 @@ font-size: 12pt; } +.title { + font-weight: normal; +} + .doctest-block { font-family: monaco, andale mono, lucidatypewriter, courier, courier new, monospace; @@ -25,3 +29,15 @@ width: 50em; margin: 0 auto; } + +hr { + border: 0; + color: black; + background-color: black; + height: 1px; +} + +.footer { + width: 50em; + margin: 0 auto; +}
--- a/docs.html Thu Sep 10 16:37:33 2009 -0700 +++ b/docs.html Thu Sep 10 16:59:18 2009 -0700 @@ -4,12 +4,12 @@ <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> +<title>Pydertron</title> <link rel="stylesheet" href="docs.css" type="text/css" /> </head> <body> -<div class="document"> -<blockquote> +<div class="document" id="pydertron"> +<h1 class="title">Pydertron</h1> <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> @@ -94,7 +94,11 @@ 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> +<div class="footer"> +<hr class="footer" /> +<a class="reference" href="docs.txt">View document source</a>. + </div> </body> </html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs.txt Thu Sep 10 16:59:18 2009 -0700 @@ -0,0 +1,81 @@ +========= +Pydertron +========= + +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 +Python and JavaScript so that you don't need to deal with any of the +low-level details of the Pydermonkey API. + +__ 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: + + >>> @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. + +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: + + >>> system['print'] = jsprint + +Now we tell the sandbox that we want the ``sys`` object to be a +global: + + >>> sandbox.set_globals(sys = system) + +And finally, we execute the compliance test by running a one-line +script that imports the 'program' module, like so: + + >>> sandbox.run_script("require('program');") + PASS monkeys permitted pass + 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 +code looks like this: + + >>> 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 + +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.
--- a/pydertron.py Thu Sep 10 16:37:33 2009 -0700 +++ b/pydertron.py Thu Sep 10 16:59:18 2009 -0700 @@ -35,83 +35,9 @@ # ***** END LICENSE BLOCK ***** """ - Pydertron is a high-level wrapper for `Pydermonkey`__ that + 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 - Python and JavaScript so that you don't need to deal with any of the - low-level details of the Pydermonkey API. - - __ 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: - - >>> @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. - - 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: - - >>> system['print'] = jsprint - - Now we tell the sandbox that we want the ``sys`` object to be a - global: - - >>> sandbox.set_globals(sys = system) - - And finally, we execute the compliance test by running a one-line - script that imports the 'program' module, like so: - - >>> sandbox.run_script("require('program');") - PASS monkeys permitted pass - 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 - code looks like this: - - >>> 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 - - 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. """ import sys