Mercurial > pydertron

annotate docs.txt @ 22:915fdf283ac5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Moved docs out to a separate file.
author Atul Varma <varmaa@toolness.com>
date Thu, 10 Sep 2009 16:59:18 -0700
parents
children 7cbbec55aef6
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
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
20 points to the ``monkeys`` SecurableModule compliance test over HTTP:
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
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
26 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
27 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
28 ``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
29
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
30 >>> @jsexposed
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
31 ... def jsprint(message, label):
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
32 ... print message, label
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 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
35 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
36 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
37 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
38 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
39 functionality.
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
40
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
41 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
42
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
43 >>> system = sandbox.new_object()
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 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
46 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
47 ``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
48 lookup to set the property here:
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
49
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
50 >>> system['print'] = jsprint
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 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
53 global:
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 >>> sandbox.set_globals(sys = system)
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 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
58 script that imports the 'program' module, like so:
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 >>> sandbox.run_script("require('program');")
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
61 PASS monkeys permitted pass
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
62 DONE info
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
63 0
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 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
66 ``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
67 ``-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
68 code looks like this:
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("(function foo() { bar(); })();",
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
71 ... stderr=sys.stdout)
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
72 Traceback (most recent call last):
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
73 File "<string>", line 1, in <module>
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
74 File "<string>", line 1, in foo
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
75 ReferenceError: bar is not defined
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
76 -1
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
77
915fdf283ac5 Moved docs out to a separate file.
Atul Varma <varmaa@toolness.com>
parents:
diff changeset
78 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
79 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
80 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
81 possible.