~cbehrens/nova/lp844160-build-works-with-zones

<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>Twisted Documentation: Twisted Enterprise Row Objects</title>

</head>

<h1 class="title">Twisted Enterprise Row Objects</h1>

<div class="toc"><ol><li><a href="#auto0">Class Definitions</a></li><li><a href="#auto1">Initialization</a></li><li><a href="#auto2">Creating Row Objects</a></li><li><a href="#auto3">Relationships Between Tables</a></li><li><a href="#auto4">Duplicate Row Objects</a></li><li><a href="#auto5">Updating Row Objects</a></li><li><a href="#auto6">Deleting Row Objects</a></li></ol></div>

<div class="note">Note:

Due to lack of maintenance, <code>twisted.enterprise.row</code>

and <code>twisted.enterprise.reflector</code> have been deprecated since

Twisted 8.0.

This documentation is maintained only for users with an existing

codebase.

</div>

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 which

developers sub-class for each relational table that their code

interacts with, and the <code>Reflector</code> which is responsible

for updates, inserts, queries and deletes against the database.

The row module is intended for applications such as on-line

games, and websites 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.

If row does not fit your model, you will be best off using

the <a href="rdbms.html" shape="rect">low-level database API</a> directly,

or writing your own object/relational layer on top of it.

<h2>Class Definitions<a name="auto0"/></h2>

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:

<ul>

<li>rowColumns - list of the column names and types in the table with

the correct case</li>

<li>rowKeyColumns - list of key columns in form: <code>[(columnName,

typeName)]</code></li>

<li>rowTableName - the name of the database table</li>

</ul>

There are also two optional class attributes that can be specified:

<ul>

<li>rowForeignKeys - list of foreign keys to other database tables

