Method try_next

pymongo/synchronous/change_stream.py:340–433

Advance the cursor without blocking indefinitely. This method returns the next change document without waiting indefinitely for the next change. For example:: with db.collection.watch() as stream: while stream.alive: change = stream.t

(self)

    @_csot.apply
    def try_next(self) -> Optional[_DocumentType]:
        """Advance the cursor without blocking indefinitely.

        This method returns the next change document without waiting
        indefinitely for the next change. For example::

            with db.collection.watch() as stream:
                while stream.alive:
                    change = stream.try_next()
                    # Note that the ChangeStream's resume token may be updated
                    # even when no changes are returned.
                    print("Current resume token: %r" % (stream.resume_token,))
                    if change is not None:
                        print("Change document: %r" % (change,))
                        continue
                    # We end up here when there are no recent changes.
                    # Sleep for a while before trying again to avoid flooding
                    # the server with getMore requests when no changes are
                    # available.
                    time.sleep(10)

        If no change document is cached locally then this method runs a single
        getMore command. If the getMore yields any documents, the next
        document is returned, otherwise, if the getMore returns no documents
        (because there have been no changes) then ``None`` is returned.

        :return: The next change document or ``None`` when no document is available
          after running a single getMore or when the cursor is closed.

        .. versionadded:: 3.8
        """
        if not self._closed and not self._cursor.alive:
            self._resume()

        # Attempt to get the next change with at most one getMore and at most
        # one resume attempt.
        try:
            try:
                change = self._cursor._try_next(True)
            except PyMongoError as exc:
                if not _resumable(exc):
                    raise
                self._resume()
                change = self._cursor._try_next(False)
        except PyMongoError as exc:
            # Close the stream after a fatal error.
            if not _resumable(exc) and not exc.timeout:
                self.close()
            raise
        # Catch KeyboardInterrupt, CancelledError, etc. and cleanup.
        except BaseException:
            self.close()
            raise

        # Check if the cursor was invalidated.
        if not self._cursor.alive:
            self._closed = True