Documentation work in release preparation.

James William Pye · James William Pye · commit b6cba32c82ca · 2012-10-05T18:19:50.000-07:00
diff --git a/postgresql/documentation/changes-v1.1.rst b/postgresql/documentation/changes-v1.1.rst
@@ -1,13 +1,25 @@
 Changes in v1.1
 ===============
 
-1.1.0 in development
---------------------
+1.1.0
+-----
 
  * Remove two-phase commit interfaces per deprecation in v1.0.
    For proper two phase commit use, a lock manager must be employed that
    the implementation did nothing to accommodate for.
  * Add support for unpacking anonymous records (Elvis)
  * Support PostgreSQL 9.2 (Elvis)
+ * Python 3.3 Support (Elvis)
  * Add column execution method. (jwp)
- * Add one-shot statement interface. Connection.query (jwp)
+ * Add one-shot statement interface. Connection.query.* (jwp)
+ * Modify the inet/cidr support by relying on the ipaddress module introduced in Python 3.3 (Google's ipaddr project)
+   The existing implementation relied on simple str() representation supported by the
+   socket module. Unfortunately, MS Windows' socket library does not appear to support the
+   necessary functionality, or Python's socket module does not expose it. ipaddress fixes
+   the problem.
+
+.. note::
+ The `ipaddress` module is now required for local inet and cidr. While it is
+ of "preliminary" status, the ipaddr project has been around for some time and
+ well supported. ipaddress appears to be the safest way forward for native
+ network types.
diff --git a/postgresql/documentation/driver.rst b/postgresql/documentation/driver.rst
@@ -1208,14 +1208,27 @@ available when using queries as the results, or handle to the results, are direc
 
 Queries have access to all execution methods:
 
- ``Connection.query(sql, *parameters)``
- ``Connection.query.rows(sql, *parameters)``
- ``Connection.query.column(sql, *parameters)``
- ``Connection.query.first(sql, *parameters)``
- ``Connection.query.chunks(sql, *parameters)``
- ``Connection.query.declare(sql, *parameters)``
- ``Connection.query.load_rows(sql, collections.Iterable(parameters))``
- ``Connection.query.load_chunks(collections.Iterable(collections.Iterable(parameters)))``
+ * ``Connection.query(sql, *parameters)``
+ * ``Connection.query.rows(sql, *parameters)``
+ * ``Connection.query.column(sql, *parameters)``
+ * ``Connection.query.first(sql, *parameters)``
+ * ``Connection.query.chunks(sql, *parameters)``
+ * ``Connection.query.declare(sql, *parameters)``
+ * ``Connection.query.load_rows(sql, collections.Iterable(parameters))``
+ * ``Connection.query.load_chunks(collections.Iterable(collections.Iterable(parameters)))``
+
+In cases where a sequence of one-shot queries needs to be performed, it may be important to
+avoid unnecessary repeat attribute resolution from the connection object as the ``query``
+property is an interface object created on access. Caching the target execution methods is
+recommended::
+
+   qrows = db.query.rows
+   l = []
+   for x in my_queries:
+      l.append(qrows(x))
+
+The characteristic of Each execution method is discussed in the prior
+`Prepared Statements`_ section.
 
 Stored Procedures
 =================
diff --git a/postgresql/documentation/index.rst b/postgresql/documentation/index.rst
@@ -31,7 +31,7 @@ Reference
    :maxdepth: 2
 
    bin
-   modules
+   reference
 
 Changes
 -------
diff --git a/postgresql/temporal.py b/postgresql/temporal.py
@@ -24,11 +24,14 @@ class Temporal(object):
 		>>> with pg_tmp:
 		...  ps = db.prepare('SELECT 1')
 		...  assert ps.first() == 1
-	
+
 	Or `pg_tmp` can decorate a method or function.
 	"""
+
+	#: Format the cluster directory name.
 	cluster_dirname = 'pg_tmp_{0}_{1}'.format
 	cluster = None
+
 	_init_pid_ = None
 	_local_id_ = 0
 	builtins_keys = {
diff --git a/postgresql/test/test_driver.py b/postgresql/test/test_driver.py
@@ -1794,6 +1794,15 @@ def testQuery(self):
 		self.assertEqual(next(db.query.rows('select 1')), (1,))
 		self.assertEqual(db.query.declare('select 1').read(), [(1,)])
 
+		self.assertEqual(db.query('select $1::int', 1), [(1,)])
+		self.assertEqual(db.query.first('select $1::int', 1), 1)
+		self.assertEqual(next(db.query.column('select $1::int', 1)), 1)
+		self.assertEqual(next(db.query.rows('select $1::int', 1)), (1,))
+		self.assertEqual(db.query.declare('select $1::int', 1).read(), [(1,)])
+
+		self.assertEqual(db.query.load_rows('select $1::int', [[1]]), None)
+		self.assertEqual(db.query.load_chunks('select $1::int', [[[1]]]), None)
+
 class test_typio(unittest.TestCase):
 	@pg_tmp
 	def testIdentify(self):
