Mercurial > pydertron

annotate docs.txt @ 23:7cbbec55aef6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Minor modifications.
author Atul Varma <varmaa@toolness.com>
date Thu, 10 Sep 2009 17:05:05 -0700
parents 915fdf283ac5
children c2c369402a2e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
9 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
10 object, and a simple `SecurableModule`__ implementation that complies
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
11 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
12 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
13 low-level details of the Pydermonkey API.
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
14
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
15 __ http://code.google.com/p/pydermonkey
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
16 __ http://wiki.commonjs.org/wiki/CommonJS/Modules/SecurableModules
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
17 __ http://wiki.commonjs.org/wiki/CommonJS
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
18
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
19 For instance, here we'll create a ``JsSandbox`` whose module root
23
7cbbec55aef6 Minor modifications.
Atul Varma <varmaa@toolness.com>
parents: 22
diff changeset
20 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
21
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
22 >>> url = ("http://interoperablejs.googlecode.com/svn/trunk/"
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
23 ... "compliance/monkeys/")
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
24 >>> sandbox = JsSandbox(HttpFileSystem(url))
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
25
23
7cbbec55aef6 Minor modifications.
Atul Varma <varmaa@toolness.com>
parents: 22
diff changeset
26 __ http://interoperablejs.googlecode.com/svn/trunk/compliance/monkeys/
7cbbec55aef6 Minor modifications.
Atul Varma <varmaa@toolness.com>
parents: 22
diff changeset
27
22
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
28 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
29 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
30 ``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
31
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
32 >>> @jsexposed
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
33 ... def jsprint(message, label):
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
34 ... print message, label
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
35
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
36 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
37 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
38 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
39 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
40 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
41 functionality.
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
42
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
43 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
44
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
45 >>> system = sandbox.new_object()
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
46
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
47 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
48 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
49 ``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
50 lookup to set the property here:
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
51
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
52 >>> system['print'] = jsprint
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
53
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
54 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
55 global:
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 >>> sandbox.set_globals(sys = system)
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 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
60 script that imports the 'program' module, like so:
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 >>> sandbox.run_script("require('program');")
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
63 PASS monkeys permitted pass
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
64 DONE info
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
65 0
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 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
68 ``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
69 ``-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
70 code looks like this:
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
71
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
72 >>> sandbox.run_script("(function foo() { bar(); })();",
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
73 ... stderr=sys.stdout)
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
74 Traceback (most recent call last):
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
75 File "<string>", line 1, in <module>
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
76 File "<string>", line 1, in foo
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
77 ReferenceError: bar is not defined
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
78 -1
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 Note that the traceback displayed is actually referring to
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
81 JavaScript code: one of Pydertron's helpful conveniences is that
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
82 it makes debugging JS code as much like debugging Python code as
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
83 possible.