Current Release: 0.8.1~+alpha1
---------------

This is the 0.8.1~+alpha1 release of Pyjamas.  Pyjamas comprises several
projects, one of which is a stand-alone python-to-javascript compiler; other
projects include a Graphical Widget Toolkit, such that pyjamas applications
can run either in web browsers as pure javascript (with no plugins required)
or stand-alone on the desktop (as a competitor to PyGTK2 and PyQT4).

Features and enhancements of the stand-alone 0.8 series javascript
compiler and associated modules include:

* more behaviour closer to python, thanks to several contributions including
  from Daniel Kluev

* improvements and additions to the standard modules, including renaming
  JSONParser to json and changing its interface to match standard python,
  and a new python-compliant logging module.

In the User-Interface suite, which is separate from the Pyjamas
stand-alone python-to-javascript compiler, the features and
enhancements include:

* a new platform override system that puts source files for both
  browsers and desktop pyjamas applications in the same directory
  as the module being overridden

* Gradient and Text functions for the 2D Canvas module

* Fix to long-standing issue with Focus.py

* Addition of Video and Audio Widgets that use HTML5 or Windows Media
  as appropriate (also operating correctly under pyjd including MSHTML).

* Finally a port of RichTextArea (HTML WYSIWYG editor) and the addition
  of a demo (but fully functional) RichTextToolBar.

* A port of gwt-selection which allows nodes to be properly identified,
  modified etc.  This is essential to augment the RichTextToolBar in order
  to add styles beyond those supported natively by the Browser Engine
  itself (HTML "edit mode").

Also, several JSONRPC server helper routines have been contributed and
added, including for cherrypy, cgi-bin and mongrel2.  A full JSONRPC
service with each of these types of web service systems can be added
usually in about 5 lines of code.

It has also been confirmed that Pyjamas and Pyjamas Desktop run successfully
under Wine 1.4 when IE8 is installed.  This may make it easier for developers
to test deployment of applications across a wider range of browsers and
desktops when working from a GNU/Linux development base.

Pyjamas
-------

Pyjamas is a port of Google Web Toolkit to Python, and thus enables
the development of Rich Media AJAX applications in Python, with no
need for special browser plugins.  Pyjamas contains a stand-alone
python-to-javascript compiler, and also a Widget Set API that looks
very similar to Desktop Widget Set APIs (such as PyQT4 or PyGTK2).

Pyjamas also contains a Desktop Widget Set version, running as pure
python, with four useable Desktop ports available.  Using web browser
technology startlingly provides an alternative to traditional
Widget sets, such as PyQT4 and PyGTK2, with the advantage of having
full support for HTML, CSS, Plugins and other web-related features
already built-in.  For the windows port, this can save users and
developers around 30mb of downloads, as MSHTML is preinstalled on
the Windows Operating System, as part of IE.

For more information, see:

    http://pyjs.org
    http://pyjs.org/FAQ.html
    http://pyjs.org/features.html

Known bugs: http://code.google.com/p/pyjamas/issues

Pyjamas-Desktop
---------------

Pyjamas runs your python application in a Web Browser (as javascript).
Pyjamas-Desktop runs exactly the same python application on the
Desktop (as pure python).

    http://pyjd.org

Release 0.6 of Pyjamas incorporated Pyjamas-Desktop directly into
the Pyjamas Distribution.  To use Pyjamas-Desktop there are three choices,
with more planned [MacOSX PyObjC; KDE's PyKHTML].

All ports of Pyjamas-Desktop will require a JSON library to be
installed: as there are plenty already, it is counter-productive
to write yet another one.  simplejson is recommended if the version of
python is 2.5 or less.  Python 2.6 and above come with a json library
installed by default.

1) - XULRunner

install hulahop and python-xpcom.  hulahop, from OLPC SugarLabs,
is distributed with both Debian and Ubuntu; python-xpcom is part
of XULRunner and is also distributed with both Debian and Ubuntu.
Other users should investigate the installation instructions for
python-xpcom and hulahop for the operating system of their choice
on the appropriate web sites.

