The Voidspace Python Guestbook

Installation and Use Guide

Author: Michael Foord
Contact: fuzzyman AT voidspace DOT org DOT uk
Version: The Voidspace Python Guestbook v1.4.3
Doc Revision:7, 2005/05/23
Original Date:2004/12/04
License:BSD License
Home Page:Guestbook Homepage
Sourceforge:Sourceforge Project
Support and Bug Reports:
 Pythonutils Mailing List


1   What Is the Voidspace Python Guestbook ?

Guestbook is a Python script that allows you to add a 'guestbook' facility to your website. It is fully customisable using HTML templates - so the guestbook can be fully integrated with your website. The entries are saved in a plain text file, for easy editing, and there is a naughty word filter as well. Have a look at the Default Guestbook Example, and the Voidspace Guestbook which makes use of the HTML templates to integrate with Voidspace.

Almost every aspect of the appearance can be edited using the templates. Various user settings can also be configured. Full instructions are contained in the template file.

It can email you when an entry is made, and features smilies, anti-spam protection, javascript form validation, and allows a limited set of html in comments. It is regularly improved and updated.

Anyway, enough advertising - I hope you find it useful.


2   Downloading

There is only one file for this distribution :

If you have any questions, or need help installing the guestbook, feel free to contact me. This is best done at the Pythonutils Mailing List.

3   Installing the Guestbook

Guestbook is a straightforward CGI script, so installing it isn't difficult. Even if you're not a Python programmer, the templates can easily be customised with any text editor [1]. It can then be nicely integrated into any website that supports Python CGIs. It's even possible to host it on a different site, and have it appear to be fully integrated with your main site. (Useful if your current site doesn't host Python and you don't want to move the whole site). The most important thing, is that the server you use must have Python [2] installed. Python comes with most Linux installations, but is still less common on Microsoft servers.

3.1   The Guestbook Files

When you get the, it will contain the following files and directories :

  • guestbook.html - this helpfile
  • guestbook.txt - the ReST source to this helpfile
  • blue_box.css - the css file for this html page
  • - the main guestbook Python script (the CGI)
  • - the html templates
  • guestentries.txt - a simple example guestbook file
  • BSD-LICENSE.txt - the license that this is released under
  • images directory - the alert image, and images for this file
  • smilies directory - a set of smilies with the relevant pak file
  • modules directory - the necessary python modules for smilies and handling html
  • scripts directory - the javascript file for form validation

3.2   Step By Step

Since version 1.4.0 there is a bit more to do if you want to use all the features of the guestbook. You'll need to install the python files correctly, put the smilies in the right place, put the javascript and alert image in the right place, and finally - edit the templates.

3.2.1   Upload the Python Files

You'll need to upload,, and the modules directory.

You'll need to do the usual things for CGI - like make sure that the first line of is set correctly for the server. It will usually need to be something like '#!/usr/bin/python' or '#!/usr/bin env python'. You will also have to change (chmod) the permissions of to '755' (executable by everyone). The files will probably need to be located in the 'cgi-bin' directory, or a subdirectory. The last thing is to make sure that the script is uploaded to your server in 'ascii' mode, rather than binary - this ensures that the line endings are properly converted when uploading. A desktop based FTP client like Filezilla is a good way to do this - just make sure it is set to 'ascii' mode for '.py' files.

3.2.2   Upload the Smilies

The Voidspace guestbook now supports smilies - hurrah. It comes with a standard set, but you can use alternative sets as well.

You need to upload the smiley images. In the distribution they come in a directory called smilies. You will need to tell guestbook where to find this directory - this is the smiley_url and smiley_path values in the templates. If you put the guestbook in your cgi-bin directory and the smilies directory in the root web directory, you might not need to edit these values.

Smiley support is done using a modified version of by Mark Andrews. It supports smiley sets with a .pak file, as used by phpbb. You can find alternative sets of smilies at the stylesdb website.

If you don't want to use smilies, delete from the modules directory.

Smilies are entered as text. They can also be inserted from the images using a piece of javascript. They are then replaced with the image when the entry is displayed. A smiley must be surrounded by spaces to be displayed. Sometimes a smiley gets inserted next to the edge of the text box and a line break gets inserted. This means an occasional smiley won't get converted. Hey, there are worse things in life.

3.2.3   The Scripts Directory

The scripts directory only has one file in it - guestform.js. This is the javascript file used to validate the form entry. If you use it then the user will be warned before submitting an entry with required fields missing, or an apparently invalid homepage url or email address. The guestbook will still work without using the javascript. This means that people who access your guestbook with javascript disabled can still make entries.

The advantage of using the script is that it will reduce rubbish in your guestbook (obviously invalid URLs and email addresses). Additionally, if a user omits a required field they don't lose their entry.

