The debounce operator allows you to wait for a defined delay until an item is emitted. Each time an item is received, a timer is started with this delay as an expiration time. Items are emitted only when the timer triggers. This has the effect of dropping any item that is received before the delay has completed.

The following figure shows the marble diagram of the debounce operator:

The prototype of this operator is the following:

Observable.debounce(self, duetime, scheduler=None)

The duetime parameter is the delay in milliseconds that must elapse between two item emissions on the source observable so that an item is emitted on the output observable. The scheduler parameter allows you to provide an alternative scheduler than the default one. If no scheduler is provided, then the timeout scheduler is used. The timeout scheduler is implemented on top of the Python Timer class of the threading module. So, by default, the debounce operator is scheduled on a dedicated thread.

Here is an example of how to use it:

import time
from datetime import datetime

def slow_sequence(observer):
    print("sending 1 at {}".format(datetime.now()))
    observer.on_next(1)
    time.sleep(0.8)
    print("sending 2 at {}".format(datetime.now()))
    observer.on_next(2)
    time.sleep(0.8)
    print("sending 3 at {}".format(datetime.now()))
    observer.on_next(3)
    print("sending 4 at {}".format(datetime.now()))    
    observer.on_next(4)
    

numbers = Observable.create(slow_sequence)

numbers.debounce(700).subscribe(
    on_next = lambda i: print("on_next {} at {}".format(i, datetime.now())),
    on_error = lambda e: print("on_error: {}".format(e)),
    on_completed = lambda: print("on_completed")
)

time.sleep(3)

Here, a custom Observable is created. This custom observable sends two items with a delay of 800 milliseconds between them, and then two items without a delay between them. The debounce operator is used with a due time of 700 milliseconds. The result of this example is the following:

sending 1 at 2018-08-01 22:14:12.236241
on_next 1 at 2018-08-01 22:14:12.940047
sending 2 at 2018-08-01 22:14:13.038211
on_next 2 at 2018-08-01 22:14:13.741002
sending 3 at 2018-08-01 22:14:13.840345
sending 4 at 2018-08-01 22:14:13.841314
on_next 4 at 2018-08-01 22:14:14.544288

The timestamps of the sending logs show that the delay between each item emission is correct: 2 is sent 800 milliseconds after 1, 3 is emitted 800 milliseconds after 2, and 4 is emitted right after 3. Also, the timestamps of the on_next logs correspond to the expected behavior—item 1 is received about 700 milliseconds after it has been sent. The small imprecision is due to the implementation of the Timer class, which is not designed to be very precise. Item 2 is received 700 milliseconds after is has been sent. Item 3 is not emitted at all because item 4 was received before the due time. Finally, 4 is also received 700 milliseconds after it has been sent.