.. Pydermonkey documentation master file, created by
   sphinx-quickstart on Mon Jul  6 17:20:31 2009.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

=========================
Pydermonkey Documentation
=========================

Pydermonkey is a Python C extension module to expose the `Mozilla
SpiderMonkey <https://developer.mozilla.org/en/SpiderMonkey>`_ engine
to Python.

.. toctree::
   :maxdepth: 2

   pydermonkey

Rationale and Goals
===================

* Python and JS are fairly complementary languages. Python provides
  tremendous developer productivity via its dynamic language features,
  its vibrant ecosystem of third-party client-side code, and its ease
  of readability. JavaScript, on the other hand, is widely known by a
  vast number of casual programmers due to its availability in web
  browsers; it was also envisioned from its conception to be executed
  as untrusted code, which gives it a lot of security characteristics
  that Python has always lacked.

* There's an increasing need for being able to run JS on the server
  side--particularly untrusted JS. For instance, being able to
  duplicate business logic on the server and client (i.e., browser)
  would be very useful. Standards-based solutions like `ServerJS
  <https://wiki.mozilla.org/ServerJS>`_ are currently paving the way
  in this field. There's Java-based solutions like Rhino out there,
  but nothing really mature is available for the Python
  world. Ideally, Pydermonkey should enable a Python programmer to create
  a custom sandboxed environment for executing JS code without needing
  to write any C.

* Pydermonkey 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 documentation and playing around with the code.

* Pydermonkey 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 C API: no SWIG, Pyrex, or other
  intermediaries. The obvious disadvantage here is that it means more
  C code, but the advantages are that
    
  1. contributors don't need to learn anything other than the
     Python and SpiderMonkey C APIs to contribute, and

  2. 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.

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

The pre-built binary of pydermonkey has no prerequisites, aside from
an installation of Python 2.5 or later.

If you need to build pydermonkey, you'll need a standard C/C++
toolchain for your platform.  Windows developers may additionally need
to obtain the `MozillaBuild
<https://developer.mozilla.org/en/Windows_Build_Prerequisites#MozillaBuild>`_
package and start a command prompt for building before following any
of the build steps.

Pydermonkey can be installed via setuptools or directly from the HG
repository.

The Easy Way
------------

Just run::

  easy_install pydermonkey

This will download the latest version of pydermonkey, obtaining a
pre-compiled binary if possible.  If there is no pre-compiled binary
for your platform, the source distribution will be downloaded and
compiled.

Via Mercurial
-------------

First, clone the HG repository::

  hg clone https://pydermonkey.googlecode.com/hg/ pydermonkey

Then, from the root of your pydermonkey repository, run::

  python setup.py build test

This will fetch and compile SpiderMonkey, build the C extension, and
run its test suite to ensure that everything works properly.

Then run::

  sudo python setup.py install

Note that if you're on Windows, you won't need the ``sudo`` bit.

Challenges
==========

There's a number of challenges that need to be resolved before
pydermonkey 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. It's possible for there to be
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
<https://developer.mozilla.org/en/Interfacing_with_the_XPCOM_cycle_collector>`_.

For the time being, however, such cycles can be manually broken via
:meth:`pydermonkey.Context.clear_object_private()` on valid objects
and functions.

Indices and Tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

