Clone this wiki locally
The pyjs repositories are hosted on Github. For read-only access to pyjs' main repository use the following:
git clone https://github.com/pyjs/pyjs.git
If you want to add contributions to the project source code see Contribute for details.
How to set up a Web development environment
Web application development can be tricky: it can come as a bit of a shock when compared to Python app development to learn that web browsers do not come with any proper debugging assistance whatsoever, by default. You will need to install and/or enable a debugger in the browsers that you use:
- For Firefox, install both Venkman and Firebug.
- For IE, install the Microsoft Script Debugger.
- For Safari, go to the settings and enable "Development".
- For Chrome, Web Developer has been reported to make your life easier. (Problems with Chrome/Chromium? See main Wiki)
- Opera has stack tracing by default.
For debug output using pyjs'
logging module is recommended (see below for details).
You should also note that the pyjs compiler has a
Lastly, it is worth reiterating that pyjs Desktop runs as pure Python: you should give serious consideration to running the application under pyjs Desktop alongside developing it for the browser. The availability of Python runtime stack traces and the simple fact that the standard Python interpreter is much better at catching certain kinds of errors than (brain-damaged) browsers has generally found to make life much much easier.
from pyjamas import logging log = logging.getConsoleLogger() # other loggers: Alert, Append, Print ... ... log.error("Hello, here is an %s error", err_name)
For a good understanding of the logging module read the Python Logging HOWTO; most of it directly applies to pyjs. Additional loggers provided by pyjs, and how you'd use them:
log = logging.getAlertLogger()shows a browser alert popup dialog for each log message.
log = logging.getAppendLogger()appends text to the end of the HTML document body. The div element holding the log messages can be accessed by its element ID ('logging_<loggername>', which defaults to 'logging_pyjs') for styling.
log = logging.getConsoleLogger()passes log messages on to the error console of Firebug/Chrome/Opera/IE8+ using the console logging functions.
log = logging.getPrintLogger()prints text to cerr, the default error output stream. This is a good choice when developing/testing with pyjs Desktop.
log = logging.getNullLogger()disable logging completely and safely.
pyjsbuild command line switch
Building User Interfaces with pyjs
To become familiar with the user interface side of pyjs, you might like to refer to the examples online and also compile and run them locally.
You might find the ui module class hierarchy useful. The
ui module contains all of the
main classes you need to create your user interface. At first, this module can be a quite confusing because of the number of classes defined. However, there is API documentation, along with a tutorial on how to create your own interactive widget.
You might also have a look at the GWT Documentation for widgets that have been ported to pyjs.
- Contributed libraries, added to the pythonpath when translating code to js
- Executables created when bootstrapping appear here
- Boilerplate files etc. for
pyjs_build's building process
- Miscellaneous helper scripts
- Documentation, tutorials, and scripts that build them
- Lots of examples with their build scripts (also used to test all is ok)
- Used for unit-testing, build it and launch it to have in-browser tests performed
- All common widgets and utilities, with platform overides when necessary
- libs tracking original gwt sources, without improvements
- libs mirroring and cross-linking gwt/ ones, to add pyjs-specific features
- Python parsing suite recoded in python
- Just ignore that for now
- Desktop runner (executes non-translated code, on several possible backends)
- Spidermonkey runner (executes js code on that js engine)
- Google V8 runner (executes js code on that js engine)
- The script through which everything starts
- Very useful to easily launch unit-tests (especially libtest) on several engines
Key points to remember:
- the "/pyjs" part is only used in translated mode, other libraries are used both for translated (browser, pyv8, pysm...) and non-translated (pyjd) modes
- each widget is split between "/library/pyjamas/ui/" and "/library/gwt/ui/" trees, to differenciate legacy and pyjs-added features
- for testing, "/test.py" and compiled "/examples/libtest" are your best allies