The path to script is set in pageheader in the template. It doesn't matter where you put the script - so long as the path is correct. By default it is expected in a directory called scripts in the root directory. If you don't want to use the javascript, delete the part of pageheader that refers to it. You may also want to delete onsubmit="return checkform(this);" in entrytable.

guestform.js does expect another file to be in a specified place though. See the section below, about the images directory.

3.2.4   The Images Directory

The images directory contains a few images for this file. It also contains a single file that you will need to put on your server. This is alert.gif which is used by guestform.js. Unfortunately the path to this is set in the javascript file. It expects the image to be at '/images/alert.gif'. If you put it anywhere else you'll need to change this path in guestform.js [3].

3.2.5   Summary

That might sound complicated. But, for a default install you can just do the following :

  • Upload the python files into the cgi-bin directory [4]
  • Upload the images, smilies, and scripts directories into the root web directory.

4   Customising Guestbook - Using the HTML Templates

Guestbook uses HTML templates to generate it's output. This means it can be easily incorporated into any website. All of the templates are contained in a file called, which can be edited with any text editor. It has several variables containing the HTML, in sections, which are put together and output by the script. You choose the look of the pages produced by guestbook, by inserting your own HTML into these variables (everything between the triple-quotations). There is a note by each one explaining where each one is used, and also explaining the layout of the page. There are also a few variables relating to the email feature. See the next section on how to set these, or to switch it off.

If you have never used HTML forms before, then it's probably best to leave alone the form that collects the information from the user. This is the variable called entrytable in Some of the values in this section are crucial to guestbook. If you do edit it, you mustn't use the '%' character anywhere in it. If this causes you problems, let me know and I can do a fix.

In actual fact you can create quite a nice guestbook just by editing the pageheader and the pagefooter entries. (Which is basically all I've done in my example two - which is the guestbook for my main website, Voidspace). You might also want to just edit the name displayed in pageheader2, and the greeting in blankout, but most of the rest of the settings are fine as defaults.

Don't forget to keep my credits intact somewhere on the page please. This is the section :

<strong>The Voidspace <a href="" target="_blank">Guestbook</a></strong> 
is written and maintained by <em><a href="" target="_blank">Fuzzyman</a></em>, 
using <strong><a href="" target="_blank">Python</a></strong>.<br>

When displayed it looks like this :

The Voidspace Guestbook is written and maintained by Fuzzyman, using Python.

Inside the zip file is an example 'guestentries.txt' file. If you upload the example one you'll probably need to set the permissions (chmod again) to '666' so that it can be written by anyone - because the script needs to write to it. If you don't upload the example one then the script ought to create it's own, which should be fine. The example one shows you the file format the entries are saved in. You can edit the actual entries in your guestbook, by editing this file (but beware if you mess it up then it's likely to crash !). It just saves the different parts of each entry (name, email, location, homepage, date and comments) separated by '||', all on one line. If a value isn't present (e.g. the user didn't specify a location) then you will see '||||'. You can delete a whole entry by deleting the whole line.

The last two lines in the file are used as a counter of how many times your website has been viewed, and a number that represents the first time it was looked at.


Because we send the guestbook web page as UTF8, your template must be saved as a UTF8 file. Most modern text editors, including notepad, can do this - but they probably have to be told to ! On windows the default encoding for non-ASCII characters is likely to be cp1252, and things might not appear how you expect.

5   The Email Feature

Guestbook can be setup to email you whenever anyone makes an entry. This needs either a working 'smtp library' on your server (which will be most servers), or access to the sendmail progam (which means Lunix type platforms only).

If you want to use sendmail then you will need to specify the path to the sendmail program, using the SENDMAIL value in the template. A likely default value comes in the standard template. If you want to use the smtp server (host 'localhost', no username or password) then change SENDMAIL to ''.

The email feature comes with the email variable set to ''. In order to switch it on you will need to put your email address into this value.

The other values (email_subject etc) make up the email message - it's probably best not to mess with these.

6   Unicode and Character Sets

As of version 1.2.0 the main guestbook page is sent as UTF-8. This is the unicode encoding that web browsers speak. It also means that the form submission should be sent back encoded as UTF-8. This means that guestbook ought to cope with input from almost any character set. Haha.. I'm sure that statement will be tested though. Anyway, if you have any problems with it, please let me know. Sending in UTF-8 is enforced by sending the http header Content-type: text/html; charset=UTF-8. This means that if you want to include non-ascii characters in your template, you should use the UTF-8 encoding and not latin-1 (or anything else). By default '' is now UTF-8 encoded, with the appropriate declaration at the start of the file.

As of version 1.3.0 the form includes a '_charset_' parameter that detects if the user has changed the character set. If they have then the submission is converted to UTF8. This is slightly more flexible than before.

