Rename db.wait to db.iternotifies.

James William Pye · James William Pye · commit 87da56a7920b · 2010-03-20T20:16:33.000-07:00
"wait" was far too ambiguous.
diff --git a/postgresql/api.py b/postgresql/api.py
@@ -989,7 +989,7 @@ def listening_channels(self) -> ["channel name", ...]:
 		"""
 
 	@abstractmethod
-	def wait(self, timeout = None) -> collections.Iterator:
+	def iternotifies(self, timeout = None) -> collections.Iterator:
 		"""
 		Return an iterator to the notifications received by the connection. The
 		iterator *must* produce triples in the form ``(channel, payload, pid)``.
diff --git a/postgresql/documentation/__init__.py b/postgresql/documentation/__init__.py
@@ -1,6 +1,5 @@
 ##
-# copyright 2009, James William Pye
-# http://python.projects.postgresql.org
+# .documentation
 ##
 r"""
 See: `postgresql.documentation.index`
diff --git a/postgresql/documentation/admin.py b/postgresql/documentation/admin.py
@@ -1,6 +1,5 @@
 ##
-# copyright 2009, James William Pye
-# http://python.projects.postgresql.org
+# .documentation.admin
 ##
 __doc__ = open(__file__[:__file__.rfind('.')] + '.txt').read()
 __docformat__ = 'reStructuredText'
diff --git a/postgresql/documentation/bin.py b/postgresql/documentation/bin.py
@@ -1,6 +1,5 @@
 ##
-# copyright 2009, James William Pye
-# http://python.projects.postgresql.org
+# .documentation.bin
 ##
 __doc__ = open(__file__[:__file__.rfind('.')] + '.txt').read()
 __docformat__ = 'reStructuredText'
diff --git a/postgresql/documentation/changes.py b/postgresql/documentation/changes.py
@@ -1,6 +1,5 @@
 ##
-# copyright 2009, James William Pye
-# http://python.projects.postgresql.org
+# .documentation.changes
 ##
 __doc__ = open(__file__[:__file__.rfind('.')] + '.txt').read()
 __docformat__ = 'reStructuredText'
diff --git a/postgresql/documentation/clientparameters.py b/postgresql/documentation/clientparameters.py
@@ -1,6 +1,5 @@
 ##
-# copyright 2009, James William Pye
-# http://python.projects.postgresql.org
+# .documentation.clientparameters
 ##
 __doc__ = open(__file__[:__file__.rfind('.')] + '.txt').read()
 __docformat__ = 'reStructuredText'
diff --git a/postgresql/documentation/driver.py b/postgresql/documentation/driver.py
@@ -1,6 +1,5 @@
 ##
-# copyright 2009, James William Pye
-# http://python.projects.postgresql.org
+# .documentation.driver
 ##
 __doc__ = open(__file__[:__file__.rfind('.')] + '.txt').read()
 __docformat__ = 'reStructuredText'
diff --git a/postgresql/documentation/driver.txt b/postgresql/documentation/driver.txt
@@ -380,7 +380,7 @@ The methods and properties on the connection object are ready for use:
   Return an iterator producing the channel names that are currently being
   listened to.
 
- ``db.wait(timeout = None)``
+ ``db.iternotifies(timeout = None)``
   Return an iterator to the NOTIFYs received on the connection. The iterator
   will yield notification triples consisting of ``(channel, payload, pid)``.
   While iterating, the connection should *not* be used in other threads.
diff --git a/postgresql/documentation/gotchas.py b/postgresql/documentation/gotchas.py
@@ -1,6 +1,5 @@
 ##
-# copyright 2009, James William Pye
-# http://python.projects.postgresql.org
+# .documentation.gotchas
 ##
 __doc__ = open(__file__[:__file__.rfind('.')] + '.txt').read()
 __docformat__ = 'reStructuredText'
diff --git a/postgresql/documentation/html/_sources/driver.txt b/postgresql/documentation/html/_sources/driver.txt
@@ -380,7 +380,7 @@ The methods and properties on the connection object are ready for use:
   Return an iterator producing the channel names that are currently being
   listened to.
 
- ``db.wait(timeout = None)``
+ ``db.iternotifies(timeout = None)``
   Return an iterator to the NOTIFYs received on the connection. The iterator
   will yield notification triples consisting of ``(channel, payload, pid)``.
   While iterating, the connection should *not* be used in other threads.
diff --git a/postgresql/documentation/html/_sources/notifyman.txt b/postgresql/documentation/html/_sources/notifyman.txt
@@ -32,15 +32,15 @@ connections. In cases where only one connection needs to be serviced, the
 Listening on a Single Connection
 ================================
 
-The ``db.wait()`` method is a simplification of the notification manager. It
+The ``db.iternotifies()`` method is a simplification of the notification manager. It
 returns an iterator to the notifications received on the subject connection.
 The iterator yields triples consisting of the ``channel`` being
 notified, the ``payload`` sent with the notification, and the ``pid`` of the
 backend that caused the notification::
 
 	>>> db.listen('for_rabbits')
 	>>> db.notify('for_rabbits')
-	>>> for x in db.wait():
+	>>> for x in db.iternotifies():
 	...  channel, payload, pid = x
 	...  break
 	>>> assert channel == 'for_rabbits'
@@ -53,10 +53,10 @@ backend that caused the notification::
 The iterator, by default, will continue listening forever unless the connection
 is terminated--thus the immediate ``break`` statement in the above loop. In
 cases where some additional activity is necessary, a timeout parameter may be
-given to the ``wait`` method in order to allow "idle" events to occur at the
-designated frequency::
+given to the ``iternotifies`` method in order to allow "idle" events to occur
+at the designated frequency::
 
-	>>> for x in db.wait(0.5):
+	>>> for x in db.iternotifies(0.5):
 	...  if x is None:
 	...   break
 
@@ -163,7 +163,7 @@ this is the appropriate way to collect pending notifications on active
 connections where using the connection exclusively for waiting is not
 practical::
 
-	>>> notifies = list(db.wait(0))
+	>>> notifies = list(db.iternotifies(0))
 
 Or with a NotificationManager instance::
 
@@ -179,7 +179,7 @@ Summary of Characteristics
 
  * The iterator will continue until the connections die.
  * Objects yielded by the iterator are either `None`, an "idle event", or an
-   individual notification triple if using ``db.wait()``, or a
+   individual notification triple if using ``db.iternotifies()``, or a
    ``(db, notifies)`` pair if using the base `NotificationManager`.
  * When a connection dies or raises an exception, it will be removed from
    the ``nm.connections`` set and added to the ``nm.garbage`` set.
diff --git a/postgresql/documentation/html/admin.html b/postgresql/documentation/html/admin.html
@@ -143,7 +143,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
       &copy; Copyright 2010, James William Pye &lt;x@jwp.name&gt;.
-      Last updated on Mar 19, 2010.
+      Last updated on Mar 20, 2010.
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
     </div>
   </body>
diff --git a/postgresql/documentation/html/alock.html b/postgresql/documentation/html/alock.html
@@ -209,7 +209,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
       &copy; Copyright 2010, James William Pye &lt;x@jwp.name&gt;.
-      Last updated on Mar 19, 2010.
+      Last updated on Mar 20, 2010.
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
     </div>
   </body>
diff --git a/postgresql/documentation/html/bin.html b/postgresql/documentation/html/bin.html
@@ -316,7 +316,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
       &copy; Copyright 2010, James William Pye &lt;x@jwp.name&gt;.
-      Last updated on Mar 19, 2010.
+      Last updated on Mar 20, 2010.
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
     </div>
   </body>
diff --git a/postgresql/documentation/html/changes.html b/postgresql/documentation/html/changes.html
@@ -152,7 +152,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
       &copy; Copyright 2010, James William Pye &lt;x@jwp.name&gt;.
-      Last updated on Mar 19, 2010.
+      Last updated on Mar 20, 2010.
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
     </div>
   </body>
diff --git a/postgresql/documentation/html/clientparameters.html b/postgresql/documentation/html/clientparameters.html
@@ -415,7 +415,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
       &copy; Copyright 2010, James William Pye &lt;x@jwp.name&gt;.
-      Last updated on Mar 19, 2010.
+      Last updated on Mar 20, 2010.
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
     </div>
   </body>
diff --git a/postgresql/documentation/html/copyman.html b/postgresql/documentation/html/copyman.html
@@ -317,7 +317,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
       &copy; Copyright 2010, James William Pye &lt;x@jwp.name&gt;.
-      Last updated on Mar 19, 2010.
+      Last updated on Mar 20, 2010.
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
     </div>
   </body>
diff --git a/postgresql/documentation/html/doctrees/driver.doctree b/postgresql/documentation/html/doctrees/driver.doctree
diff --git a/postgresql/documentation/html/doctrees/environment.pickle b/postgresql/documentation/html/doctrees/environment.pickle
diff --git a/postgresql/documentation/html/doctrees/notifyman.doctree b/postgresql/documentation/html/doctrees/notifyman.doctree
diff --git a/postgresql/documentation/html/driver.html b/postgresql/documentation/html/driver.html
@@ -379,7 +379,7 @@ <h3>Database Interface Points<a class="headerlink" href="#database-interface-poi
 <dt><tt class="docutils literal"><span class="pre">db.listening_channels()</span></tt></dt>
 <dd>Return an iterator producing the channel names that are currently being
 listened to.</dd>
-<dt><tt class="docutils literal"><span class="pre">db.wait(timeout</span> <span class="pre">=</span> <span class="pre">None)</span></tt></dt>
+<dt><tt class="docutils literal"><span class="pre">db.iternotifies(timeout</span> <span class="pre">=</span> <span class="pre">None)</span></tt></dt>
 <dd>Return an iterator to the NOTIFYs received on the connection. The iterator
 will yield notification triples consisting of <tt class="docutils literal"><span class="pre">(channel,</span> <span class="pre">payload,</span> <span class="pre">pid)</span></tt>.
 While iterating, the connection should <em>not</em> be used in other threads.
@@ -1817,7 +1817,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
       &copy; Copyright 2010, James William Pye &lt;x@jwp.name&gt;.
-      Last updated on Mar 19, 2010.
+      Last updated on Mar 20, 2010.
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
     </div>
   </body>
diff --git a/postgresql/documentation/html/genindex.html b/postgresql/documentation/html/genindex.html
@@ -83,7 +83,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
       &copy; Copyright 2010, James William Pye &lt;x@jwp.name&gt;.
-      Last updated on Mar 19, 2010.
+      Last updated on Mar 20, 2010.
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
     </div>
   </body>
diff --git a/postgresql/documentation/html/gotchas.html b/postgresql/documentation/html/gotchas.html
@@ -192,7 +192,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
       &copy; Copyright 2010, James William Pye &lt;x@jwp.name&gt;.
-      Last updated on Mar 19, 2010.
+      Last updated on Mar 20, 2010.
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
     </div>
   </body>
diff --git a/postgresql/documentation/html/index.html b/postgresql/documentation/html/index.html
@@ -222,7 +222,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
       &copy; Copyright 2010, James William Pye &lt;x@jwp.name&gt;.
-      Last updated on Mar 19, 2010.
+      Last updated on Mar 20, 2010.
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
     </div>
   </body>
diff --git a/postgresql/documentation/html/lib.html b/postgresql/documentation/html/lib.html
@@ -590,7 +590,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
       &copy; Copyright 2010, James William Pye &lt;x@jwp.name&gt;.
-      Last updated on Mar 19, 2010.
+      Last updated on Mar 20, 2010.
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
     </div>
   </body>
diff --git a/postgresql/documentation/html/notifyman.html b/postgresql/documentation/html/notifyman.html
@@ -70,14 +70,14 @@ <h3>Navigation</h3>
 <cite>postgresql.api.Database.wait</cite> method can be used to simplify the process.</p>
 <div class="section" id="listening-on-a-single-connection">
 <h2>Listening on a Single Connection<a class="headerlink" href="#listening-on-a-single-connection" title="Permalink to this headline">&para;</a></h2>
-<p>The <tt class="docutils literal"><span class="pre">db.wait()</span></tt> method is a simplification of the notification manager. It
+<p>The <tt class="docutils literal"><span class="pre">db.iternotifies()</span></tt> method is a simplification of the notification manager. It
 returns an iterator to the notifications received on the subject connection.
 The iterator yields triples consisting of the <tt class="docutils literal"><span class="pre">channel</span></tt> being
 notified, the <tt class="docutils literal"><span class="pre">payload</span></tt> sent with the notification, and the <tt class="docutils literal"><span class="pre">pid</span></tt> of the
 backend that caused the notification:</p>
 <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">db</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="s">&#39;for_rabbits&#39;</span><span class="p">)</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="n">db</span><span class="o">.</span><span class="n">notify</span><span class="p">(</span><span class="s">&#39;for_rabbits&#39;</span><span class="p">)</span>
-<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">db</span><span class="o">.</span><span class="n">wait</span><span class="p">():</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">db</span><span class="o">.</span><span class="n">iternotifies</span><span class="p">():</span>
 <span class="gp">... </span> <span class="n">channel</span><span class="p">,</span> <span class="n">payload</span><span class="p">,</span> <span class="n">pid</span> <span class="o">=</span> <span class="n">x</span>
 <span class="gp">... </span> <span class="k">break</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="n">channel</span> <span class="o">==</span> <span class="s">&#39;for_rabbits&#39;</span>
@@ -91,9 +91,9 @@ <h2>Listening on a Single Connection<a class="headerlink" href="#listening-on-a-
 <p>The iterator, by default, will continue listening forever unless the connection
 is terminated&#8211;thus the immediate <tt class="docutils literal"><span class="pre">break</span></tt> statement in the above loop. In
 cases where some additional activity is necessary, a timeout parameter may be
-given to the <tt class="docutils literal"><span class="pre">wait</span></tt> method in order to allow &#8220;idle&#8221; events to occur at the
-designated frequency:</p>
-<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">db</span><span class="o">.</span><span class="n">wait</span><span class="p">(</span><span class="mf">0.5</span><span class="p">):</span>
+given to the <tt class="docutils literal"><span class="pre">iternotifies</span></tt> method in order to allow &#8220;idle&#8221; events to occur
+at the designated frequency:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">db</span><span class="o">.</span><span class="n">iternotifies</span><span class="p">(</span><span class="mf">0.5</span><span class="p">):</span>
 <span class="gp">... </span> <span class="k">if</span> <span class="n">x</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span>
 <span class="gp">... </span>  <span class="k">break</span>
 </pre></div>
@@ -193,7 +193,7 @@ <h2>Zero Timeout<a class="headerlink" href="#zero-timeout" title="Permalink to t
 this is the appropriate way to collect pending notifications on active
 connections where using the connection exclusively for waiting is not
 practical:</p>
-<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">notifies</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">db</span><span class="o">.</span><span class="n">wait</span><span class="p">(</span><span class="mi">0</span><span class="p">))</span>
+<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">notifies</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">db</span><span class="o">.</span><span class="n">iternotifies</span><span class="p">(</span><span class="mi">0</span><span class="p">))</span>
 </pre></div>
 </div>
 <p>Or with a NotificationManager instance:</p>
@@ -210,7 +210,7 @@ <h2>Summary of Characteristics<a class="headerlink" href="#summary-of-characteri
 <ul class="simple">
 <li>The iterator will continue until the connections die.</li>
 <li>Objects yielded by the iterator are either <cite>None</cite>, an &#8220;idle event&#8221;, or an
-individual notification triple if using <tt class="docutils literal"><span class="pre">db.wait()</span></tt>, or a
+individual notification triple if using <tt class="docutils literal"><span class="pre">db.iternotifies()</span></tt>, or a
 <tt class="docutils literal"><span class="pre">(db,</span> <span class="pre">notifies)</span></tt> pair if using the base <cite>NotificationManager</cite>.</li>
 <li>When a connection dies or raises an exception, it will be removed from
 the <tt class="docutils literal"><span class="pre">nm.connections</span></tt> set and added to the <tt class="docutils literal"><span class="pre">nm.garbage</span></tt> set.</li>
@@ -290,7 +290,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
       &copy; Copyright 2010, James William Pye &lt;x@jwp.name&gt;.
-      Last updated on Mar 19, 2010.
+      Last updated on Mar 20, 2010.
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
     </div>
   </body>
diff --git a/postgresql/documentation/html/search.html b/postgresql/documentation/html/search.html
@@ -83,7 +83,7 @@ <h3>Navigation</h3>
   
     <div class="footer">
       &copy; Copyright 2010, James William Pye &lt;x@jwp.name&gt;.
-      Last updated on Mar 19, 2010.
+      Last updated on Mar 20, 2010.
       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.3.
     </div>
   <script type="text/javascript" src="searchindex.js"></script>
diff --git a/postgresql/documentation/html/searchindex.js b/postgresql/documentation/html/searchindex.js
diff --git a/postgresql/documentation/index.py b/postgresql/documentation/index.py
@@ -1,6 +1,5 @@
 ##
-# copyright 2009, James William Pye
-# http://python.projects.postgresql.org
+# .documentation.index
 ##
 __doc__ = open(__file__[:__file__.rfind('.')] + '.txt').read()
 __docformat__ = 'reStructuredText'
diff --git a/postgresql/documentation/lib.py b/postgresql/documentation/lib.py
@@ -1,6 +1,5 @@
 ##
-# copyright 2009, James William Pye
-# http://python.projects.postgresql.org
+# .documentation.lib
 ##
 __doc__ = open(__file__[:__file__.rfind('.')] + '.txt').read()
 __docformat__ = 'reStructuredText'
diff --git a/postgresql/documentation/notifyman.txt b/postgresql/documentation/notifyman.txt
@@ -32,15 +32,15 @@ connections. In cases where only one connection needs to be serviced, the
 Listening on a Single Connection
 ================================
 
-The ``db.wait()`` method is a simplification of the notification manager. It
+The ``db.iternotifies()`` method is a simplification of the notification manager. It
 returns an iterator to the notifications received on the subject connection.
 The iterator yields triples consisting of the ``channel`` being
 notified, the ``payload`` sent with the notification, and the ``pid`` of the
 backend that caused the notification::
 
 	>>> db.listen('for_rabbits')
 	>>> db.notify('for_rabbits')
-	>>> for x in db.wait():
+	>>> for x in db.iternotifies():
 	...  channel, payload, pid = x
 	...  break
 	>>> assert channel == 'for_rabbits'
@@ -53,10 +53,10 @@ backend that caused the notification::
 The iterator, by default, will continue listening forever unless the connection
 is terminated--thus the immediate ``break`` statement in the above loop. In
 cases where some additional activity is necessary, a timeout parameter may be
-given to the ``wait`` method in order to allow "idle" events to occur at the
-designated frequency::
+given to the ``iternotifies`` method in order to allow "idle" events to occur
+at the designated frequency::
 
-	>>> for x in db.wait(0.5):
+	>>> for x in db.iternotifies(0.5):
 	...  if x is None:
 	...   break
 
@@ -163,7 +163,7 @@ this is the appropriate way to collect pending notifications on active
 connections where using the connection exclusively for waiting is not
 practical::
 
-	>>> notifies = list(db.wait(0))
+	>>> notifies = list(db.iternotifies(0))
 
 Or with a NotificationManager instance::
 
@@ -179,7 +179,7 @@ Summary of Characteristics
 
  * The iterator will continue until the connections die.
  * Objects yielded by the iterator are either `None`, an "idle event", or an
-   individual notification triple if using ``db.wait()``, or a
+   individual notification triple if using ``db.iternotifies()``, or a
    ``(db, notifies)`` pair if using the base `NotificationManager`.
  * When a connection dies or raises an exception, it will be removed from
    the ``nm.connections`` set and added to the ``nm.garbage`` set.
diff --git a/postgresql/driver/__init__.py b/postgresql/driver/__init__.py
@@ -1,6 +1,5 @@
 ##
-# copyright 2009, James William Pye
-# http://python.projects.postgresql.org
+# .driver package
 ##
 """
 Driver package for providing an interface to a PostgreSQL database.
diff --git a/postgresql/driver/pq3.py b/postgresql/driver/pq3.py
@@ -71,8 +71,8 @@
 	(b'M', "could not establish connection to server"),
 ))
 
+# generate an id for a client statement or cursor
 def ID(s, title = None, IDNS = 'py:'):
-	'generate an id for a client statement or cursor'
 	return IDNS + hex(id(s))
 
 def declare_statement_string(
@@ -2609,7 +2609,7 @@ def unlisten(self, *channels, len = len):
 			qstr += '; UNLISTEN ' + x.replace('"', '""')
 		return self.execute(qstr)
 
-	def wait(self, timeout = None):
+	def iternotifies(self, timeout = None):
 		nm = NotificationManager(self, timeout = timeout)
 		for x in nm:
 			if x is None:
diff --git a/postgresql/test/test_copyman.py b/postgresql/test/test_copyman.py
diff --git a/postgresql/test/test_notifyman.py b/postgresql/test/test_notifyman.py
