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:

• Overview and Tutorial
• Fields Reference List
• Design Notes
• Data Flow and Data Paths
• Developer's Guide
• FAQ

• Generic library that is possible to reused in many frameworks and applications. It is not tied to any storage model or domain model, this library provides the data, and you must then store the data yourself. This makes sense, as user-interfaces may change but the underlying data model remain the same;
• Extensible: it is easy to create and add new field types without having to modify the framework. It is also possible to create renderers for your favourite output library (e.g. Stan)
• Fields may render to multiple input widgets and are consolidated in a single value automatically;
• Internationalization (I18n) of all messages is supported (all messages generated by the library are grouped in a s single place and can be easily customized);
• Supports hidden, disabled, and read-only widgets that can be used for implementing multiple-page forms;
• Supports per-field errors, to be rendered next to the erroneous widgets;
• Supports a UI message and status for the re-rendering a form with errors;
• Could easily be extended to support widgets with JavaScript/AJAX code.

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.

• Online Demo -- Try It Now!

A Mercurial repository can be found at:

http://github.com/blais/atocha

The atocha-discuss mailing-list for the project can be found at http://lists.sourceforge.net/lists/listinfo/atocha-discuss

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.

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.

• Another similar project is the FormEncode library (author: Ian Bicking): http://formencode.org/.

• Python >=2.3

Copyright (C) 2005 Martin Blais. This code is distributed under the GNU General Public License.

The Atocha library has evolved a lot from my original use of the form.py 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 <blais@furius.ca>