PYTHON-5993 Trim the getMore span comments and docstrings

Cut each to the invariant a reader needs, dropping spec references and
restatements of the code.

Author: blink1073

pymongo/_otel.py

@@ -65,11 +65,8 @@
     "_CURRENT_OPERATION_NAME", default=None
 )
 
-# True while the driver is iterating a cursor of its own to build the return
-# value of one public API call (list_collection_names, index_information, ...).
-# Such a call gets a single operation span covering every getMore it sends,
-# whereas a cursor handed back to the caller gets a fresh operation span per
-# caller-driven getMore. See internal_cursor_iteration.
+# True while the driver is draining a cursor of its own to build one public API
+# call's return value. See internal_cursor_iteration.
 _INTERNAL_CURSOR_ITERATION: ContextVar[bool] = ContextVar(
     "_INTERNAL_CURSOR_ITERATION", default=False
 )
@@ -140,11 +137,9 @@ def _env_truthy(name: str) -> bool:
 def internal_cursor_iteration() -> Iterator[None]:
     """Mark the enclosing block as driver-internal cursor iteration.
 
-    Wrap the block in which a public API method creates a cursor and drains it
-    itself to build its return value. Everything the block sends, including
-    every getMore, then belongs to that method's one operation span, as the
-    OTel spec requires. Outside such a block the cursor is assumed to reach the
-    caller, whose iteration is a separate operation per getMore.
+    Everything the block sends, every getMore included, belongs to the enclosing
+    method's one operation span. Outside such a block a getMore is assumed to be
+    caller-driven and gets an operation span of its own.
     """
     token = _INTERNAL_CURSOR_ITERATION.set(True)
     try:
