Function stream_generator

praw/models/util.py:93–260

Yield new items from ``function`` as they become available. :param function: A callable that returns a :class:`.ListingGenerator`, e.g., :meth:`.Subreddit.comments` or :meth:`.Subreddit.new`. :param attribute_name: The field to use as an ID (default: ``"fullname"``). :param excl

(
    function: Callable,
    *,
    attribute_name: str = "fullname",
    continue_after_id: str | None = None,
    exception_handler: Callable[[Exception], None] | None = None,
    exclude_before: bool = False,
    pause_after: int | None = None,
    skip_existing: bool = False,
    **function_kwargs: Any,
)

def stream_generator(
    function: Callable,
    *,
    attribute_name: str = "fullname",
    continue_after_id: str | None = None,
    exception_handler: Callable[[Exception], None] | None = None,
    exclude_before: bool = False,
    pause_after: int | None = None,
    skip_existing: bool = False,
    **function_kwargs: Any,
) -> Iterator[Any]:
    """Yield new items from ``function`` as they become available.

    :param function: A callable that returns a :class:`.ListingGenerator`, e.g.,
        :meth:`.Subreddit.comments` or :meth:`.Subreddit.new`.
    :param attribute_name: The field to use as an ID (default: ``"fullname"``).
    :param exclude_before: When ``True`` does not pass ``params`` to ``function``
        (default: ``False``).
    :param exception_handler: A callable that is invoked with the exception raised while
        fetching items, instead of letting it propagate and terminate the stream. After
        the handler returns, the stream waits (using the same exponential backoff
        applied to empty responses) and then resumes. To stop the stream, re-raise the
        exception (or raise a new one) from within the handler. When ``None``,
        exceptions propagate and terminate the stream as before (default: ``None``).
    :param pause_after: An integer representing the number of requests that result in no
        new items before this function yields ``None``, effectively introducing a pause
        into the stream. A negative value yields ``None`` after items from a single
        response have been yielded, regardless of number of new items obtained in that
        response. A value of ``0`` yields ``None`` after every response resulting in no
        new items, and a value of ``None`` never introduces a pause (default: ``None``).
    :param skip_existing: When ``True``, this does not yield any results from the first
        request thereby skipping any items that existed in the stream prior to starting
        the stream (default: ``False``).
    :param continue_after_id: The initial item ID value to use for ``before`` in
        ``params``. The stream will continue from the item following this one (default:
        ``None``).

    Additional keyword arguments will be passed to ``function``.

    .. note::

        This function internally uses an exponential delay with jitter between
        subsequent responses that contain no new results, up to a maximum delay of just
        over 16 seconds. In practice, that means that the time before pause for
        ``pause_after=N+1`` is approximately twice the time before pause for
        ``pause_after=N``.

    For example, to create a stream of comment replies, try:

    .. code-block:: python

        reply_function = reddit.inbox.comment_replies
        for reply in praw.models.util.stream_generator(reply_function):
            print(reply)

    To pause a comment stream after six responses with no new comments, try:

    .. code-block:: python