[Service Bus] Clarify prefetch_count versus max_message_count docstrings

[Eldert Grootenboer (EldertGrootenboer)]

Description

Fixes #42697.

The prefetch_count docstring described the setting as "the maximum number of
messages to cache", while a following sentence said that at a prefetch_count
of 0, receive_messages "would try to cache max_message_count (if provided)
within its request to the service". Using "cache" for both a standing buffer and
a per-call request is what made the two settings read as one, which is exactly
what the issue asks about.

Changes

• prefetch_count is now described as the number of messages the receiver
  requests ahead of a receive call, and every site states that it is separate
  from the max_message_count argument to receive_messages. The word "cache"
  no longer appears in these docstrings.
• The default is stated as "prefetch is turned off", replacing "messages will be
  received from the service and processed one at a time", which was misleading:
  at the default a receive call requests max_message_count messages, not one.
• receive_messages explains how the two interact on each branch. When
  prefetch_count is 0 the receiver requests max_message_count on the call;
  when it is greater than 0 the call is served first from what the receiver
  already holds and then continues on the standing prefetch credit.
• max_message_count documents that passing None falls back to
  prefetch_count, so at the default it returns an empty list immediately. The
  max_wait_time sentence is scoped so the two parameters no longer contradict
  each other.

Applied to all 8 prefetch_count sites and both receive_messages docstrings,
sync and async, with identical wording.

Verification

• Docstring-only. The AST with docstrings stripped is identical to main for all
  four files, so there is no API surface change and api.md is untouched.
• Repo pylint configuration with azure-pylint-guidelines-checker: 0 new
  findings against main. Proven non-vacuous by seeding a violation, which the
  gate reports.
• reST parsed at all 10 changed docstrings; every field body is a single
  well-formed paragraph, with a positive control confirming the check fires.
• Every behavioural claim was traced to the implementation, and the
  prefetch_count > 0 path was measured: with an empty buffer the call
  continues receiving on standing credit, and when the buffer already satisfies
  the request the wire is never touched.

Notes

Known gap, pre-existing and left unchanged: the RECEIVE_AND_DELETE warning is
scoped to prefetch_count > 0, while at the default one standing credit means a
message can be buffered in that mode. It is unrelated to this issue and belongs
in its own change.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
10 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

Clarifies Service Bus receiver documentation for prefetch_count, max_message_count, and max_wait_time.

Changes:

• Distinguishes prefetch buffering from per-call batch limits.
• Documents default and None behavior.
• Updates synchronous and asynchronous APIs consistently.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
_servicebus_receiver.py	Updates synchronous receiver docstrings.
_servicebus_client.py	Clarifies synchronous receiver factory parameters.
aio/_servicebus_receiver_async.py	Updates asynchronous receiver docstrings.
aio/_servicebus_client_async.py	Clarifies asynchronous receiver factory parameters.

Suppressed comments (2)

sdk/servicebus/azure-servicebus/azure/servicebus/_servicebus_receiver.py:635

• The new guard only scopes the no-timeout sentence. The following “If specified” sentence still says that a call with any timeout waits for that timeout, contradicting the documented max_message_count=None/prefetch_count=0 path. Carry the “messages are requested” condition across both cases.

         If messages are requested, no messages arrive, and no timeout is specified, this call will not
         return until the connection is closed. If specified, and no messages arrive within the
         timeout period, an empty list will be returned. NOTE: Setting max_wait_time on receive_messages

sdk/servicebus/azure-servicebus/azure/servicebus/aio/_servicebus_receiver_async.py:624

• The new guard only scopes the no-timeout sentence. The following “If specified” sentence still says that a call with any timeout waits for that timeout, contradicting the documented max_message_count=None/prefetch_count=0 path. Carry the “messages are requested” condition across both cases.

         If messages are requested, no messages arrive, and no timeout is specified, this call will not
         return until the connection is closed. If specified, and no messages arrive within the
         timeout period, an empty list will be returned. NOTE: Setting max_wait_time on receive_messages

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (2)

sdk/servicebus/azure-servicebus/azure/servicebus/_servicebus_receiver.py:621

• At prefetch_count == 0, the receiver can already hold one RECEIVE_AND_DELETE message from its standing link credit. _receive drains that buffer first and grants credit only for max_message_count - len(batch), so this call can request fewer than max_message_count messages from the service. Describe max_message_count as the call target and the service request as only the additional messages needed.

        the same one. When `prefetch_count` is 0, the receiver requests `max_message_count` (if
        provided) messages from the service on this call. When `prefetch_count` is greater than 0,
        the call is served first from what the receiver already holds, and if that is fewer than
        `max_message_count` it continues receiving on the receiver's standing prefetch credit until
        the count is met or the wait time elapses.

sdk/servicebus/azure-servicebus/azure/servicebus/aio/_servicebus_receiver_async.py:610

• At prefetch_count == 0, the receiver can already hold one RECEIVE_AND_DELETE message from its standing link credit. _receive drains that buffer first and grants credit only for max_message_count - len(batch), so this call can request fewer than max_message_count messages from the service. Describe max_message_count as the call target and the service request as only the additional messages needed.

        the same one. When `prefetch_count` is 0, the receiver requests `max_message_count` (if
        provided) messages from the service on this call. When `prefetch_count` is greater than 0,
        the call is served first from what the receiver already holds, and if that is fewer than
        `max_message_count` it continues receiving on the receiver's standing prefetch credit until
        the count is met or the wait time elapses.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.