Promote subscribe_experimental() to subscribe(), remove old subscriber implementation. (googleapis#5274)

Promote subscribe_experimental() to subscribe(), remove old subscriber implementation.

This removes the following public interfaces:
* pubsub_v1.subscriber.policy.base
* pubsub_v1.subscriber.policy.thread
* pubsub_v1.subscriber.futures.Future
* pubsub_v1.subscriber.client.Client.subscribe_experimental

Author: Jon Wayne Parrott

docs/pubsub/index.rst

@@ -90,25 +90,33 @@ the topic, and subscribe to that.
     ...     project_id=os.getenv('GOOGLE_CLOUD_PROJECT'),
     ...     sub='MY_SUBSCRIPTION_NAME',  # Set this to something appropriate.
     ... )
-    >>> subscription = subscriber.create_subscription(subscription_name, topic)
+    >>> subscriber.create_subscription(subscription_name, topic)
 
-The subscription is opened asynchronously, and messages are processed by
-use of a callback.
+To receive messages on the subscription, you *subscribe* to the subscription.
+The client opens a stream in a background process and calls a callback for each
+message received.
 
 .. code-block:: python
 
     >>> def callback(message):
     ...     print(message.data)
     ...     message.ack()
-    >>> future = subscription.open(callback)
+    >>> future = subscriber.subscribe(subscription_name, callback)
 
 You can use the future to block the main thread, and raise any exceptions
-that originate asychronously.
+that originate asynchronously.
 
 .. code-block:: python
 
     >>> future.result()
 
+You can also cancel the future to stop receiving messages.
+
+
+.. code-block:: python
+
+    >>> future.cancel()
+
 To learn more, consult the :doc:`subscriber documentation <subscriber/index>`.
 
 

docs/pubsub/subscriber/api/futures.rst

@@ -0,0 +1,6 @@
+Futures
+=======
+
+.. automodule:: google.cloud.pubsub_v1.subscriber.futures
+  :members:
+  :inherited-members:

docs/pubsub/subscriber/api/policy.rst

@@ -0,0 +1,6 @@
+Scheduler
+=========
+
+.. automodule:: google.cloud.pubsub_v1.subscriber.scheduler
+  :members:
+  :inherited-members:

docs/pubsub/subscriber/api/scheduler.rst

@@ -47,37 +47,38 @@ Pulling a Subscription
 ----------------------
 
 Once you have created a subscription (or if you already had one), the next
-step is to pull data from it. This entails two steps: first you must call
-:meth:`~.pubsub_v1.subscriber.client.Client.subscribe`, passing in the
-subscription string.
+step is to pull data from it. The subscriber client uses the
+:meth:`~.pubsub_v1.subscriber.client.Client.subscribe` method to start a
+background thread to receive messages from Pub/Sub and calls a callback with
+each message received.
 
 .. code-block:: python
 
     # As before, substitute {project} and {subscription} with appropriate
     # values for your application.
-    subscription = subscriber.subscribe(
+    future = subscriber.subscribe(
         'projects/{project}/subscriptions/{subscription}',
+        callback
     )
 
-This will return an object with an
-:meth:`~.pubsub_v1.subscriber.policy.thread.Policy.open` method; calling
-this method will actually begin consumption of the subscription.
+This will return a 
+:class:`~.pubsub_v1.subscriber.futures.StreamingPullFuture`. This future allows
+you to control the background thread that is managing the subscription.
 
 
 Subscription Callbacks
 ----------------------
 
-Because subscriptions in this Pub/Sub client are opened asynchronously,
-processing the messages that are yielded by the subscription is handled
-through **callbacks**.
+Messages received from a subscription are processed asynchronously through
+**callbacks**.
 
 The basic idea: Define a function that takes one argument; this argument
 will be a :class:`~.pubsub_v1.subscriber.message.Message` instance. This
 function should do whatever processing is necessary. At the end, the
-function should :meth:`~.pubsub_v1.subscriber.message.Message.ack` the
-message.
+function should either :meth:`~.pubsub_v1.subscriber.message.Message.ack`
+or :meth:`~.pubsub_v1.subscriber.message.Message.nack` the message.
 
-When you call :meth:`~.pubsub_v1.subscriber.policy.thread.Policy.open`, you
+When you call :meth:`~.pubsub_v1.subscriber.client.Client.subscribe`, you
 must pass the callback that will be used.
 
 Here is an example:
@@ -91,11 +92,15 @@ Here is an example:
         message.ack()
 
     # Open the subscription, passing the callback.
-    future = subscription.open(callback)
+    future = subscriber.subscribe(
+        'projects/{project}/subscriptions/{subscription}',
+        callback
+    )
 
-The :meth:`~.pubsub_v1.subscriber.policy.thread.Policy.open` method returns
-a :class:`~.pubsub_v1.subscriber.futures.Future`, which is both the interface
-to wait on messages (e.g. block the primary thread) and to address exceptions.
+The :meth:`~.pubsub_v1.subscriber.client.Client.subscribe` method returns
+a :class:`~.pubsub_v1.subscriber.futures.StreamingPullFuture`, which is both
+the interface to wait on messages (e.g. block the primary thread) and to
+address exceptions.
 
 To block the thread you are in while messages are coming in the stream,
 use the :meth:`~.pubsub_v1.subscriber.futures.Future.result` method:
@@ -104,6 +109,9 @@ use the :meth:`~.pubsub_v1.subscriber.futures.Future.result` method:
 
     future.result()
 
+.. note: This will block forever assuming no errors or that ``cancel`` is never
+    called.
+
 You can also use this for error handling; any exceptions that crop up on a
 thread will be set on the future.
 
@@ -115,6 +123,15 @@ thread will be set on the future.
         subscription.close()
         raise
 
+Finally, you can use
+:meth:`~.pubsub_v1.subscriber.futures.StreamingPullFuture.cancel` to stop
+receiving messages.
+
+
+.. code-block:: python
+
+    future.cancel()
+
 
 Explaining Ack
 --------------
@@ -142,5 +159,6 @@ API Reference
   :maxdepth: 2
 
   api/client
-  api/policy
   api/message
+  api/futures
+  api/scheduler