Mercurial > pymonkey

comparison README @ 49:7401af070bb8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Moved README to Sphinx documentation. Keeping the rendered docs in the repository so that they can be viewed via HG and locally by people who don't have Sphinx installed.
author Atul Varma <varmaa@toolness.com>
date Tue, 07 Jul 2009 09:26:36 -0700
parents 04a6e9a67ae5
children e455f0f00e98
comparison
equal deleted inserted replaced
48:bc4263c6ae82 49:7401af070bb8
1 Pymonkey README 1 Pymonkey README
2 --------------- 2 ---------------
3 3
4 Pymonkey is a pure Python CAPI module to expose the Mozilla 4 Pymonkey is a Python C extension module to expose the Mozilla
5 SpiderMonkey engine to Python. 5 SpiderMonkey engine to Python.
6 6
7 Rationale and Goals: 7 Please run "python manage.py docs" to open the full Pymonkey
8 8 documentation in your web browser.
9 * Python and JS are fairly complementary languages. Python provides
10 tremendous developer productivity via its dynamic language
11 features, its vibrant library of third-party client-side code, and
12 its ease of readability. JavaScript, on the other hand, is widely
13 known by a vast number of casual programmers due to its
14 availability in web browsers; it was also envisioned from its
15 conception to be executed as untrusted code, which gives it a lot
16 of security features that Python has always lacked.
17
18 * There's an increasing need for being able to run JS on the server
19 side--particularly untrusted JS [1]. For instance, being able to
20 duplicate business logic on the server and client (i.e., browser)
21 would be very useful. There's Java-based solutions like Rhino out
22 there, but nothing really mature is available for the Python
23 world. Ideally, Pymonkey should enable a Python programmer to
24 create a custom sandboxed environment for executing JS code
25 without needing to write any C.
26
27 * Pymonkey should have awesome Sphinx documentation with doctests
28 and all the trappings of a model Python package. Not only should
29 it be easy for Python programmers to learn how to use the module,
30 but it should also be easy for them to learn more about how
31 SpiderMonkey works by reading the docs and playing around with the
32 code.
33
34 * Pymonkey needs to have outstanding developer ergonomics. Full
35 cross-language stack tracebacks should be available, for instance,
36 and developers should be able to easily debug. Access to memory
37 profiling facilities in JS-land is a must.
38
39 * The module uses the Python CAPI: no SWIG, Pyrex, or other
40 intermediaries. The obvious disadvantage here is that it means
41 more C code, but the advantages are that
42
43 (A) contributors don't need to learn anything other than the
44 Python and SpiderMonkey C APIs to contribute, and
45
46 (B) it means one less dependency, which makes the build process
47 easier.
48
49 The module also doesn't use ctypes because using the SpiderMonkey
50 C API requires fairly complex preprocessor macros defined in the
51 engine's header files.
52
53 Finally, Atul has never really made a straight Python CAPI module
54 before, so he wanted to give it a try.
55
56 [1] https://wiki.mozilla.org/ServerJS
57
58 Building and Testing
59 --------------------
60
61 You can either build SpiderMonkey off the mozilla-central HG
62 repository, or off a mirror I made of its SpiderMonkey directory. The
63 latter can be obtained here:
64
65 http://hg.toolness.com/spidermonkey/
66
67 Just HG clone that repository and read the instructions in the README
68 to build SpiderMonkey.
69
70 Then come back to the root of your pymonkey repository and run:
71
72 python manage.py build --static --objdir=PATH_TO_OBJDIR
73
74 Where PATH_TO_OBJDIR is the path to your Mozilla/SpiderMonkey build's
75 objdir.
76
77 Note that at the moment, the build script is only tested on OS X.
78
79 Example Code
80 ------------
81
82 Right now the only example code that exists is in the test suite at
83 test_pymonkey.py. Check it out and feel free to add more.
84
85 Challenges
86 ----------
87
88 There's a number of challenges that need to be resolved before
89 pymonkey can be really usable. Here's some of them.
90
91 Garbage Collection
92
93 Python's garbage collection uses reference counting, whereas
94 SpiderMonkey's is mark-and-sweep. We'll likely run into situations
95 where there are cycles that exist between SpiderMonkey and Python
96 objects; this is actually quite similar to the relationship between
97 XPCOM and JavaScript in the Mozilla platform--XPCOM uses reference
98 counting too--so detecting such cycles will probably involve creating
99 something akin to XPCOM's cycle collector [1].
100
101 [1] https://developer.mozilla.org/en/Interfacing_with_the_XPCOM_cycle_collector