atocha: Web Forms Library



Atocha is a Python package for parsing and rendering data from web forms. It is framework-agnostic, generic, and it should be possible to use it with CGI scripts or to incorporate it in your favourite web application framework.


Just before I decided to write this software (2005-09-30), I had the following problems:

  • There was no library that could parse input from widgets and perform automatic types conversions reliably, that was both decent and simple, or that was not tied to a specific web application framework. (A few options were starting to sprout and mature around that time, such as FormEncode);
  • I was having lots of trouble in the various data paths of my handlers with type conversions, often having unicode encoding problems;
  • I felt that the problem of handling and rendering web forms were really tied closely, and that it could be solved in a generic manner.

At the time, I had written my own web application framework, and a small form library I had copied from somewhere had grown into a messy monster. So I decided to attack the problem directly and rewrite my forms handling generically, with the following goals in mind:

  1. Reuse the form definition for parsing submitted arguments as well as rendering and displaying data (leverage the knowledge stored in the form definition as much as possible);
  2. Robustness: an emphasis on strict type checking and robustness via tests;
  3. Fields automatically perform appropriate type conversion when returning the parsed value to the user; Like desktop UI toolkit widgets, fields may return all sorts of data types. Also, fields can use multiple HTML input widgets, the notion of input and its mechanism are separate.

Essentially, I wanted functionality closer to what desktop UI toolkits provide, which is often not present in web form parsing toolkits.


Ultimately, you'll have to delve into the heavily documented code to find out about all the gory details, but the simple introduction in this section will give you a taste for what the library can do for you.

Some documents:


Online Demo

You can try an online demo of a form with all the available widgets, that was implemented using simple CGI scripts. You can visit the source code from the demo web pages too.


This simple demo does not use session management, so if many people access it at the same time you may be surprised by other people's values appearing in the results.


A Mercurial repository can be found at:


The atocha-discuss mailing-list for the project can be found at

Reporting Bugs


If you find bugs, please post them on the associated SourceForge bug tracker. I share my source code in the hope that other users will provide feedback to improve stability. Contributions are also welcome.

Support and Stability

I am actively using this library to build a commercial-grade web application and will actively improve and support the library. There is a test suite that runs through the basic features of the library.

Installation and Dependencies


The Atocha library has evolved a lot from my original use of the file in the draco framework written by Geert Jansen. I originally copied and modified the file quite a bit, and at some point I got really frustrated in my mess, being constantly in data type conversion hell and decided to rewrite the whole thing completely, with a particular emphasis on identifying and checking the types which flow throughout the life of a request.


Martin Blais <>