[Documentation Issue] Pub/Sub default max_messages is unclear in 0.13.0 docs

[joeholley]

Page Name: pubsub-usage
Release: 0.13.0

This section:

Fetch pending messages for a pull subscription:

>>> from gcloud import pubsub
>>> client = pubsub.Client()
>>> topic = client.topic('topic_name')
>>> subscription = topic.subscription('subscription_name')
>>> with topic.batch() as batch:
...     batch.publish('this is the first message_payload')
...     batch.publish('this is the second message_payload',
...                   attr1='value1', attr2='value2')
>>> received = subscription.pull()  # API request
>>> messages = [recv[1] for recv in received]
>>> [message.message_id for message in messages]
[<message_id1>, <message_id2>]
>>> [message.data for message in messages]
['this is the first message_payload', 'this is the second message_payload']
>>> [message.attributes for message in messages]
[{}, {'attr1': 'value1', 'attr2': 'value2'}]

Does not pull all pending messages in my very simple test code. It only pulls one pending message. I can get multiple by specifying 'max_messages' greater than 1 in the 'subscription.pull()' call.

Has something changed in the implementation since this doc was written?

[joeholley]

Tested with two simple scripts: one that publishes one message a second on infinite loop, and one that does subscription.pull() once per 10 seconds on an infinite loop. No args for subscription.pull() results in one message received. Specifying max_messages > 1 will allow me to get multiple in one pull.

[joeholley]

Does look like http://googlecloudplatform.github.io/gcloud-python/stable/pubsub-subscription.html#gcloud.pubsub.subscription.Subscription.pull shows a default value of 1 specified for the max_messages arg. Documentation should be updated, I guess?

[tseaver]

Thanks for the report! I will update the docs.

[dhermes]

@tmatsuo Is there a better default than 1 for max_messages?

---

@tseaver I would give you the line in pubsub-usage.rst where received = subscription.pull() # API request should be changed, but GitHub doesn't allow linking into RST or MD files, so I can't.

@joeholley Do you think a suitable change would be to just change that line to

received = subscription.pull(max_messages=2)

or do you think there should be a separate example showcasing that the default is 1?

---

@joeholley RE: Subscription.pull shows a default value of 1, that is what's in the actual code. I'm not sure how familiar you are with Sphinx, but most of the module docs are completely generated by Sphinx with no curation by us, and that includes the defaults for keyword arguments.

[tseaver]

@dhermes the actual snippet on master is now being pulled from docs/pubsub_snippets.py, and shows the max_messages argument.

[dhermes]

Nice! I forgot about that. w00t!

So the issue is that 0.13.0 is out of date.

@joeholley Does that resolve your issue? Also, in general, when filing a docs bug, double check latest before filing, since stable and 0.x.y are docs that will be frozen at the time they were generated.

[tseaver]

@joeholley please reopen if needed.

[tmatsuo]

@dhermes I think it is a mandatory parameter for the core API. Having 1 as a default in this layer seems reasonable.

[dhermes]

Thanks @tmatsuo!