[Twisted-Python] row.html howto XHTML compliance [PATCH]
G'day all, I noticed that admin/generate-domdocs failed on row.html, so I patched it to be a well-formed XHTML document (and to have lowercase tags ;) Patch below! Cheers, jml Index: doc/howto/row.html =================================================================== RCS file: /cvs/Twisted/doc/howto/row.html,v retrieving revision 1.9 diff -r1.9 row.html 1,5c1,9 < <HTML> < <HEAD> < <TITLE>Twisted Enterprise Row Objects</TITLE> < </HEAD> < <BODY> ---
<?xml version="1.0"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Twisted Enterprise Row Objects</title> </head> <body> 7c11 < <H1>Twisted Enterprise Row Objects</H1>
<h1>Twisted Enterprise Row Objects</h1> 9c13 < <P>The <CODE>twisted.enterprise.row</CODE> module is a method
<p>The <code>twisted.enterprise.row</code> module is a method 11c15 < tables. It has two components: the <CODE>RowObject</CODE> class
tables. It has two components: the <code>RowObject</code> class 13c17 < code interacts with, and the <CODE>DBReflector</CODE> which generates
code interacts with, and the <code>DBReflector</code> which generates 15c19 < deletes against the database.</P>
deletes against the database.</p> 17c21 < <P>The row module is intended for applications such as on-line
<p>The row module is intended for applications such as on-line 24c28 < to an existing python application.</P>
to an existing python application.</p> 26c30 < <P>Currently, the row module requires the use of PostgreSQL.</P>
<p>Currently, the row module requires the use of PostgreSQL.</p> 28c32 < <H2>Class Definitions</H2>
<h2>Class Definitions</h2> 30,31c34,35 < <P>To interface to relational database tables, the developer must < create a class derived from the <CODE>twisted.enterprise.row.RowObject</CODE>
<p>To interface to relational database tables, the developer must create a class derived from the <code>twisted.enterprise.row.RowObject</code> 35c39 < are:</P>
are:</p> 37,42c41,46 < <UL> < <LI>rowColumns - list of the columns in the table with the correct < case < <LI>rowKeyColumns - list of key columns in form: [(columnName, < typeName)] < <LI>rowTableName - the name of the database table
<ul> <li>rowColumns - list of the columns in the table with the correct case</li> <li>rowKeyColumns - list of key columns in form: [(columnName, typeName)]</li> <li>rowTableName - the name of the database table</li> 45c49 < <P>There are also two optional class attributes that can be specified:</P>
<p>There are also two optional class attributes that can be specified:</p> 47,48c51,52 < <UL> < <LI>rowForeignKeys - list of foreign keys to other database tables
<ul> <li>rowForeignKeys - list of foreign keys to other database tables 50,53c54,57 < autoLoad] < <LI>rowFactoryMethod - a method that creates instances of this < class < </UL>
autoLoad]</li> <li>rowFactoryMethod - a method that creates instances of this class</li> </ul> 55c59 < <P>For example:</P>
<p>For example:</p> 57c61 < <PRE>
<pre class="python"> 62c66,67 < rowFactoryMethod = [myRowFactory]</PRE>
rowFactoryMethod = [myRowFactory] </pre>
64,65c69,70 < <P>The items in the rowColumns list will become data members of < classes of this type when they are created by the DBReflector.</P> ---
<p>The items in the rowColumns list will become data members of classes of this type when they are created by the DBReflector.</p> 67c72 < <H2>Initialization</H2>
<h2>Initialization</h2> 69c74 < <P>The initialization phase builds the SQL for the database interactions.
<p>The initialization phase builds the SQL for the database interactions. 73c78 < are passed to the DBReflector when it is created.</P>
are passed to the DBReflector when it is created.</p> 75c80 < <P>An example class list for the RoomRow class we specified above:</P>
<p>An example class list for the RoomRow class we specified above:</p> 77c82 < <PRE>
<pre class="python"> 82c87,88 < reflector = row.DBReflector( dbpool, [RoomRow], runTests )</PRE>
reflector = row.DBReflector( dbpool, [RoomRow], runTests ) </pre> 84c90 < <H2>Creating Row Objects</H2>
<h2>Creating Row Objects</h2> 86,87c92,93 < <P>There are two methods of creating RowObjects - loading from < the database, and creating a new instance ready to be inserted.</P>
<p>There are two methods of creating RowObjects - loading from the database, and creating a new instance ready to be inserted.</p> 89c95 < <P>To load rows from the database and create RowObject instances
<p>To load rows from the database and create RowObject instances 94c100 < example:</P>
example:</p> 96c102 < <PRE>
<pre class="python"> 101c107,108 < refector.loadObjectsFrom("testrooms", whereClause=[("id", reflector.EQUAL, 5)]).addCallback(gotRooms)</PRE>
refector.loadObjectsFrom("testrooms", whereClause=[("id", reflector.EQUAL, 5)]).addCallback(gotRooms) </pre> 103c110 < <P>For more advanced RowObject construction, loadObjectsFrom may
<p>For more advanced RowObject construction, loadObjectsFrom may 110c117 < before exposing the data to user code. An example factory method:</P>
before exposing the data to user code. An example factory method:</p> 112c119 < <PRE>
<pre class="python"> 116c123 < return newRoom</PRE>
return newRoom</pre>
118c125 < <P>The last method of creating a row object is for new instances ---
<p>The last method of creating a row object is for new instances 122c129 < method of the DBReflector. For example:</P>
method of the DBReflector. For example:</p> 124c131 < <PRE>
<pre class="python"> 134c141,142 < reflector.insertRow(newRoom).addCallback(onInsert)</PRE>
reflector.insertRow(newRoom).addCallback(onInsert) </pre>
136c144 < <P>This will insert a new row into the database table for this ---
<p>This will insert a new row into the database table for this 141c149 < from being changed by mistake.</P>
from being changed by mistake.</p> 143d150 < <P> </P> 145c152 < <H2>Relationships Between Tables</H2>
<h2>Relationships Between Tables</h2> 147,154c154,162 < <P>Specifying a foreign key for a RowClass creates a relationship < between database tables. When <I>loadObjectsFrom</I> is called for a < table, it will automatically load all the children rows for the rows < from the specified table. The child rows will be put into a list < member variable of the rowObject instance with the name "childRows" or < if a <i>containerMethod</i> is specified for the foreign key < relationship, that method will be called on the parent row object for < each row that is being added to it as a child.</P>
<p>Specifying a foreign key for a RowClass creates a relationship between database tables. When <code class="python">loadObjectsFrom</code> is called for a table, it will automatically load all the children rows for the rows from the specified table. The child rows will be put into a list member variable of the rowObject instance with the name "childRows" or if a <i>containerMethod</i> is specified for the foreign key relationship, that method will be called on the parent row object for each row that is being added to it as a child.</p> 156c164 < <P>The <i>autoLoad</i> member of the foreign key definition is a flag
<p>The <i>autoLoad</i> member of the foreign key definition is a flag 158c166 < relationship when a parent row is loaded.
relationship when a parent row is loaded.</p> 160c168 < <H2>Duplicate Row Objects</H2>
<h2>Duplicate Row Objects</h2> 162c170 < <P>If a reflector tries to load an instance of a rowObject that
<p>If a reflector tries to load an instance of a rowObject that 166c174 < unique keys for this purpose.</P>
unique keys for this purpose.</p> 168c176 < <H2>Updating Row Objects</H2>
<h2>Updating Row Objects</h2> 170c178 < <P>RowObjects have a "dirty" member attribute that is
<p>RowObjects have a "dirty" member attribute that is 176c184 < (be sure to call the base class setDirty though!).</P>
(be sure to call the base class setDirty though!).</p> 178c186 < <P>When it is determined that a RowObject instance is dirty and
<p>When it is determined that a RowObject instance is dirty and 180c188 < to the "updateRow" method of the DBReflector. For example:</P>
to the "updateRow" method of the DBReflector. For example:</p> 182,183c190,192 < <PRE> < reflector.updateRow(room).addCallback(onUpdated)</PRE>
<pre class="python"> reflector.updateRow(room).addCallback(onUpdated)\ </pre> 185c194 < <P>For more complex behavior, the reflector can generate the SQL
<p>For more complex behavior, the reflector can generate the SQL 187c196 < for batching up multiple updates into single requests. For example:</P>
for batching up multiple updates into single requests. For example:</p> 189,190c198,200 < <PRE> < updateSQL = reflector.updateRowSQL(room)</PRE>
<pre class="python"> updateSQL = reflector.updateRowSQL(room)\ </pre> 192c202 < <H2>Deleting Row Objects</H2>
<h2>Deleting Row Objects</h2> 194c204 < <P>To delete a row from a database pass the RowObject instance
<p>To delete a row from a database pass the RowObject instance 196,197c206,207 < Deleting the python Rowobject instance does <EM>not</EM> automatically < delete the row from the database. For example:</P>
Deleting the python Rowobject instance does <em>not</em> automatically delete the row from the database. For example:</p> 199,200c209,211 < <PRE> < reflector.deleteRow(room)</PRE>
<pre class="python"> reflector.deleteRow(room) </pre> 202,203c213,214 < </BODY> < </HTML>
</body> </html>
On Wed, 2002-09-18 at 09:24, Jonathan Lange wrote:
G'day all,
I noticed that admin/generate-domdocs failed on row.html, so I patched it to be a well-formed XHTML document (and to have lowercase tags ;)
Patch below!
Was asked by spiv to resend this as a unidiff. Here it is: Index: doc/howto/row.html =================================================================== RCS file: /cvs/Twisted/doc/howto/row.html,v retrieving revision 1.9 diff -u -r1.9 row.html --- doc/howto/row.html 23 Sep 2002 00:21:53 -0000 1.9 +++ doc/howto/row.html 23 Sep 2002 11:26:03 -0000 @@ -1,127 +1,134 @@ -<HTML> -<HEAD> - <TITLE>Twisted Enterprise Row Objects</TITLE> -</HEAD> -<BODY> +<?xml version="1.0"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> + <title>Twisted Enterprise Row Objects</title> +</head> +<body> -<H1>Twisted Enterprise Row Objects</H1> +<h1>Twisted Enterprise Row Objects</h1> -<P>The <CODE>twisted.enterprise.row</CODE> module is a method +<p>The <code>twisted.enterprise.row</code> module is a method of interfacing simple python objects with rows in relational database -tables. It has two components: the <CODE>RowObject</CODE> class +tables. It has two components: the <code>RowObject</code> class which developers sub-class for each relational table that their -code interacts with, and the <CODE>DBReflector</CODE> which generates +code interacts with, and the <code>DBReflector</code> which generates and contains the SQL to perform updates, inserts, queries and -deletes against the database.</P> +deletes against the database.</p> -<P>The row module is intended for applications such as on-line +<p>The row module is intended for applications such as on-line games, and web-site that require a back-end database interface. It is not a full functioned object-relational mapper for python - it deals best with simple data types structured in ways that can be easily represented in a relational database. It is well suited to building a python interface to an existing relational database, and slightly less suited to added database persistance -to an existing python application.</P> +to an existing python application.</p> -<P>Currently, the row module requires the use of PostgreSQL.</P> +<p>Currently, the row module requires the use of PostgreSQL.</p> -<H2>Class Definitions</H2> +<h2>Class Definitions</h2> -<P>To interface to relational database tables, the developer must -create a class derived from the <CODE>twisted.enterprise.row.RowObject</CODE> +<p>To interface to relational database tables, the developer must +create a class derived from the <code>twisted.enterprise.row.RowObject</code> class for each table. These derived classes must define a number of class attributes which contains information about the database table that class corresponds to. The required class attributes -are:</P> +are:</p> -<UL> - <LI>rowColumns - list of the columns in the table with the correct - case - <LI>rowKeyColumns - list of key columns in form: [(columnName, - typeName)] - <LI>rowTableName - the name of the database table +<ul> + <li>rowColumns - list of the columns in the table with the correct + case</li> + <li>rowKeyColumns - list of key columns in form: [(columnName, + typeName)]</li> + <li>rowTableName - the name of the database table</li> </UL> -<P>There are also two optional class attributes that can be specified:</P> +<p>There are also two optional class attributes that can be specified:</p> -<UL> - <LI>rowForeignKeys - list of foreign keys to other database tables +<ul> + <li>rowForeignKeys - list of foreign keys to other database tables in the form: [(tableName, [(columnName, columnType)], containerMethodName, - autoLoad] - <LI>rowFactoryMethod - a method that creates instances of this - class -</UL> + autoLoad]</li> + <li>rowFactoryMethod - a method that creates instances of this + class</li> +</ul> -<P>For example:</P> +<p>For example:</p> -<PRE> +<pre class="python"> class RoomRow(row.RowObject): rowColumns = ["roomId","town_id","name","owner","posx","posy","width","height"] rowKeyColumns = [("id", "int4")] rowTableName = "testrooms" - rowFactoryMethod = [myRowFactory]</PRE> + rowFactoryMethod = [myRowFactory] +</pre> -<P>The items in the rowColumns list will become data members of -classes of this type when they are created by the DBReflector.</P> +<p>The items in the rowColumns list will become data members of +classes of this type when they are created by the DBReflector.</p> -<H2>Initialization</H2> +<h2>Initialization</h2> -<P>The initialization phase builds the SQL for the database interactions. +<p>The initialization phase builds the SQL for the database interactions. It uses the system catalogs of the database to do this, but requires some basic information to get started. The class attributes of the classes derived from RowClass are used for this. Those clases -are passed to the DBReflector when it is created.</P> +are passed to the DBReflector when it is created.</p> -<P>An example class list for the RoomRow class we specified above:</P> +<p>An example class list for the RoomRow class we specified above:</p> -<PRE> +<pre class="python"> def runTests(result): print "Done initializing" dbpool = adbapi.ConnectionPool("pyPgSQL.PgSQL") -reflector = row.DBReflector( dbpool, [RoomRow], runTests )</PRE> +reflector = row.DBReflector( dbpool, [RoomRow], runTests ) +</pre> -<H2>Creating Row Objects</H2> +<h2>Creating Row Objects</h2> -<P>There are two methods of creating RowObjects - loading from -the database, and creating a new instance ready to be inserted.</P> +<p>There are two methods of creating RowObjects - loading from +the database, and creating a new instance ready to be inserted.</p> -<P>To load rows from the database and create RowObject instances +<p>To load rows from the database and create RowObject instances for each of the rows, use the loadObjectsFrom method of the Reflector. This takes a tableName, an optional "user data" parameter, and an optional "where clause". The where clause may be omitted which will retrieve all the rows from the table. For -example:</P> +example:</p> -<PRE> +<pre class="python"> def gotRooms(rooms): for room in rooms: print "Got room:", room.id -refector.loadObjectsFrom("testrooms", whereClause=[("id", reflector.EQUAL, 5)]).addCallback(gotRooms)</PRE> +refector.loadObjectsFrom("testrooms", whereClause=[("id", reflector.EQUAL, 5)]).addCallback(gotRooms) +</pre> -<P>For more advanced RowObject construction, loadObjectsFrom may +<p>For more advanced RowObject construction, loadObjectsFrom may use a factoryMethod that was specified as a class attribute for the RowClass derived class. This method will be called for each of the rows with the class object, the userData parameter, and a dictionary of data from the database keyed by column name. This factory method should return a fully populated RowObject instance and may be used to do pre-processing, lookups, and data transformations -before exposing the data to user code. An example factory method:</P> +before exposing the data to user code. An example factory method:</p> -<PRE> +<pre class="python"> def testRoomFactory(roomClass, userData, kw): newRoom = roomClass(userData) newRoom.__dict__.update(kw) - return newRoom</PRE> + return newRoom</pre> -<P>The last method of creating a row object is for new instances +<p>The last method of creating a row object is for new instances that do not already exist in the database table. In this case, create a new instance and assign its primary key attributes and all of its member data attributes, then pass it to the "insertRow" -method of the DBReflector. For example:</P> +method of the DBReflector. For example:</p> -<PRE> +<pre class="python"> newRoom = RoomRow() newRoom.assignKeyAttr("roomId", 11) newRoom.town_id = 20 @@ -131,73 +138,77 @@ newRoom.posy = 100 newRoom.width = 15 newRoom.height = 20 - reflector.insertRow(newRoom).addCallback(onInsert)</PRE> + reflector.insertRow(newRoom).addCallback(onInsert) +</pre> -<P>This will insert a new row into the database table for this +<p>This will insert a new row into the database table for this new RowObject instance. Note that the "assignKeyAttr" method must be used to set primary key attributes - regular attribute assignment of a primary key attribute of a rowObject will raise an exception. This prevents the database identity of RowObject -from being changed by mistake.</P> +from being changed by mistake.</p> -<P> </P> -<H2>Relationships Between Tables</H2> +<h2>Relationships Between Tables</h2> -<P>Specifying a foreign key for a RowClass creates a relationship -between database tables. When <I>loadObjectsFrom</I> is called for a -table, it will automatically load all the children rows for the rows -from the specified table. The child rows will be put into a list -member variable of the rowObject instance with the name "childRows" or -if a <i>containerMethod</i> is specified for the foreign key -relationship, that method will be called on the parent row object for -each row that is being added to it as a child.</P> +<p>Specifying a foreign key for a RowClass creates a relationship +between database tables. When <code +class="python">loadObjectsFrom</code> is called for a table, it will +automatically load all the children rows for the rows from the specified +table. The child rows will be put into a list member variable of the +rowObject instance with the name "childRows" or if a +<i>containerMethod</i> is specified for the foreign key relationship, +that method will be called on the parent row object for each row that is +being added to it as a child.</p> -<P>The <i>autoLoad</i> member of the foreign key definition is a flag +<p>The <i>autoLoad</i> member of the foreign key definition is a flag that specifies whether child rows should be auto-loaded for that -relationship when a parent row is loaded. +relationship when a parent row is loaded.</p> -<H2>Duplicate Row Objects</H2> +<h2>Duplicate Row Objects</h2> -<P>If a reflector tries to load an instance of a rowObject that +<p>If a reflector tries to load an instance of a rowObject that is already loaded, it will return a reference to the existing rowObject rather than creating a new instance. The reflector maintains a cache of weak references to all loaded row objects by their -unique keys for this purpose.</P> +unique keys for this purpose.</p> -<H2>Updating Row Objects</H2> +<h2>Updating Row Objects</h2> -<P>RowObjects have a "dirty" member attribute that is +<p>RowObjects have a "dirty" member attribute that is set to 1 when any of the member attributes of the instance that map to database columns are changed. This dirty flag can be used to tell when RowObjects need to be updated back to the database. In addition, the "setDirty" method can be overridden to provide more complex automated handling such as dirty lists -(be sure to call the base class setDirty though!).</P> +(be sure to call the base class setDirty though!).</p> -<P>When it is determined that a RowObject instance is dirty and +<p>When it is determined that a RowObject instance is dirty and need to have its state updated into the database, pass that object -to the "updateRow" method of the DBReflector. For example:</P> +to the "updateRow" method of the DBReflector. For example:</p> -<PRE> - reflector.updateRow(room).addCallback(onUpdated)</PRE> +<pre class="python"> +reflector.updateRow(room).addCallback(onUpdated)\ +</pre> -<P>For more complex behavior, the reflector can generate the SQL +<p>For more complex behavior, the reflector can generate the SQL for the update but not perform the update. This can be useful -for batching up multiple updates into single requests. For example:</P> +for batching up multiple updates into single requests. For example:</p> -<PRE> - updateSQL = reflector.updateRowSQL(room)</PRE> +<pre class="python"> +updateSQL = reflector.updateRowSQL(room)\ +</pre> -<H2>Deleting Row Objects</H2> +<h2>Deleting Row Objects</h2> -<P>To delete a row from a database pass the RowObject instance +<p>To delete a row from a database pass the RowObject instance for that row to the DBReflector "deleteRow" method. -Deleting the python Rowobject instance does <EM>not</EM> automatically -delete the row from the database. For example:</P> +Deleting the python Rowobject instance does <em>not</em> automatically +delete the row from the database. For example:</p> -<PRE> - reflector.deleteRow(room)</PRE> +<pre class="python"> +reflector.deleteRow(room) +</pre> -</BODY> -</HTML> +</body> +</html>
participants (1)
-
Jonathan Lange