7   Anti-Spam Features

Unfortunately spam is a fact of life. This includes guestbook spam. The Voidspace Guestbook includes a few features to help reduce this. The most obvious one is that the geustbook files are saved as plain text. This means you can edit them with any standard text editor and delete offending entries !

The next method is using the naughty word list in the template file. As well as containing naughty words it also contains some words used by a lot of spammers - these include the obvious like 'viagra' and 'cialis'. If you are regularly bothered by the same sort of spam you can add extra words here to block entries.

As of version 1.3.0 some new features have been added. You'll need to update your template file to take advantage of them - see the values in the 1.3.0 template file. The first is that links displayed (the homepage entry) have the rel="nofollow" tag. This means that search engines don't follow the link and they are no use to spammers. (Spammers make entries in guestbooks to increase the number of pages linking to their sites and increase their search engine rankings). This change is in the g_homepage value in the template.

Also, in version 1.3.0 - email addresses are displayed by the browser using javascript. This means the email address isn't in the page source in a plain format. This ought to make it harder for spammers to gather email addresses from your guestbook. This change is in the g_email value in the template.

The entry table now has a message telling your viewers about these two facts.

The final feature is new in version 1.4.0. We now make a basic check that the POST has been made by a human, rather than an automated POST. First, the IP address of the GET must match the IP of the POST. Second, the time of the POST must be less than 15 minutes after GET - and more than 5 seconds.

8   HTML in Entries

Supplied in the modules directory is a file called by Connelly Barnes. This allows us to process HTML based on what tags are used. All this is a long winded way of saying that some html is allowed in entries.

Exactly what html tags we allow is set in the allowed_tags list. Any other tags, and related text, will be removed. This means that some styles like bold and italics, etc, can be used by people who know html. I haven't allowed <pre>, because it breaks the layout of my pages.

If you delete the file from the modules directory, then the whole entry will be treated as text (any html will show up as text).

If the user enters badly formed HTML then we attempt to sort this - should close any unclosed tags, and we don't allow any tags that can affect layout. If you encounter any problems with this let me know.

9   datestring and language

Earlier on I proudly proclaimed that all the values in the templates could easily be edited by non programmers. That's not quite true any more I'm afraid. There are a few values with slightly techie meanings.

The first of these is called datestring. It controls how guestbook displays the dates of entries [5]. This string is actually used by a function called strftime in the Python time module. If you check the documentation on the time module it gives instructions on how to edit this.

The next techie value is one called language. This enables you to change a setting called the locale on the computer that guestbook runs on. In practical terms, it affects the way that guestbook displays the dates of entries made [6]. See the documentation on the locale module for details of what it does. Unfortunately the way to configure it varies across different platforms. For example, to change guestbook to using german dates on a windows server you need to set language to 'german'. On Linux you probably need to set it to 'de_DE'. It may require some experimentation to get it to work for you.

Their is another geeky value called SENDMAIL. This is documented in The Email Feature section.

10   TODO

Features I could add :

10.1   Version 2.0 ?

It would be possible to move all the templates into a config file, the sort read by ConfigObj. This would naturally mesh with logintools and an admin interface.

This would make it easier to add an admin interface for editing/deleting entries and also editing the templates. Installing guestbook would also mean installing logintools and ConfigObj though [7]. ConfigObj would also need to support multiline values (which it currently does through the obscure '&mjf-lf;' escaping). This is one of the targets of ConfigObj 4.

It would even be feasible for a single install of guestbook to support multiple different guestbooks. All of this would make it an order of magnitude harder to install in the first place of course.

11   BUGS ?

Please remember it's possible a few bugs may be uncovered in guestbook - but I'll fix them as they arrive. If you want to be kept up to date with bugfixes and improvements then join the Pythonutils Mailing List.

12   Changelog

2005/05/23          Version 1.4.3
Added a setting to change the locale (language) in
Added a setting to change the date formatting in
    uses strftime format - 'datestring'
Time of entries now saved as numbers
    (so changes to 'datestring' can affect all entries saved as numbers)
Removed strftime from pageheader2 - uses **time** and **version** 
A better ObscenityCheck function
    Thanks to Marius Soutier for inspiring the above changes.
Changed position of entrytable when displaying at the top.
Bugfix - cgi escaping name etc - even if we are using htmldata for comments.
Moved other logic out of template - now use **htmltags**
Moved versionstring out of templates.
Remove UTF8 BOM from the guestentries.txt file if necessary.

