Class sqltuple

    object --+            
             |            
      property --+        
                 |        
datatypes.datatype --+    
                     |    
            _container --+
                         |
                        sqltuple

This datatype represents a relationship between relations in which the child relation provides a number of values for a parent relation indexed by the parent's primary key. In the parent dbobject these values appear as a tuple.

  CREATE parent (
      id INTEGER,
      ... some more fields ...
  );

  CREATE child (
      parent_id INTEGER NOT NULL REFERENCES parent(id),
      info TEXT
  );

  class parent(dbobject):
      id = integer()
      info = sqltuple('child', text(), 'id', 'parent_id')

  result = ds.select(parent)
  p = result.next()
  p.info = ( "One", "Two", "Three", )

An sqltuple is not mutable (i.e. a tuple and not a list), so you can't set any member of the tupe as in t[3] = 'Hallo'. To append a value you must say dbobj.tpl += ( "Hallo", ). The program will do the right thing and only create as many INSERT statements as strings added. For all other operations all rows referenced by the parent's key will be DELETEd and INSERTed again.

The sqltuple dbattribute may be set to any iterable that yields values of the appropriate type. It will always return a Python tuple.

The orderby parameter allows you to specify an SQL clause that will determine the order of the child table's rows that are returned. It may be None. Orderby must be an instance of sql.orderby.

@param child_relation: sql.relation object or string, indicating
   the name of the dependent relation.
@param child_column: It's datatype (datatype object). The datatype's
   column parameter may be used as well as teh validators. Title and
   has_default will be ignored. The column name defaults to the
   container's attribute_name in the parent dbclass.
@param child_key: A string indicating the column in the child
   relation that is used in the foreign key to point to the parent.
   
The the docstrings of the actual implementations for examples,
that's going to make it clearer.

As a sidenote: This only works for a single-column reference
key from the parent class to the child class. It would be
possible implementing this for multiple column keys using an
anonymous dbclass, but it's just soooo darn complicated! So I
thought to myself that orm2 is complecated enough...