Add db.do() method.

Author: James William Pye

postgresql/api.py

@@ -899,6 +899,18 @@ def settings(self) -> Settings:
 		A `Settings` instance bound to the `Database`.
 		"""
 
+	@abstractmethod
+	def do(source, language = None) -> None:
+		"""
+		Execute a DO statement using the given source. Always returns `None` and
+		raise a `postgresql.exceptions.Error` subclass on error.
+
+		If `language` is `None`, no language will be given to the DO statement,
+		allowing the default configured language to be used.
+
+		Likely to be a function of Connection.execute.
+		"""
+
 	@abstractmethod
 	def execute(sql) -> None:
 		"""

postgresql/bin/pg_python.py

@@ -90,9 +90,8 @@ def command(argv = sys.argv):
 		# New built-ins
 			'connector' : connector,
 			'db' : connection,
+			'do' : connection.do,
 			'prepare' : connection.prepare,
-			# XXX: being replaced by sqlexec.
-			'execute' : connection.execute,
 
 			'sqlexec' : connection.execute,
 			'settings' : connection.settings,

postgresql/documentation/bin.txt

@@ -28,10 +28,12 @@ with the following built-ins:
  ``proc``
   ``db.proc``
 
+ ``do``
+  ``db.do``, execute a single DO statement.
+
  ``sqlexec``
   ``db.execute``, execute multiple SQL statements (``None`` is always returned)
 
-
 pg_python Usage
 ---------------
 

postgresql/documentation/changes.txt

@@ -1,6 +1,12 @@
 Changes
 =======
 
+1.0 in development
+------------------
+
+ * Added db.do() method for DO-statement support(convenience method).
+ * **DEPRECATION**: Removed 2PC support documentation.
+
 0.9.2 released on 2009-12-14
 ----------------------------
 
@@ -60,7 +66,6 @@ Changes
  * Document msghook attributes, and use postgresql.sys.errformat for
    postgresql.exceptions.Error.__str__.
 
-
 0.8.2 released on 2009-06-13
 ----------------------------
 
@@ -69,7 +74,6 @@ Changes
    qualified names. [Reported by Dallas Morisett]
  * Fix DB-API setting of rowcount after execute. [Reported by Mike Bayer; 1010643]
 
-
 0.8.1 released on 2009-04-30
 ----------------------------
 

postgresql/documentation/driver.txt

@@ -332,6 +332,11 @@ The methods and properties on the connection object are ready for use:
   This is used in cases where the cursor was declared on the server. See
   `Cursors`_ for more information.
 
+ ``db.do(source[, language = None])``
+  Execute a DO statement on the server. If `language` is `None`, none will be
+  specified and the `default_do_language` database setting will be used by
+  PostgreSQL.
+
  ``db.execute(sql_statements_string)``
   Run a block of SQL on the server. This method returns `None` unless an error
   occurs. If errors occur, the processing of the statements will stop and the

postgresql/driver/pq3.py

@@ -1702,6 +1702,12 @@ def execute(self, query : str) -> None:
 		self._pq_push(q, self)
 		self._pq_complete()
 
+	def do(self, source : str, language : str = None) -> None:
+		sql = "DO " + pg_str.quote_literal(source)
+		if language is not None:
+			sql = sql + " LANGUAGE " + pg_str.quote_ident(language)
+		self.execute(sql + ";")
+
 	def xact(self, gid = None, isolation = None, mode = None):
 		x = Transaction(self, gid = gid, isolation = isolation, mode = mode)
 		return x

postgresql/lib/libsys.sql

@@ -133,3 +133,6 @@ SELECT pg_catalog.pg_relation_size($1::text)::bigint
 
 [pg_reload_conf]
 SELECT pg_reload_conf()
+
+[languages::column]
+SELECT lanname FROM pg_catalog.pg_language

postgresql/test/test_driver.py

@@ -1365,5 +1365,21 @@ def testSettings(self):
 		dall.sort(key=itemgetter(0))
 		self.failUnlessEqual(dall, all)
 
+	def testDo(self):
+		# plpgsql is expected to be available.
+		if self.db.version_info[:2] < (8,5):
+			return
+		if 'plpgsql' not in self.db.sys.languages():
+			self.db.execute("CREATE LANGUAGE plpgsql")
+		self.db.do(
+			"BEGIN CREATE TEMP TABLE do_tmp_table(i int, t text); END",
+			language = 'plpgsql')
+		self.failUnlessEqual(len(self.db.prepare("SELECT * FROM do_tmp_table")()), 0)
+		# now, with the default language.
+		self.db.settings["default_do_language"] = 'plpgsql'
+		self.db.do(
+			"BEGIN INSERT INTO do_tmp_table VALUES (100, 'foo'); END")
+		self.failUnlessEqual(len(self.db.prepare("SELECT * FROM do_tmp_table")()), 1)
+
 if __name__ == '__main__':
 	unittest.main()