2005/05/04          Version 1.4.2
Fixed Python 2.3 incompatibility in CheckStamp - oops.
Fixed Python 2.2 incompatibility in ObscenityCheck (yes I'm testing now)
Fixed second image location in guestform.js

2005/04/28          Version 1.4.1
Fixed bug in handling of self closing tags with htmldata.
Upgraded to htmldata 1.0.7
Smileys by the edge of the textarea get displayed now.
Optimised the ObscenityCheck function.
Javascript improved in
Added checks for automated entries - comparing IP and time of GET and POST
Added the 'counter' - displays how many times the guestbook has been displayed.

2005/04/23          Version 1.4.0
Support for smilies - needs and
We now replace '  ' with '&nbsp;&nbsp;' (whitespace preserevd in entries)
' wrap="hard"' added to textarea.
Use the htmldata module to allow certain html tags.
Better use of CSS.
Fixed bug causing page number not to be displayed.
Added javascript form validation.

2005/04/06          Version 1.3.0
Lots of restyling in the HTML templates - not *quite* so horrible now.
We write new entries at the start of the file rather than the end (undoes a bug introduced in 1.2.0)
Max of two URLs in an entry.
A few extra words added to the banned list. (Still trying to combat guestbook span)
New value 'BREAKVAL' added to templates (so we can use the XHTML <br /> if needed)
The '_charset_' field added to the form and value checked (in case page encoding changed by guests browser)
Now use rel="nofollow" in links to foil spammers
Email addresses shown using javascript in an attempt to foil address harvesters.
Obviously invalid email addresses and urls are removed. (very basic) 

2004/12/04          Version 1.2.0
You can now use sendmail instead of smtplib as an option (my current host will only allow sendmail).
License change (again!) - now the BSD license, which is OSI accepted.
Changed to use the UTF-8 encoding. We ought to be able to accept 'foreign' entries now.
Less danger of trashing the guestbook file (append instead of write is used).
Updated the docs (using reST) and the templates.

2004/10/09          Version 1.1.2
Added the environment information back into emails sent.

20-09-04            Version 1.1.1
Email function is now cross platform, not just for Linux servers. (Uses smtplib rather than sendmail).
Attempted to fix a problem with carriage returns - odd.
Changed license text.
Various minor tinkerings..
Removed the need to have the script name in the template.
Added the word poker to the list of banned words (to stop certain adverts).
Added from_email to the templates - which means this version of isn't compatible with an old template file.
(and added a work around so people won't notice...)

01-07-04            Version 1.1.0
Added the 'e-mail administrator' function. 

24-04-04            Version 1.0.1
Corrected bug in displaying the links for multiple page books.

02-10-04            Version 1.0.0
Working guestbook.

13   Credits

The Voidspace Guestbook, is written by Michael Foord [8]. is written by Mark Andrews. It is licensed under the same license as the Guestbook License [9]. (needed by is written by Jason Orendorff. He has placed it in the public domain. is written by Connelly Barnes, he has placed it in the public domain.

guestform.js is adapted from the unobtrusive javascript articles by Christian Heilmann. It is licensed under a Creative Commons License.

The smilies come from a gentleman called Spider.

14   Guestbook License

These files are licensed under the BSD license. This is a very unrestrictive license - but it comes with the usual disclaimer. This is free software - test it, break it, just don't blame me if it eats your data ! (If it does though, let me know and I'll (try to) fix that it so it doesn't happen to anyone else :-)

Copyright (c) 2003-2005, Michael Foord
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are

    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.

    * Redistributions in binary form must reproduce the above
      copyright notice, this list of conditions and the following
      disclaimer in the documentation and/or other materials provided
      with the distribution.

    * Neither the name of Michael Foord nor the name of Voidspace 
      may be used to endorse or promote products derived from this
      software without specific prior written permission.


You should also be able to find a copy of this license at : BSD License

If you let me know of any places where you use my scripts, I can include a link back to you as an examples. If you use this program, please help Sponsor Voidspace, to help cover the costs of hosting Voidspace and all the Pythonutils projects. Even $1 or $2 is helpful !

[1]The two exceptions to this rule are the 'datestring' value for formatting the way dates appear, and the 'language' setting for changign the native language of the guestbook, otherwise known as the 'locale'. The template file has details.

[2]It is tested, and ought to work with Python 2.2 or more recent. If you have any problems please report them and I'll fix them.
[3]This path occurs twice in guestform.js - both very close to each other.
[4]Which we assume is a subdirectory of the root web directory. If it isn't you'll have to alter the smiley_path value.
[5]Or more properly formats the dates of entries.
[6]This only applies to entries made after version 1.4.3 (or later) is installed. Entries made prior to this will have been saved with the date as text.
[7]Both logintools and ConfigObj are pure python modules - so they could just be bundled with guestbook.
[8]Also known as Fuzzyman
[9]Known as the 'BSD License'
Support This Project Logo

Certified Open Source