Pymonkey README
---------------

Pymonkey is a pure Python CAPI module to expose the Mozilla
SpiderMonkey engine to Python.

Rationale and Goals:

  * There's an increasing need for being able to run JS on the server
    side--particularly untrusted JS [1].  There's Java-based solutions
    like Rhino out there, but nothing really mature is available for
    the Python world.  Ideally, Pymonkey should enable a Python
    programmer to create a custom sandboxed environment for executing
    JS code without needing to write any C.

  * Pymonkey should have awesome Sphinx documentation with doctests
    and all the trappings of a model Python package.  Not only should
    it be easy for Python programmers to learn how to use the module,
    but it should also be easy for them to learn more about how
    SpiderMonkey works by reading the docs and playing around with the
    code.

  * Pymonkey needs to have outstanding developer ergonomics. Full
    cross-language stack tracebacks should be available, for instance,
    and developers should be able to easily debug.  Access to memory
    profiling facilities in JS-land is a must.

  * The module uses the Python CAPI: no SWIG, Pyrex, or other
    intermediaries. The obvious disadvantage here is that it means
    more C code, but the advantages are that 
    
      (A) contributors don't need to learn anything other than the
          Python and SpiderMonkey C APIs to contribute, and

      (B) it means one less dependency, which makes the build process
          easier.

    The module also doesn't use ctypes because using the SpiderMonkey
    C API requires fairly complex preprocessor macros defined in the
    engine's header files.

    Finally, Atul has never really made a straight Python CAPI module
    before, so he wanted to give it a try.

[1] https://wiki.mozilla.org/ServerJS

Building and Testing
--------------------

You can either build SpiderMonkey off the mozilla-central HG
repository, or off a mirror I made of its SpiderMonkey directory. The
latter can be obtained here:

  http://hg.toolness.com/spidermonkey/

Just HG clone that repository and read the instructions in the README
to build SpiderMonkey.

Then come back to the root of your pymonkey repository and run:

  python manage.py build --static --objdir=PATH_TO_OBJDIR

Where PATH_TO_OBJDIR is the path to your Mozilla/SpiderMonkey build's
objdir.

Note that at the moment, the build script is only tested on OS X.

Example Code
------------

Right now the only example code that exists is in the test suite at
test_pymonkey.py.  Check it out and feel free to add more.

Challenges
----------

There's a number of challenges that need to be resolved before
pymonkey can be really usable. Here's some of them.

Garbage Collection

Python's garbage collection uses reference counting, whereas
SpiderMonkey's is mark-and-sweep. We'll likely run into situations
where there are cycles that exist between SpiderMonkey and Python
objects; this is actually quite similar to the relationship between
XPCOM and JavaScript in the Mozilla platform--XPCOM uses reference
counting too--so detecting such cycles will probably involve creating
something akin to XPCOM's cycle collector [1].

[1] https://developer.mozilla.org/en/Interfacing_with_the_XPCOM_cycle_collector