Update db.notify()'s API.

James William Pye · James William Pye · commit 4b4965790fbb · 2010-03-25T18:38:00.000-07:00
Implement notify() to accept variable arguments and keywords for NOTIFY'ing
multiple channels with or without payloads.
diff --git a/postgresql/api.py b/postgresql/api.py
@@ -963,7 +963,16 @@ def notify(self, *channels, **channel_and_payload) -> int:
 		NOTIFY the channels with the given payload.
 
 		Equivalent to issuing "NOTIFY <channel>" or "NOTIFY <channel>, <payload>"
-		if a payload is given.
+		for each item in `channels` and `channel_and_payload`. All NOTIFYs issued
+		*must* occur in the same transaction.
+
+		The items in `channels` can either be a string or a tuple. If a string,
+		no payload is given, but if an item is a `builtins.tuple`, the second item
+		will be given as the payload. `channels` offers a means to issue NOTIFYs
+		in guaranteed order.
+
+		The items in `channel_and_payload` are all payloaded NOTIFYs where the
+		keys are the channels and the values are the payloads. Order is undefined.
 		"""
 
 	@abstractmethod
diff --git a/postgresql/documentation/driver.txt b/postgresql/documentation/driver.txt
@@ -380,6 +380,33 @@ 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.
 
+ ``Connection.notify(*channels, **channel_and_payload)``
+  NOTIFY the channels with the given payload. Sends a batch of ``NOTIFY``
+  statements to the server.
+
+  Equivalent to issuing "NOTIFY <channel>" or "NOTIFY <channel>, <payload>"
+  for each item in `channels` and `channel_and_payload`. All NOTIFYs issued
+  will occur in the same transaction, regardless of auto-commit.
+
+  The items in `channels` can either be a string or a tuple. If a string,
+  no payload is given, but if an item is a `builtins.tuple`, the second item
+  in the pair will be given as the payload, and the first as the channel.
+  `channels` offers a means to issue NOTIFYs in guaranteed order::
+
+   >>> db.notify('channel1', ('different_channel', 'payload'))
+
+  In the above, ``NOTIFY "channel1";`` will be issued first, followed by
+  ``NOTIFY "different_channel", 'payload';``.
+
+  The items in `channel_and_payload` are all payloaded NOTIFYs where the
+  keys are the channels and the values are the payloads. Order is undefined::
+
+   >>> db.notify(channel_name = 'payload_data')
+
+  `channels` and `channels_and_payload` can be used together. In such cases all
+  NOTIFY statements generated from `channels_and_payload` will follow those in
+  `channels`.
+
  ``Connection.iternotifies(timeout = None)``
   Return an iterator to the NOTIFYs received on the connection. The iterator
   will yield notification triples consisting of ``(channel, payload, pid)``.
diff --git a/postgresql/documentation/html/_sources/driver.txt b/postgresql/documentation/html/_sources/driver.txt
@@ -380,6 +380,33 @@ 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.
 
+ ``Connection.notify(*channels, **channel_and_payload)``
+  NOTIFY the channels with the given payload. Sends a batch of ``NOTIFY``
+  statements to the server.
+
+  Equivalent to issuing "NOTIFY <channel>" or "NOTIFY <channel>, <payload>"
+  for each item in `channels` and `channel_and_payload`. All NOTIFYs issued
+  will occur in the same transaction, regardless of auto-commit.
+
+  The items in `channels` can either be a string or a tuple. If a string,
+  no payload is given, but if an item is a `builtins.tuple`, the second item
+  in the pair will be given as the payload, and the first as the channel.
+  `channels` offers a means to issue NOTIFYs in guaranteed order::
+
+   >>> db.notify('channel1', ('different_channel', 'payload'))
+
+  In the above, ``NOTIFY "channel1";`` will be issued first, followed by
+  ``NOTIFY "different_channel", 'payload';``.
+
+  The items in `channel_and_payload` are all payloaded NOTIFYs where the
+  keys are the channels and the values are the payloads. Order is undefined::
+
+   >>> db.notify(channel_name = 'payload_data')
+
+  `channels` and `channels_and_payload` can be used together. In such cases all
+  NOTIFY statements generated from `channels_and_payload` will follow those in
+  `channels`.
+
  ``Connection.iternotifies(timeout = None)``
   Return an iterator to the NOTIFYs received on the connection. The iterator
   will yield notification triples consisting of ``(channel, payload, pid)``.
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/driver.html b/postgresql/documentation/html/driver.html
@@ -379,6 +379,30 @@ <h3>Database Interface Points<a class="headerlink" href="#database-interface-poi
 <dt><tt class="docutils literal"><span class="pre">Connection.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">Connection.notify(*channels,</span> <span class="pre">**channel_and_payload)</span></tt></dt>
+<dd><p class="first">NOTIFY the channels with the given payload. Sends a batch of <tt class="docutils literal"><span class="pre">NOTIFY</span></tt>
+statements to the server.</p>
+<p>Equivalent to issuing &#8220;NOTIFY &lt;channel&gt;&#8221; or &#8220;NOTIFY &lt;channel&gt;, &lt;payload&gt;&#8221;
+for each item in <cite>channels</cite> and <cite>channel_and_payload</cite>. All NOTIFYs issued
+will occur in the same transaction, regardless of auto-commit.</p>
+<p>The items in <cite>channels</cite> can either be a string or a tuple. If a string,
+no payload is given, but if an item is a <cite>builtins.tuple</cite>, the second item
+in the pair will be given as the payload, and the first as the channel.
+<cite>channels</cite> offers a means to issue NOTIFYs in guaranteed order:</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">notify</span><span class="p">(</span><span class="s">&#39;channel1&#39;</span><span class="p">,</span> <span class="p">(</span><span class="s">&#39;different_channel&#39;</span><span class="p">,</span> <span class="s">&#39;payload&#39;</span><span class="p">))</span>
+</pre></div>
+</div>
+<p>In the above, <tt class="docutils literal"><span class="pre">NOTIFY</span> <span class="pre">&quot;channel1&quot;;</span></tt> will be issued first, followed by
+<tt class="docutils literal"><span class="pre">NOTIFY</span> <span class="pre">&quot;different_channel&quot;,</span> <span class="pre">'payload';</span></tt>.</p>
+<p>The items in <cite>channel_and_payload</cite> are all payloaded NOTIFYs where the
+keys are the channels and the values are the payloads. Order is undefined:</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">notify</span><span class="p">(</span><span class="n">channel_name</span> <span class="o">=</span> <span class="s">&#39;payload_data&#39;</span><span class="p">)</span>
+</pre></div>
+</div>
+<p class="last"><cite>channels</cite> and <cite>channels_and_payload</cite> can be used together. In such cases all
+NOTIFY statements generated from <cite>channels_and_payload</cite> will follow those in
+<cite>channels</cite>.</p>
+</dd>
 <dt><tt class="docutils literal"><span class="pre">Connection.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>.
diff --git a/postgresql/documentation/html/searchindex.js b/postgresql/documentation/html/searchindex.js
diff --git a/postgresql/driver/pq3.py b/postgresql/driver/pq3.py
@@ -2576,19 +2576,27 @@ def clone(self, *args, **kw):
 		c.connect()
 		return c
 
-	def notify(self, channel, payload = None,
-		notify_with_payload = "NOTIFY \"{0}\", '{1}'".format,
-		notify_without_payload = "NOTIFY \"{0}\"".format,
-	):
-		if payload is not None:
-			return self.execute(notify_with_payload(
-				channel.replace('"', '""'),
-				payload.replace("'", "''"),
+	def notify(self, *channels, **channel_and_payload):
+		notifies = ""
+		if channels:
+			notifies += ';'.join((
+				'NOTIFY "' + x.replace('"', '""') + '"' # str() case
+				if x.__class__ is not tuple else (
+					# tuple() case
+					'NOTIFY "' + x[0].replace('"', '""') + """",'""" + \
+					x[1].replace("'", "''") + "'"
+				)
+				for x in channels
 			))