Sadly, modifications made by the Mozilla team to the xulrunner API
have not propagated through to python-xpcom due to lack of attention
and support by the Mozilla team.  Older versions of XULRunner must be
used: versions 1.9.0 or 1.9.1 are known to be suitable, as is version
9.0.  Versions 10 and above are known to segfault.  The Mozilla
Foundation is NOT paying attention to the stability of xulrunner for
embedded purposes: many applications (not just pyjamas-desktop) are
now being left without working, stable code.

2) - PyWebKitGtk

There are two versions of PyWebKitGTK: please do not use the older
version which has been "taken over" by the Webkit team: the Webkit
team have decided that full support of and direct-equivalent
interoperability with the full W3C HTML specifications is not important.

The version of pywebkitgtk at http://www.gnu.org/software/pythonwebkit
provides full and direct python-equivalent interoperability for all functions
for which access through javascript has been provided: thus, Pyjamas
Desktop will function correctly.

PyWebkitGtk must be explicitly enabled.  create a $HOME/.pyjd/pyjdrc file
containing the following two lines:

[gui]
engine=pywebkitgtk

3) - PyWebkitDFB

This is an experimental but minimally functional engine that is extremely
quick to start up.  The build dependencies are also drastically smaller than
any of the other web browser engines (which indirectly contributes to the
fast startup time).

HTML5 is fully supported, with the exception of Video and Canvas; also
missing at present is support for Frames.  Despite the present limitations,
PyWebkitDFB is highly suited to embedded systems, as well as being useable
as an excellent and ultra-quick general-purpose web browser engine.

PyWebkitDFB must be explicitly enabled.  create a $HOME/.pyjd/pyjdrc file
containing the following two lines:

[gui]
engine=pywebkitdfb

4) - MSHTML

For Windows users, all that's required, other than installing python
and Internet Explorer, is one further tiny package: Win32 "comtypes".

Win32 "comtypes" can be downloaded here:
* http://sourceforge.net/projects/comtypes/

Unlike the other ports, which can comprise a whopping great bundle
of anything up to 30mb in size, the MSHTML port literally requires
nothing more than comtypes, thanks to the far-sighted design of the
MSHTML Trident Engine and its extensive COM interface.

5) - PyQt4

Kindly contributed by Thomas Henning, the PyQT4 port requires a current
PyQt-snapshot with Qt 4.6 (which includes QWebElement, a DOM-like API for
WebKit).

The PyQt4 engine is highly experimental, and requires a configuration file
to explicitly enable it.  create a $HOME/.pyjd/pyjdrc file containing the
following two lines:

[gui]
engine=pyqt4

Sadly, the PyQT4 port serves more as a demonstration of how never to access
web browser DOM functionality from python (ever).  The reason is simple:
to access all but about 1% of the available DOM functionality, javascript
code snippets must be created on-the-fly and executed, and all incoming and
outgoing data must be dynamically translated between python and javascript
(as Qt4 objects).

Aside from providing truly dreadful performance, this technical approach
should have you either in hysterics, throwing up or requiring counselling,
depending on your resilience and constitution.  All is not lost: if funding
is made available, the PythonWebkit project can, with very little actual
coding required, be ported to Qt4, as the GNU PythonWebkit Project has been
designed to provide python access to DOM functionality, independent of the
actual GUI display engine being used.

6) - PyKDE

The PyKDE engine has been done as a "thank you" to the KDE Team, without
whom Webkit would not exist.  Sadly, though, for technical reasons, the PyKDE
engine requires that the entire KHTML Part be compiled with c++ "rtti" enabled,
and the majority of GNU/Linux Distributions explicitly disable RTTI due to
it having an impact on performance.

If this is ever fixed, then out of sheer nostalgia and bloody-mindedness, the
PyKDE engine will have continued support, even though the KHTML engine is only
DOM TR2 compliant (at present).