How to Implement a Tumbling Window Counter in Python

Count events that fall within a fixed-size sliding time window using a deque and pruning logic.

Easy Python 3.9+ Aug 9, 2026 Streaming & messaging 14 views 0 copies

streaming window aggregation deque

Python code

28 lines

Python 3.9+

from collections import deque
import time


class TumblingWindowCounter:
    def __init__(self, window_size_seconds):
        self.window_size = window_size_seconds
        self.window = deque()

    def add_event(self, timestamp):
        self.window.append(timestamp)

    def count(self, current_time):
        while self.window and current_time - self.window[0] >= self.window_size:
            self.window.popleft()
        return len(self.window)


if __name__ == "__main__":
    counter = TumblingWindowCounter(window_size_seconds=10)
    timestamps = [1000, 1003, 1005, 1012, 1015, 1025]

    for ts in timestamps:
        counter.add_event(ts)

    print("Count at t=1015:", counter.count(1015))
    print("Count at t=1025:", counter.count(1025))
    print("Count at t=1035:", counter.count(1035))

Output

stdout

Count at t=1015: 4
Count at t=1025: 3
Count at t=1035: 2

How it works

The TumblingWindowCounter uses a deque to store event timestamps. When count is called, it removes events older than the window size by checking the oldest timestamp against the current time. This ensures the deque always contains only events from the most recent fixed window. The len of the deque gives the aggregate count. The deque is efficient because popleft and append are O(1) operations.

Common mistakes

Assuming timestamps are in chronological order when adding events; if not, the deque won't hold a valid window.
Forgetting to call `count` to prune old events before using the internal deque directly.
Using a list instead of deque, which makes removal from the front O(n).
Off-by-one errors when comparing age: use `>=` to exclude events exactly at the window boundary.

Variations

Using `heapq` if events arrive out of order and you need to process them in timestamp order.
Using `time.time()` to get the current time automatically instead of passing it explicitly.

Real-world use cases

Counting requests per IP in a web server for rate limiting over a 10-second window.
Aggregating click events from a streaming analytics pipeline to show active users per minute.
Tracking error occurrences in a logging system to trigger alerts when a threshold is breached within a fixed window.

How to Implement a Tumbling Window Counter in Python

Python code

Output

How it works

Common mistakes

Variations

Real-world use cases

More from Streaming & messaging

Tutorials

Quizzes

Python code

Output

How it works

Common mistakes

Variations

Real-world use cases

More from Streaming & messaging

Keep learning

Tutorials

Quizzes