Webware for Python
Here we describe best practices for developing a web application using Webware.
The first task in developing an application is to set up the file structure in which you will be working.
It is possible to put your application in a subdirectory under WebKit/ and change WebKit/Configs/Application.config to add another context. But do not do this. Your application will be entwined with the Webware installation, making it difficult to upgrade Webware, and difficult to identify your own files from Webware files.
Instead you should use the script bin/MakeAppWorkDir.py. You should run it like:
$ python Webware/bin/MakeAppWorkDir -c Context -l Lib --cvsignore WorkDir
This will create a directory WorkDir that will contain a directory structure for your application. The options are:
You can see all available options if you run Webware/bin/MakeAppWorkDir.py without any parameters.
When you do this, you'll see this directory structure:
AppServer* Configs/ error404.html Launch.py Logs/ WebKit.cgi Cache/ Context/ ErrorMsgs/ Lib/ Sessions/ webkit*
Here's what the files and directories are for:
A version control system is a useful tool for managing your application. Popular Open Source version control systems are are the Concurrent Versions System (CVS) and, increasingly, Subversion (SVN). I recommend using SVN because it has a few advantages over CVS. For instance, it tracks both files and directories and handles copy, rename, and delete operations on files well. These systems handle versioning, but they also make it possible for other people to see snapshots of your progress, for multiple developers to collaborate and work on an application simultaneously, and they create a sort of implicit file share for your project. Even if you are the only developer on an application, a version control system can be very helpful.
The working directory is a good place to start for creating a versioned project. Assuming you've set up CVS, and set CVSROOT to point to your repository, you can get started by importing your project into the repository simply by running:
$ cd WorkDir $ cvs import -m 'initial import' MyWebwareProject username start
Replace MyWebwareProject with the name of your project and username with your own user name. You should use the option --cvsignore when running MakeAppWorkDir.py if you plan to do this. If you do, then .cvsignore files will be added to each directory. These tell CVS to ignore files with certain extensions (such as .pyc files), and all the files in certain directories (Cache, ErrorMsgs, Logs, and Sessions). You shouldn't otherwise notice these files, even if you aren't using CVS.
The command to import your project into a SVN repository is very similar:
$ cd WorkDir $ svn import -m 'initial import' https://myserver/myrepos/MyWebWareProject
Replace https://myserver/myrepos/ with the URL of your SVN repository. The .cvsignore files will not be used in this case. Instead, you have to set the svn:ignore property on the respective directory. You can still use the .cvsignore files to generate the necessary svn propset commands:
$ find . -name .cvsignore | while read f; \ > do echo svn propset svn:ignore -F $f $(dirname $f); done
After importing WorkDir to the repository, note that it is not automatically under version control. To start working, you first need to explicitely check it out from the repository using cvs checkout or svn checkout.
If you are using a version control system or if you are otherwise distributing your application code, you may find that it is difficult to manage the differences between accounts. For instance, in different accounts on different machines Webware may be installed in different locations. You may have the actual directory in a different location as well -- it may be in ~/webware/WorkDir for your active development, but /var/webware/WorkDir for the production version. And if there are multiple development copies on the same machine, you have to be sure they each use different adapter ports.
To solve these problems I recommend creating a shell script to handle startup. I generally call this script start, and it looks something like this:
#!/bin/sh # lothlorien.colorstudy.com is my development machine if [ `hostname` = lothlorien.colorstudy.com ] ; then WORKING=$HOME/prog/webware/WorkingDir WEBWARE=$HOME/prog/webware/Webware OPS="AppServer.AutoReload=1" fi # this is my production environment if [ `hostname` = color.colorstudy.com && `whoami` = webware ] ; then WORKING=/www/WorkingDir WEBWARE=/www/Webware OPS="" fi if [ "$WORKING" = "" ] ; then echo I do not recognize this environment exit 1 fi cd $WORKING ./AppServer --work-dir=$WORKING --webware-dir=$WEBWARE $OPS $*
You can add this to your project in the repository, and the script should automatically detect what environment it is being used in. You can use options to change configuration parameters, like setting some parameters depending on whether the environment is a development or production environment.
Some options that you may be particularly interested in:
For more settings, see the Configuration document.
Once you've got the basic files and directories in place, you're ready to go in and write some code. Don't let this document get in the way of developing the application how you choose, but here are some common patterns that have proven useful for Webware applications.
Subclass a SitePage from WebKit.Page for your application. This subclass will change some methods and add some new methods. It serves as the basis and as a template for all the pages that follow.
Some code you may wish to include in your SitePage:
I also typically add other functions to the SitePage module, and then do from Lib.SitePage import * in each servlet -- this might include functions like htmlEncode, or some other select functions that I use constantly in web applications. Whether you want to use functions or methods is up to you -- in many cases methods can be more easily extended or customized later, but sometimes method use can become excessive and create unnecessary dependences in your code.
A basic framework for your SitePage might be:
from WebKit.Page import Page class SitePage(Page): def respond(self, trans): if self.securePage(): if not self.session().value('username', False): self.respondLogIn() return def securePage(self): """Override this method in your servlets to return True if the page should only be accessible to logged-in users -- by default pages are publically viewable""" return False def respondLogin(self): # Here we should deal with logging in... pass
Obviously there are a lot of details to add in on your own which are specific to your application and the security and user model you are using.