summaryrefslogtreecommitdiff
path: root/libraries/python-spidermonkey/README.md
blob: 1ddc3d1fe46fa94a2741753c8e7429ad70c04e58 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
Execute arbitrary JavaScript code from Python. Allows you to reference
arbitrary Python objects and functions in the JavaScript VM

Having issues?
==============

The project support site can be found at [lighthouseapp.com][lh].

Requirements
============

Pkg-Config
----------

Mac OS X:

This should be installed by default. If not there is a port package:

    $ sudo port install pkgconfig

Debian/Ubuntu:

This is also generally installed by default, but I have reports of it being
otherwise.

    $ sudo apt-get install pkg-config

Gentoo:

    $ sudo emerge dev-util/pkgconfig

Python Development Files
------------------------

Mac OS X:

If you installed Python via port then the headers should already be installed.
I have not heard reports of problems from people using the bundled
interpreters.

Debian/Ubuntu:

    $ sudo apt-get install pythonX.X-dev

Where X.X is the version of Python you are using. I have not tested
python-spidermonkey on Py3K so it may be horribly broken there.

Gentoo:

If you have python installed, then the headers should already be installed.

Netscape Portable Runtime (nspr)
--------------------------------

The nspr library is required for building the Spidermonkey sources. You should
be able to grab it from your package manager of choice with something like the
following:

Mac OS X:

    $ sudo port install nspr

Debian/Ubuntu:

    $ sudo apt-get install libnspr4-dev
    
Gentoo:

    $ sudo emerge dev-libs/nspr

Alternatively you can build from [source][nspr]. If you choose this route make
sure that the nspr-config command is on your $PATH when running the install
commands below.

If you choose this route make
sure that the pkg-config command is on your `$PATH` when running the install
commands below. Additionally, make sure that `$PKG_CONFIG_PATH` is properly
set.

XULRunner (optional)
--------------------
You can optionally build the extension linked to your system's spidermonkey
library, which is installed with XULRunner. You should be able to grab it from
your package manager of choice with something like the following:

Mac OS X:

    $ sudo port install xulrunner

Debian/Ubuntu:

    $ sudo apt-get install xulrunner-1.9-dev

Gentoo:

    $ sudo emerge net-libs/xulrunner

As with [nspr][nspr], you can also build [xulrunner][xulrunner] from source. And as with [nspr][nspr] you need to make sure hat `$PATH` and `$PKG_CONFIG_PATH` are properly set when building the module.

Installation
============

    $ git clone git://github.com/davisp/python-spidermonkey.git
    $ cd python-spidermonkey
    $ python setup.py build
    $ python setup.py test

    $ sudo python setup.py install

    *OR*
    
    $ sudo python setup.py develop

If you want to build with the system spidermonkey library, replace the build
command with the following:

    $ python setup.py --system-library build

Examples
========

Basics
------

    >>> import spidermonkey
    >>> rt = spidermonkey.Runtime()
    >>> cx = rt.new_context()
    >>> cx.execute("var x = 3; x *= 4; x;")
    12
    >>> class Orange(object):
    ...   def is_ripe(self,arg):
    ...       return "ripe %s" % arg
    ...
    >>> fruit = Orange()
    >>> cx.add_global("apple", fruit)
    >>> cx.execute('"Show me the " + apple.is_ripe("raisin");')
    u'Show me the ripe raisin'


Playing with Classes
--------------------

    >>> import spidermonkey
    >>> class Monkey(object):
    ...     def __init__(self):
    ...         self.baz = "blammo"
    ...     def wrench(self, arg):
    ...         return "%s now wrenched" % arg
    ...
    >>> rt = spidermonkey.Runtime()
    >>> cx = rt.new_context()
    >>> cx.add_global("Monkey", Monkey)
    >>> monkey = cx.execute('var x = new Monkey(); x.baz = "schmammo"; x;')
    >>> monkey.baz
    u'schmammo'
    >>> monkey.__class__.__name__
    'Monkey'


JavaScript Functions
--------------------

    >>> import spidermonkey
    >>> rt = spidermonkey.Runtime()
    >>> cx = rt.new_context()
    >>> func = cx.execute('function(val) {return "whoosh: " + val;}')
    >>> func("zipper!");
    u'whoosh: zipper!'


Filtering access to Python
--------------------------

    >>> import spidermonkey
    >>> rt = spidermonkey.Runtime()
    >>> def checker(obj, name):
    ...     return not name.startswith("_")
    ...
    >>> cx = rt.new_context(access=checker)
    >>> # Alternatively:
    >>> cx.set_access()                                     #doctest: +ELLIPSIS
    <function checker at ...>
    >>> cx.set_access(checker)                              #doctest: +ELLIPSIS
    <function checker at ...>
    >>> cx.add_global("fish", {"gold": "gone", "_old_lady": "huzza"})
    >>> cx.execute('fish["_old_lady"];')
    Traceback (most recent call last):
            ...
    JSError: Error executing JavaScript.


Previous Authors
================

* John J. Lee
* Atul Varma

[lh]: http://davisp.lighthouseapp.com/projects/26898-python-spidermonkey/overview
[nspr]: ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases
[xulrunner]: ftp://ftp.mozilla.org/pub/mozilla.org/xulrunner/releases