Package lemon.db.builder

DBBuilder - Typed SQL Abstraction Layer.

Still to do:        
        Forms Code -> pass the form object a Row class.
        (Transaction Support.) In the documentation.
            ##### Problem with default values in defaults???
            
        Driver/Interface model for implementing anydb, other drivers etc...
   
BUGS 
    - Dates don't work properly from the table(rowid).dict() method.
    - Should be able to choose to use the Lemon date classes with a function.

Developer Documentation:

    Rough guide in case I forget!!
    
    Table Class
    
    User constructs a class derived from table -> In the initialisation of the Table base class a list of column
    objects is created based on the names and types of the columns specified in the derived class. Any custom
    methods are applied to the objects by assigning the methods to currently existing methods. The column names
    are error checked
    
    Row Class
    
    The row class contains the values from one row of the table. It holds the data as a list of column values
    the same as in the table class. It has a load of overloaded methods to allow dictionary access etc.
    
    We now have:
    
    row.middleInitial           #  - The value of the column middleInitial for the row row.
    row.var.middleInitial       #  - A Query Builder object for middleInitial to create WHERE clauses.
    row.column.middleInitial    #  - The middleInitial form field, containing the column value middleInitial for
                                #    use as a form field.
                                
    row.column.middleInitial can be used in an html.form.Form setup() function exactly as if it was an html.field
    object. This means that you can easily create correctly validating html forms which makes life much much easier
    if you are wrting a web application as it means you don't have to do any work yourself! Just create your own
    middleInitial_valid() funciton in the class constructor, setting any errors and this will be used to validate
    your field.
    
    ColType Class
    
    All column type classes are dervided from ColType and have a number of different methods to be overloaded in
    the creation of new column types. Each ColType object contains the data from one table field for one row as
    well as containing methods to validate and manipulate that value. The validation methods etc, are used from 
    all over the module to make sure values are correct.
    
    ColType classes are effectively a derivitive of both an html field and an imaginary db field. The class
    achieves this by having methods, identical to the html field whilst also implementing its own methods.
    
    An ideal solution would be to have one class Type that acted both as a db field, an html field and a data
    type. We cannot do things this way though because we want data types such as strings to be used and we 
    cannot add our own methods to a string. So to save having to use classes for string and int we do it this
    complicated way instead!
    
    DataType Classes
    
    These are classes used to store the data for a particular ColType field. For example Date stores information
    for DateCol classes. DataType classes should have the __cmp__() method defined for comparison and should do
    bsaic error checking for the data type in the constructor. ColType fields should only take the corresponding
    DataType object as the value of the field and the validation methods should be written with this in respect.
    The exceptions are the string and number based classes already written which take the corresponding Python
    type as the data object.
    
    Query Builder
    
    This class holds the names of all the columns. A QueryBuilder object is obtained from the Table().query. The
    class allows attribute access to columns returning a Query class for that column.
    
    Query Class
    
    This is a class with a load of overloaded operators to allow the construction of SQL queries in natural python
    syntax. Values are stored in a list, SQL is stored as the name. As the expression is built, '%s's are placed
    where the SQL values should be and the new SQL is passed as the name of the next Query object which is
    returned. In this way the query gets longer as does the attribute list. When the __str__() method is called
    the values are all error checked against their type using the ColType.checkType() method and if successful
    encoded using ColType.encodeAsQuery() and full SQL query is returned as SQL for use in the WHERE clause.
    
    Column Class
    
    This is simply a class to act like a list but be able to access ColType objects by name via an attribute
    access system so that adding them to a form looks pretty in code.
    
    

    
    #Mappings

    Foreign Key and Mapping implementations are just a matter of doing a seond query.
    Maybe map the result to a mapping object accessable as an array.
    
    Deleting an object with a foreighn key deletes them too.. so do something with them first!
    
    Implement slicing, contains for rows and mapping objects.
    

All datatypes must implment their own validation and the __str__ method to convert them to SQL.
They must also implemnt the comparison operaotrs, as must the rows column.

They should all have the .sql() method.

Constructing Objects/Data Types
-------------------------------

If the object is not an integer it is assumed that str(object) will generate the SQL together with necessary
quoting.


Still to implement:

    (Timestamp), Pickle???
    Auto generation of currentCols
    Code for unique.
    rename name() etc to sql_name()
    Simple structure for inheriting
    Re-implemnt col-override.
    
Adding a field:
    - Derive from ColType
    - Add name to currentCols
    - Add to Query.checkTypes() method for validation.
    - Add a new DateType to hold the value.
    
Warnings:
    - Uniqueness checking is done by the database. This option just sets the UNIQUE when creating
      the table so make sure your table has it specified so that it works!
      
      
QueryBuilder - Code to generate SQL for the WHERE statements.

Still To Do:
    Error check the Func arguments.
    
# XXX Remove autoincrement.. do it manually.

Note.. implemented asList() for Column class as a hack rather than writing an iterator.