in the form: <code>[(tableName, [(childColumnName, childColumnType), ...],

[(parentColumnName, parentColumnType), ...], containerMethodName, autoLoad]</code></li>

<li>rowFactoryMethod - a method that creates instances of this

class</li>

</ul>

For example:

<pre class="python"> 1

class RoomRow(row.RowObject):

rowColumns = [("roomId", "int"),

("town_id", "int"),

("name", "varchar"),

("owner", "varchar"),

("posx", "int"),

("posy", "int"),

("width", "int"),

("height", "int")]

rowKeyColumns = [("roomId", "int4")]

rowTableName = "testrooms"

100

rowFactoryMethod = [testRoomFactory]

101

</pre>

102

103

The items in the rowColumns list will become data members of

104

classes of this type when they are created by the Reflector.

105

106

<h2>Initialization<a name="auto1"/></h2>

107

108

The initialization phase builds the SQL for the database interactions.

109

It uses the system catalogs of the database to do this, but requires

110

some basic information to get started. The class attributes of

111

the classes derived from RowClass are used for this. Those classes

112

are passed to a Reflector when it is created.

113

114

There are currently two available reflectors in Twisted Enterprise,

115

the SQL Reflector for relational databases which uses the python DB

116

API, and the XML Reflector which uses a file system containing XML

117

files. The XML reflector is currently extremely slow.

118

119

An example class list for the RoomRow class we specified above using the SQLReflector:

120

121

<pre class="python">1

122

123

124

125

from twisted.enterprise.sqlreflector import SQLReflector

126

127

dbpool = adbapi.ConnectionPool("pyPgSQL.PgSQL")

128

reflector = SQLReflector( dbpool, [RoomRow] )

129

</pre>

130

131

<h2>Creating Row Objects<a name="auto2"/></h2>

132

133

There are two methods of creating RowObjects - loading from

134

the database, and creating a new instance ready to be inserted.

135

136

To load rows from the database and create RowObject instances

137

for each of the rows, use the loadObjectsFrom method of the Reflector.

138

This takes a tableName, an optional <q>user data</q> parameter,

139

and an optional <q>where clause</q>. The where clause may

140

be omitted which will retrieve all the rows from the table. For

141

example:

142

143

<pre class="python">1

144

145

146

147

148

149

150

def gotRooms(rooms):

151

for room in rooms:

152

print "Got room:", room.id

153

154

d = reflector.loadObjectsFrom("testrooms",

155

whereClause=[("id", reflector.EQUAL, 5)])

156

d.addCallback(gotRooms)

157

</pre>

158

159

For more advanced RowObject construction, loadObjectsFrom may

160

use a factoryMethod that was specified as a class attribute for

161

the RowClass derived class. This method will be called for each

162

of the rows with the class object, the userData parameter, and

163

a dictionary of data from the database keyed by column name. This

164

factory method should return a fully populated RowObject instance

165

and may be used to do pre-processing, lookups, and data transformations

166

before exposing the data to user code. An example factory method:

167

168

<pre class="python">1

169

170

171

172

def testRoomFactory(roomClass, userData, kw):

173

newRoom = roomClass(userData)

174

newRoom.__dict__.update(kw)

175

return newRoom

176

</pre>

177

178

The last method of creating a row object is for new instances

179

that do not already exist in the database table. In this case,

180

create a new instance and assign its primary key attributes and

181

all of its member data attributes, then pass it to the <code>insertRow</code>

182

method of the Reflector. For example:

183

184

<pre class="python"> 1

185

186

187

188

189

190

191

192

193

194

newRoom = RoomRow()

195

newRoom.assignKeyAttr("roomI", 11)

196

newRoom.town_id = 20

197

newRoom.name = 'newRoom1'

198

newRoom.owner = 'fred'

199

newRoom.posx = 100

200

newRoom.posy = 100

201

newRoom.width = 15

202

newRoom.height = 20

203

reflector.insertRow(newRoom).addCallback(onInsert)

204

</pre>

205

206

This will insert a new row into the database table for this

207

new RowObject instance. Note that the <code>assignKeyAttr</code>

208

method must be used to set primary key attributes - regular attribute

209

assignment of a primary key attribute of a rowObject will raise

210

an exception. This prevents the database identity of RowObject

211

from being changed by mistake.

212

213

214

<h2>Relationships Between Tables<a name="auto3"/></h2>

215

216

Specifying a foreign key for a RowClass creates a relationship

217

between database tables. When <code class="python">loadObjectsFrom</code> is called for a table, it will

218

automatically load all the children rows for the rows from the specified

219

table. The child rows will be put into a list member variable of the

220

rowObject instance with the name <code>childRows</code> or if a

221

containerMethod is specified for the foreign key relationship,

222

that method will be called on the parent row object for each row that is

223

being added to it as a child.

224

225

The autoLoad member of the foreign key definition is a flag

226

that specifies whether child rows should be auto-loaded for that

227

relationship when a parent row is loaded.

228

229

<h2>Duplicate Row Objects<a name="auto4"/></h2>

230

231

If a reflector tries to load an instance of a rowObject that

232

is already loaded, it will return a reference to the existing

233

rowObject rather than creating a new instance. The reflector maintains

234

a cache of weak references to all loaded row objects by their

235

unique keys for this purpose.

236

237

<h2>Updating Row Objects<a name="auto5"/></h2>

238

239

RowObjects have a <code>dirty</code> member attribute that is

240

set to 1 when any of the member attributes of the instance that

241

map to database columns are changed. This dirty flag can be used

242

to tell when RowObjects need to be updated back to the database.

243

In addition, the <code>setDirty</code> method can be overridden

244

to provide more complex automated handling such as dirty lists

245

(be sure to call the base class setDirty though!).

246

247

When it is determined that a RowObject instance is dirty and

248

need to have its state updated into the database, pass that object

249

to the <code>updateRow</code> method of the Reflector. For example:

250

251

<pre class="python">1

252

reflector.updateRow(room).addCallback(onUpdated)

253

</pre>

254

255

For more complex behavior, the reflector can generate the SQL

256

for the update but not perform the update. This can be useful

257

for batching up multiple updates into single requests. For example:

258

259

<pre class="python">1

260

updateSQL = reflector.updateRowSQL(room)

261

</pre>

262

263

<h2>Deleting Row Objects<a name="auto6"/></h2>

264

265

To delete a row from a database pass the RowObject instance

266

for that row to the Reflector <code>deleteRow</code> method.

267

Deleting the python Rowobject instance does not automatically

268

delete the row from the database. For example:

269

270

<pre class="python">1

271

reflector.deleteRow(room)

272

</pre>

273

274

</div>

275

276

<a href="index.html">Index</a>

277

Version: 10.0.0

278

</body>

279

</html>

b'\\ No newline at end of file'

Older »