pydertron: docs.txt annotate

annotate docs.txt @ 34:739c87de4667

added another gc test

author	Atul Varma <avarma@mozilla.com>
date	Mon, 10 May 2010 20:57:23 -0700
parents	0b00162939ae
children

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
25 351819baecd1 Updated docs. Atul Varma <varmaa@toolness.com> parents: 24 diff changeset	5 Pydertron is an experimental high-level wrapper for `Pydermonkey`__
351819baecd1 Updated docs. Atul Varma <varmaa@toolness.com> parents: 24 diff changeset	6 that provides convenient, secure object wrapping between JS and Python
22 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
25 351819baecd1 Updated docs. Atul Varma <varmaa@toolness.com> parents: 24 diff changeset	14 Pydertron is currently hosted at
351819baecd1 Updated docs. Atul Varma <varmaa@toolness.com> parents: 24 diff changeset	15 http://hg.toolness.com/pydertron. Please feel free to send any
351819baecd1 Updated docs. Atul Varma <varmaa@toolness.com> parents: 24 diff changeset	16 questions or comments to atul@mozilla.com.
351819baecd1 Updated docs. Atul Varma <varmaa@toolness.com> parents: 24 diff changeset	17
24 c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	18 The Basics
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	19 ----------
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	20
22 915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	21 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	22 object, and a simple `SecurableModule`__ implementation that complies
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	23 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	24 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	25 low-level details of the Pydermonkey API.
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 __ http://code.google.com/p/pydermonkey
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	28 __ http://wiki.commonjs.org/wiki/CommonJS/Modules/SecurableModules
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	29 __ http://wiki.commonjs.org/wiki/CommonJS
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	30
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	31 For instance, here we'll create a ``JsSandbox`` whose module root
23 7cbbec55aef6 Minor modifications. Atul Varma <varmaa@toolness.com> parents: 22 diff changeset	32 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	33
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	34 >>> url = ("http://interoperablejs.googlecode.com/svn/trunk/"
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	35 ... "compliance/monkeys/")
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	36 >>> sandbox = JsSandbox(HttpFileSystem(url))
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	37
23 7cbbec55aef6 Minor modifications. Atul Varma <varmaa@toolness.com> parents: 22 diff changeset	38 __ http://interoperablejs.googlecode.com/svn/trunk/compliance/monkeys/
7cbbec55aef6 Minor modifications. Atul Varma <varmaa@toolness.com> parents: 22 diff changeset	39
22 915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	40 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	41 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	42 ``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	43
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	44 >>> @jsexposed
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	45 ... def jsprint(message, label):
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	46 ... print message, label
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	47
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	48 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	49 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	50 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	51 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	52 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	53 functionality.
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 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	56
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	57 >>> system = sandbox.new_object()
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	58
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	59 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	60 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	61 ``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	62 lookup to set the property here:
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	63
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	64 >>> system['print'] = jsprint
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	65
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	66 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	67 global:
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	68
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	69 >>> sandbox.set_globals(sys = system)
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	70
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	71 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	72 script that imports the 'program' module, like so:
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	73
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	74 >>> sandbox.run_script("require('program');")
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	75 PASS monkeys permitted pass
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	76 DONE info
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	77 0
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	78
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	79 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	80 ``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	81 ``-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	82 code looks like this:
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	83
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	84 >>> sandbox.run_script("(function foo() { bar(); })();",
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	85 ... stderr=sys.stdout)
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	86 Traceback (most recent call last):
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	87 File "<string>", line 1, in <module>
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	88 File "<string>", line 1, in foo
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	89 ReferenceError: bar is not defined
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	90 -1
915fdf283ac5 Moved docs out to a separate file. Atul Varma <varmaa@toolness.com> parents: diff changeset	91
24 c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	92 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	93 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	94 like debugging Python code as possible.
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	95
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	96 Exceptions
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	97 ----------
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	98
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	99 Any exceptions raised by wrapped Python functions need to be of type
27 0b00162939ae Fixed to work w/ latest Pydermonkey tip. Atul Varma <avarma@mozilla.com> parents: 25 diff changeset	100 ``pydermonkey.ScriptError`` to be propagated into calling JavaScript code;
24 c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	101 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	102 stack is unrolled.
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	103
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	104 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	105
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	106 >>> @jsexposed
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	107 ... def fail():
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	108 ... o()
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	109 >>> sandbox.root.fail = fail
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 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	112 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	113 is simply halted:
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	114
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	115 >>> sandbox.run_script("try { fail(); } catch (e) {}",
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	116 ... stderr=sys.stdout) #doctest: +ELLIPSIS
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	117 An internal error occurred.
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	118 Traceback (most recent call last):
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	119 ...
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	120 NameError: global name 'o' is not defined
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	121 -1
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	122
c2c369402a2e Added more docs, fixed edge cases. Atul Varma <varmaa@toolness.com> parents: 23 diff changeset	123 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	124 have similar effect.

Mercurial > pydertron

annotate docs.txt @ 34:739c87de4667