Add 'Subscription.auto_ack' factory.

Addresses (on the other PR):
#1637 (comment)

Author: tseaver

gcloud/pubsub/subscription.py

@@ -123,6 +123,24 @@ def path(self):
         """URL path for the subscription's APIs"""
         return '/%s' % (self.full_name,)
 
+    def auto_ack(self, return_immediately=False, max_messages=1, client=None):
+        """:class:`AutoAck` factory
+
+        :type return_immediately: boolean
+        :param return_immediately: passed through to :meth:`Subscription.pull`
+
+        :type max_messages: int
+        :param max_messages: passed through to :meth:`Subscription.pull`
+
+        :type client: :class:`gcloud.pubsub.client.Client` or ``NoneType``
+        :param client: passed through to :meth:`Subscription.pull` and
+                      :meth:`Subscription.acknowledge`.
+
+        :rtype: :class:`AutoAck`
+        :returns: the instance created for the given ``ack_id`` and ``message``
+        """
+        return AutoAck(self, return_immediately, max_messages, client)
+
     def _require_client(self, client):
         """Check client or verify over-ride.
 

gcloud/pubsub/test_subscription.py

@@ -134,16 +134,40 @@ def test_from_api_repr_w_topics_w_topic_match(self):
 
     def test_full_name_and_path(self):
         PROJECT = 'PROJECT'
-        SUB_NAME = 'sub_name'
-        SUB_FULL = 'projects/%s/subscriptions/%s' % (PROJECT, SUB_NAME)
+        SUB_FULL = 'projects/%s/subscriptions/%s' % (PROJECT, self.SUB_NAME)
         SUB_PATH = '/%s' % (SUB_FULL,)
         TOPIC_NAME = 'topic_name'
         CLIENT = _Client(project=PROJECT)
         topic = _Topic(TOPIC_NAME, client=CLIENT)
-        subscription = self._makeOne(SUB_NAME, topic)
+        subscription = self._makeOne(self.SUB_NAME, topic)
         self.assertEqual(subscription.full_name, SUB_FULL)
         self.assertEqual(subscription.path, SUB_PATH)
 
+    def test_autoack_defaults(self):
+        from gcloud.pubsub.subscription import AutoAck
+        client = _Client(project=self.PROJECT)
+        topic = _Topic(self.TOPIC_NAME, client=client)
+        subscription = self._makeOne(self.SUB_NAME, topic)
+        auto_ack = subscription.auto_ack()
+        self.assertTrue(isinstance(auto_ack, AutoAck))
+        self.assertTrue(auto_ack._subscription is subscription)
+        self.assertEqual(auto_ack._return_immediately, False)
+        self.assertEqual(auto_ack._max_messages, 1)
+        self.assertTrue(auto_ack._client is None)
+
+    def test_autoack_explicit(self):
+        from gcloud.pubsub.subscription import AutoAck
+        client1 = _Client(project=self.PROJECT)
+        client2 = _Client(project=self.PROJECT)
+        topic = _Topic(self.TOPIC_NAME, client=client1)
+        subscription = self._makeOne(self.SUB_NAME, topic)
+        auto_ack = subscription.auto_ack(True, 10, client2)
+        self.assertTrue(isinstance(auto_ack, AutoAck))
+        self.assertTrue(auto_ack._subscription is subscription)
+        self.assertEqual(auto_ack._return_immediately, True)
+        self.assertEqual(auto_ack._max_messages, 10)
+        self.assertTrue(auto_ack._client is client2)
+
     def test_create_pull_wo_ack_deadline_w_bound_client(self):
         RESPONSE = {
             'topic': self.TOPIC_PATH,