-		else:
-			return self.execute(notify_without_payload(
-				channel.replace('"', '""'),
+			notifies += ';'
+		if channel_and_payload:
+			notifies += ';'.join((
+				'NOTIFY "' + channel.replace('"', '""') + """",'""" + \
+				payload.replace("'", "''") + "'"
+				for channel, payload in channel_and_payload.items()
 			))
+			notifies += ';'
+		return self.execute(notifies)
 
 	def listening_channels(self):
 		if self.version_info[:2] > (8,4):
diff --git a/postgresql/test/test_driver.py b/postgresql/test/test_driver.py
@@ -1627,6 +1627,34 @@ def testNotify(self):
 		self.failUnlessRaises(Exception, db.listen, 'doesntexist', 'x'*64)
 		self.failUnless('doesntexist' not in db.listening_channels())
 
+	@pg_tmp
+	def testPayloads(self):
+		if db.version_info[:2] >= (9,0):
+			db.listen('foo')
+			db.notify(foo = 'bar')
+			self.failUnlessEqual(('foo', 'bar', db.backend_id), list(db.iternotifies(0))[0])
+			db.notify(('foo', 'barred'))
+			self.failUnlessEqual(('foo', 'barred', db.backend_id), list(db.iternotifies(0))[0])
+			# mixed
+			db.notify(('foo', 'barred'), 'foo', ('foo', 'bleh'), foo = 'kw')
+			self.failUnlessEqual([
+					('foo', 'barred', db.backend_id),
+					('foo', '', db.backend_id),
+					('foo', 'bleh', db.backend_id),
+					# Keywords are appened.
+					('foo', 'kw', db.backend_id),
+				], list(db.iternotifies(0))
+			)
+			# multiple keywords
+			expect = [
+				('foo', 'meh', db.backend_id),
+				('bar', 'foo', db.backend_id),
+			]
+			rexpect = list(reversed(expect))
+			db.listen('bar')
+			db.notify(foo = 'meh', bar = 'foo')
+			self.failUnless(list(db.iternotifies(0)) in [expect, rexpect])
+
 	@pg_tmp
 	def testMessageHook(self):
 		create = db.prepare('CREATE TEMP TABLE msghook (i INT PRIMARY KEY)')
