pydertron: docs.txt annotate

annotate docs.txt @ 24:c2c369402a2e

Added more docs, fixed edge cases.

author	Atul Varma <varmaa@toolness.com>
date	Thu, 10 Sep 2009 22:32:45 -0700
parents	7cbbec55aef6
children	351819baecd1

rev	line source
22 915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	1 =========
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	2 Pydertron
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	3 =========
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	4
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	5 Pydertron is a high-level wrapper for `Pydermonkey`__ that
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	6 provides convenient, secure object wrapping between JS and Python
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	7 space.
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	8
24 c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	9 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	10 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	11 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	12 inter-language interaction.
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	13
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	14 The Basics
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	15 ----------
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	16
22 915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	17 The ``JsSandbox`` class encapsulates a JavaScript runtime, context, global
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	18 object, and a simple `SecurableModule`__ implementation that complies
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	19 with the `CommonJS`__ standard. It also provides a high-level bridge between
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	20 Python and JavaScript so that you don't need to deal with any of the
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	21 low-level details of the Pydermonkey API.
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	22
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	23 __ http://code.google.com/p/pydermonkey
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	24 __ http://wiki.commonjs.org/wiki/CommonJS/Modules/SecurableModules
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	25 __ http://wiki.commonjs.org/wiki/CommonJS
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	26
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	27 For instance, here we'll create a ``JsSandbox`` whose module root
23 7cbbec55aef6 Minor modifications. Atul Varma <varmaa@toolness.com> parents: 22 diff changeset	28 points to the `monkeys`__ SecurableModule compliance test over HTTP:
22 915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	29
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	30 >>> url = ("http://interoperablejs.googlecode.com/svn/trunk/"
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	31 ... "compliance/monkeys/")
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	32 >>> sandbox = JsSandbox(HttpFileSystem(url))
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	33
23 7cbbec55aef6 Minor modifications. Atul Varma <varmaa@toolness.com> parents: 22 diff changeset	34 __ http://interoperablejs.googlecode.com/svn/trunk/compliance/monkeys/
7cbbec55aef6 Minor modifications. Atul Varma <varmaa@toolness.com> parents: 22 diff changeset	35
22 915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	36 This compliance test requires a global ``sys`` object that contains one
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	37 method, ``print()``, that takes two arguments. First, we'll create the
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	38 ``print()`` function and prepare it for exposure to JS code:
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	39
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	40 >>> @jsexposed
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	41 ... def jsprint(message, label):
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	42 ... print message, label
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	43
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	44 Note the use of the ``@jsexposed`` decorator: all this does is set
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	45 the function's ``__jsexposed__`` attribute to ``True``. This is
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	46 done for security purposes: only Python callables satisfying this
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	47 criteria will be exposed to JavaScript code, to ensure that
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	48 untrusted JS can't accidentally gain access to privileged Python
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	49 functionality.
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	50
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	51 Creating a JS object can be done like this:
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	52
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	53 >>> system = sandbox.new_object()
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	54
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	55 We can now access and set properties on this object via either
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	56 item or attribute lookup, just like in JavaScript. Because
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	57 ``print`` is a reserved word in Python, though, we'll use item
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	58 lookup to set the property here:
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	59
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	60 >>> system['print'] = jsprint
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	61
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	62 Now we tell the sandbox that we want the ``sys`` object to be a
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	63 global:
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	64
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	65 >>> sandbox.set_globals(sys = system)
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	66
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	67 And finally, we execute the compliance test by running a one-line
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	68 script that imports the 'program' module, like so:
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	69
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	70 >>> sandbox.run_script("require('program');")
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	71 PASS monkeys permitted pass
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	72 DONE info
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	73 0
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	74
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	75 Note the ``0`` in the last line: this is the return value of
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	76 ``sandbox.run_script()``, which returns ``0`` on success, and
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	77 ``-1`` if an exception was raised. For instance, the output of bad
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	78 code looks like this:
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	79
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	80 >>> sandbox.run_script("(function foo() { bar(); })();",
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	81 ... stderr=sys.stdout)
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	82 Traceback (most recent call last):
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	83 File "<string>", line 1, in <module>
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	84 File "<string>", line 1, in foo
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	85 ReferenceError: bar is not defined
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	86 -1
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	87
24 c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	88 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	89 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	90 like debugging Python code as possible.
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	91
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	92 Exceptions
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	93 ----------
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	94
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	95 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	96 ``pydermonkey.error`` to be propagated into calling JavaScript code;
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	97 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	98 stack is unrolled.
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	99
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	100 For example, here's a function that's bound to fail:
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	101
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	102 >>> @jsexposed
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	103 ... def fail():
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	104 ... o()
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	105 >>> sandbox.root.fail = fail
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	106
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	107 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	108 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	109 is simply halted:
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	110
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	111 >>> sandbox.run_script("try { fail(); } catch (e) {}",
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	112 ... stderr=sys.stdout) #doctest: +ELLIPSIS
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	113 An internal error occurred.
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	114 Traceback (most recent call last):
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	115 ...
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	116 NameError: global name 'o' is not defined
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	117 -1
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	118
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	119 Note that a ``KeyboardInterrupt`` triggered while JS is executing will
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	120 have similar effect.

Mercurial > pydertron

annotate docs.txt @ 24:c2c369402a2e