python 39 lines · 6 steps

A thread-safe debounce decorator in Python

A decorator that delays a function until calls stop arriving, using a lock and a restartable timer.

Explained by highlit
Advanced decorators debounce threading closures concurrency
1import threading
2from functools import wraps
3 
4 
5def debounce(wait):
6 def decorator(fn):
7 lock = threading.Lock()
8 state = {"timer": None}
9 
10 @wraps(fn)
11 def wrapper(*args, **kwargs):
12 def call():
13 with lock:
14 state["timer"] = None
15 fn(*args, **kwargs)
16 
17 with lock:
18 if state["timer"] is not None:
19 state["timer"].cancel()
20 state["timer"] = threading.Timer(wait, call)
21 state["timer"].daemon = True
22 state["timer"].start()
23 
24 def cancel():
25 with lock:
26 if state["timer"] is not None:
27 state["timer"].cancel()
28 state["timer"] = None
29 
30 wrapper.cancel = cancel
31 return wrapper
32 
33 return decorator
34 
35 
36@debounce(0.3)
37def on_search_input(query):
38 results = search_index.query(query)
39 render(results)
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1Debouncing collapses a burst of rapid calls into one execution after the activity settles.
  2. 2A shared mutable dict plus a lock lets nested closures coordinate state safely across threads.
  3. 3Attaching a method to the returned wrapper extends a decorated function without changing its signature.

Related explainers

python 
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
 
app = FastAPI()
 

Building a WebSocket chat with FastAPI

websockets broadcast connection-management
Intermediate 9 steps
python 
import time
import uuid
 
from django.utils.deprecation import MiddlewareMixin

Attaching per-request context in Django

middleware request lifecycle multi-tenancy
Intermediate 7 steps
javascript 
function evaluate(expression) {
  const tokens = tokenize(expression);
  let pos = 0;
 

Building a recursive descent calculator

parsing recursion operator-precedence
Intermediate 8 steps
go 
func (w *Watcher) resetDebounce(d time.Duration) {
	if !w.timer.Stop() {
		select {
		case <-w.timer.C:

Debouncing a stream of events in Go

debounce timers channels
Advanced 7 steps
python 
import random
from typing import Iterator, List
 
 

How reservoir sampling picks k items

reservoir-sampling streaming randomness
Intermediate 5 steps
python 
import secrets
 
from django.contrib.auth import authenticate, login
from django.core.cache import cache

Two-factor login with OTP in Django

two-factor-auth one-time-passwords caching
Intermediate 9 steps

Share this explainer

Here's the card — post it anywhere.

A thread-safe debounce decorator in Python — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code