@@ -326,11 +321,8 @@ def start_command_span(
         return None
 
     collection = _extract_collection_name(command_name, dbname, cmd)
-    # A getMore's own command value is the id of the cursor being read, which is
-    # the value db.mongodb.cursor_id takes for a command operating on an
-    # existing cursor: the id sent, not whatever the reply comes back with. It
-    # has to be read here rather than from the reply because the reply is 0 once
-    # the cursor is exhausted, and the attribute is required even then.
+    # The id sent, not the reply's, which is 0 once the cursor is exhausted
+    # while the attribute is still required.
     sent_cursor_id = cmd.get(_GET_MORE) if command_name == _GET_MORE else None
     if not isinstance(sent_cursor_id, int):
         sent_cursor_id = None
@@ -391,9 +383,8 @@ def start_command_span(
 def _set_operation_cursor_id(cursor_id: int) -> None:
     """Set db.mongodb.cursor_id on the ambient operation span, if there is one.
 
-    Guarded on the operation-name contextvar for the same reason
-    ``start_command_span``'s backfill is: without it the "current span" could be
-    an unrelated span belonging to the host application.
+    Guarded on the operation-name contextvar, since the current span could
+    otherwise be an unrelated one belonging to the host application.
     """
     if _CURRENT_OPERATION_NAME.get() is None:
         return
@@ -408,13 +399,9 @@ def end_command_span_success(span: Optional[Span], reply: _DocumentOut) -> None:
         return
     cursor = reply.get("cursor")
     if isinstance(cursor, Mapping) and cursor.get("id"):
-        # Per the spec the attribute is omitted rather than set to 0, so a
-        # cursor-creating command that leaves no cursor open reports nothing. A
-        # getMore keeps the id it sent, which this does not overwrite with a 0.
+        # Omitted rather than set to 0, so a getMore keeps the id it sent.
         cursor_id = cursor["id"]
         span.set_attribute("db.mongodb.cursor_id", cursor_id)
-        # The operation span carries the same attribute: this reply's id for a
-        # cursor-creating command, or the already-set sent id for a getMore.
         _set_operation_cursor_id(cursor_id)
     span.end()
 
@@ -496,9 +483,8 @@ def start_operation_span(
     ``parent_span`` becomes an *explicit* parent rather than being read from
     ambient context, so a concurrent unrelated session cannot be captured.
 
-    ``cursor_id`` sets ``db.mongodb.cursor_id`` up front, for an operation
-    reading an existing cursor: the id is known before the command is built and
-    is needed even if the operation fails before any command span exists.
+    ``cursor_id`` sets ``db.mongodb.cursor_id`` up front, since a getMore knows
+    it before the command is built and needs it even if the operation fails.
 
     ``set_current=False`` leaves the span and the operation-name contextvar
     alone, for a caller that makes it current with ``use_operation_span``.

pymongo/asynchronous/change_stream.py

@@ -250,14 +250,9 @@ async def _run_aggregation_cmd(
             result_processor=self._process_result,
             comment=self._comment,
         )
-        # Deliberately no operation_telemetry is attached to the resulting
-        # cursor here: a change stream can tail indefinitely, so an operation
-        # span covering its whole lifetime (initial query + every getMore,
-        # like other command cursors) would never end while it's watching.
-        # Leaving it unattached means each getMore instead gets its own
-        # short-lived sibling "getMore" operation span, less ideal nesting,
-        # but not a leaked/never-exported span. Do not "fix" this without
-        # addressing that tradeoff.
+        # No operation span is attached to the resulting cursor: a change stream
+        # can tail indefinitely, so a span covering its whole lifetime would
+        # never end. Each getMore gets its own sibling span instead.
         return await self._client._retryable_read(
             cmd.get_cursor,
             self._target._read_preference_for(session),

pymongo/asynchronous/client_bulk.py

@@ -336,11 +336,8 @@ async def _process_results_cursor(
                 session=session,
                 comment=self.comment,
             )
-            # This cursor's getMores run inside the enclosing bulkWrite
-            # operation span, so their command spans belong under it directly;
-            # a getMore operation span of their own would be spurious. The
-            # cursor is also per-batch and never surfaces to the caller, so
-            # there is no cursor-lifetime span to own here.
+            # These getMores run inside the enclosing bulkWrite operation span,
+            # so a getMore operation span of their own would be spurious.
             cmd_cursor._reuse_current_span_for_getmore = True
             await cmd_cursor._maybe_pin_connection(conn)
 

pymongo/asynchronous/command_cursor.py

@@ -246,10 +246,8 @@ async def _refresh(self) -> int:
             if not own_span:
                 await self._send_message(getmore)
             else:
-                # _send_message ends the span itself on every failure path, and
-                # an exhausted cursor's close() ends it on the way out; both are
-                # idempotent, so only a successful send leaving the cursor open
-                # is left to handle here.
+                # _send_message ends the span on every failure path and close()
+                # ends it once exhausted, leaving only this case.
                 try:
                     await self._send_message(getmore)
                 except BaseException as exc:

pymongo/asynchronous/cursor.py

@@ -1089,9 +1089,8 @@ async def _refresh(self) -> int:
                 collection=self._collection.name,
                 set_current=False,
             )
-            # The query's span covers the query alone unless this cursor is
-            # being drained by the public API call that created it, in which
-            # case the span stays open to cover that call's getMores too.
+            # The query's span stays open only when the call that created this
+            # cursor drains it itself, to cover that call's getMores too.
             own_span = not is_internal_cursor_iteration()
             await self._send_message_in_operation_span(q, own_span)
         elif self._id:  # Get More

pymongo/asynchronous/mongo_client.py

@@ -1912,12 +1912,9 @@ async def _run_operation(
         :param address: Optional address when sending a message
             to a specific server, used for getMore.
         :param operation_telemetry: The calling cursor's operation span, or None,
-            so this send's command spans nest under it. Covers one caller-driven
-            getMore, or a whole API call that drains the cursor itself.
-        :param reuse_current_span: Create no operation span at all and leave the
-            ambient span in place as the parent for this operation's command
-            spans. Mutually exclusive with ``operation_telemetry``. Defaults to
-            False.
+            so this send's command spans nest under it.
+        :param reuse_current_span: Leave the ambient span as the parent for this
+            operation's command spans, creating none, defaults to False.
         """
         if operation.conn_mgr:
             server = await self._select_server(
@@ -2028,13 +2025,9 @@ async def _retry_internal(
         :param operation_id: Stable operation id shared across retries, defaults to None
         :param operation_telemetry: A cursor's operation span, which this call
             makes current but neither creates nor ends, defaults to None.
-        :param reuse_current_span: Create no operation span at all and leave the
-            ambient span in place as the parent for this operation's command
-            spans. For callers that know a suitable operation span is already
-            current, where a second one would be spurious (the client
-            bulk-write results cursor's getMores, which belong under the
-            enclosing bulkWrite span). Mutually exclusive with
-            ``operation_telemetry``. Defaults to False.
+        :param reuse_current_span: Leave the ambient span as the parent for this
+            operation's command spans, creating none. Mutually exclusive with
+            ``operation_telemetry``, defaults to False.
 
         :return: Output of the calling func()
         """
@@ -2087,10 +2080,7 @@ async def _retryable_read(
         :param is_aggregate_write: If this is a aggregate operation with a write, defaults to False.
         :param operation_id: Stable operation id shared across retries, defaults to None
         :param operation_telemetry: As for ``_retry_internal``, defaults to None.
-        :param reuse_current_span: Create no operation span at all and leave the
-            ambient span in place as the parent for this operation's command
-            spans. Mutually exclusive with ``operation_telemetry``. Defaults to
-            False.
+        :param reuse_current_span: As for ``_retry_internal``, defaults to False.
         """
 
         # Ensure that the client supports retrying on reads and there is no session in
@@ -2133,15 +2123,12 @@ async def _retryable_read_cursor(
         """Run a command cursor read within its own operation span.
 
         Takes the same arguments as :meth:`_retryable_read`, plus the namespace
-        for the span. A command cursor's first batch is fetched inside that
-        call, before the cursor exists, so the span cannot be owned by the
-        cursor the way a find cursor's is; create it here instead.
-
-        The span ends with the command that created the cursor. Later getMores
-        belong to whoever drives iteration: each one the caller drives gets an
-        operation span of its own, so only a public API call that drains the
-        cursor itself (see ``_otel.internal_cursor_iteration``) keeps this one
-        open, by handing it to the cursor.
+        for the span. A command cursor's first batch is fetched before the cursor
+        exists, so the span cannot be owned by the cursor and is created here.
+
+        The span ends with the creating command, unless a public API call
+        draining the cursor itself (see ``_otel.internal_cursor_iteration``)
+        keeps it open by handing it to the cursor.
         """
         operation_telemetry = _operation_telemetry_or_none(
             self.options.tracing,
@@ -3041,9 +3028,8 @@ def __init__(
         self._operation_id = operation_id
         if reuse_current_span and operation_telemetry is not None:
             raise ValueError("reuse_current_span and operation_telemetry are mutually exclusive")
-        # With nothing passed in, create the span here and end it in run(); with a
-        # span passed in, the caller owns it. reuse_current_span means an enclosing
-        # span is already current, so this object creates none.
+        # With nothing passed in, create the span here and end it in run(); with
+        # a span passed in, or reuse_current_span, an outer caller owns it.
         self._owns_telemetry = operation_telemetry is None and not reuse_current_span
         if self._owns_telemetry:
             operation_telemetry = _operation_telemetry_or_none(

pymongo/cursor_shared.py

@@ -58,9 +58,8 @@ class _AgnosticCursorBase(Generic[_DocumentType], ABC):
     _session: Optional[Any]
     _killed: bool
     _operation_telemetry: Optional[Any] = None
-    # Set by callers whose getMores belong under an operation span that is
-    # already current (the client bulk-write results cursor), rather than under
-    # a getMore operation span of their own.
+    # Set by callers whose getMores belong under an already-current operation
+    # span (the client bulk-write results cursor) instead of one of their own.
     _reuse_current_span_for_getmore: bool = False
 
     @abstractmethod
@@ -125,13 +124,9 @@ def _prepare_to_die(self, already_killed: bool) -> tuple[int, Optional[_CursorAd
     def _end_operation_telemetry(self, exc: Optional[BaseException] = None) -> None:
         """End the operation span currently attached to this cursor, exactly once.
 
-        No span is ever scoped to the cursor's lifetime: a caller-driven getMore
-        attaches a span of its own and ends it as soon as that getMore
-        completes. What can outlive a single command is the span of a public API
-        call that drains the cursor itself (see
-        ``_otel.internal_cursor_iteration``), which ends when the cursor is
-        exhausted or, for a cursor abandoned part-way, at close()/__del__.
-        Idempotent, so every one of those paths can call it unconditionally.
+        Only the span of a public API call draining the cursor itself outlives a
+        single command (see ``_otel.internal_cursor_iteration``). Idempotent, so
+        every path that might end a cursor can call it unconditionally.
         """
         telemetry = self._operation_telemetry
         if telemetry is None:
@@ -145,22 +140,18 @@ def _end_operation_telemetry(self, exc: Optional[BaseException] = None) -> None:
     def _start_getmore_operation_telemetry(self, dbname: str, collname: Optional[str]) -> bool:
         """Give the getMore about to be sent an operation span of its own.
 
-        The spec requires an operation span per caller-driven getMore, and
-        forbids nesting it under the operation that created the cursor, since
-        the application may do unrelated work between batches.
+        Never nested under the operation that created the cursor, since the
+        application may do unrelated work between batches.
 
-        Returns True when the caller now owns a span and must end it once the
-        getMore completes. Returns False when this getMore already belongs to
-        another operation, or when tracing is off.
+        :return: True when the caller now owns the span and must end it.
         """
         if self._operation_telemetry is not None or self._reuse_current_span_for_getmore:
             return False
         tracing_options = self._collection.database.client.options.tracing
         if not _otel._is_tracing_enabled(tracing_options):
             return False
-        # A cursor opened by a command (listCollections, listIndexes, a
-        # database-level aggregate) reports a namespace like
-        # "$cmd.listCollections", which names no user collection.
+        # A command cursor's namespace looks like "$cmd.listCollections", which
+        # names no user collection.
         if _otel.is_command_namespace(collname):
             collname = None
         self._operation_telemetry = _operation_telemetry_or_none(
@@ -177,15 +168,10 @@ def _start_getmore_operation_telemetry(self, dbname: str, collname: Optional[str
     def _attach_operation_telemetry(self, telemetry: Any) -> None:
         """Adopt the still-open operation span of the call that created this cursor.
 
-        For command cursors only, and only when that call goes on to drain the
-        cursor itself, so its getMores belong to the same operation (see
-        ``_otel.internal_cursor_iteration``). A cursor returned to the caller
-        has its creating span ended right away and never gets here.
-
-        A command cursor exhausted by its first batch is marked ``_killed`` in
-        ``__init__`` without calling ``close()``, so no getMore is sent and
-        neither ``_refresh()`` nor ``_die_lock()`` runs. Ending the span here
-        keeps that case prompt instead of leaving it to ``__del__``.
+        Only for a call that drains the cursor itself, so its getMores belong to
+        the same operation (see ``_otel.internal_cursor_iteration``). A cursor
+        exhausted by its first batch never calls ``close()``, so end its span
+        here rather than leaving it to ``__del__``.
         """
         self._operation_telemetry = telemetry
         if self._killed:

pymongo/synchronous/change_stream.py

@@ -248,14 +248,9 @@ def _run_aggregation_cmd(self, session: Optional[ClientSession]) -> CommandCurso
             result_processor=self._process_result,
             comment=self._comment,
         )
-        # Deliberately no operation_telemetry is attached to the resulting
-        # cursor here: a change stream can tail indefinitely, so an operation
-        # span covering its whole lifetime (initial query + every getMore,
-        # like other command cursors) would never end while it's watching.
-        # Leaving it unattached means each getMore instead gets its own
-        # short-lived sibling "getMore" operation span, less ideal nesting,
-        # but not a leaked/never-exported span. Do not "fix" this without
-        # addressing that tradeoff.
+        # No operation span is attached to the resulting cursor: a change stream
+        # can tail indefinitely, so a span covering its whole lifetime would
+        # never end. Each getMore gets its own sibling span instead.
         return self._client._retryable_read(
             cmd.get_cursor,
             self._target._read_preference_for(session),

pymongo/synchronous/client_bulk.py

@@ -334,11 +334,8 @@ def _process_results_cursor(
                 session=session,
                 comment=self.comment,
             )
-            # This cursor's getMores run inside the enclosing bulkWrite
-            # operation span, so their command spans belong under it directly;
-            # a getMore operation span of their own would be spurious. The
-            # cursor is also per-batch and never surfaces to the caller, so
-            # there is no cursor-lifetime span to own here.
+            # These getMores run inside the enclosing bulkWrite operation span,
+            # so a getMore operation span of their own would be spurious.
             cmd_cursor._reuse_current_span_for_getmore = True
             cmd_cursor._maybe_pin_connection(conn)
 

pymongo/synchronous/command_cursor.py

@@ -246,10 +246,8 @@ def _refresh(self) -> int:
             if not own_span:
                 self._send_message(getmore)
             else:
-                # _send_message ends the span itself on every failure path, and
-                # an exhausted cursor's close() ends it on the way out; both are
-                # idempotent, so only a successful send leaving the cursor open
-                # is left to handle here.
+                # _send_message ends the span on every failure path and close()
+                # ends it once exhausted, leaving only this case.
                 try:
                     self._send_message(getmore)
                 except BaseException as exc: