![image.png](https://files.peakd.com/file/peakd-hive/makerhacks/AKSdibpqEJhtvAiBQtJqttprRMmzB74dmKfV3NS5B7yY8ptGjn84eAgyoq18bcN.png)


Sometimes the right tool makes all the difference. I was building a Python script that hit API rate limits a bit too often. Not because I was doing anything wild, but because checking and managing timestamps of previous API calls started to slow things down.

The culprit? A regular Python list.  

The fix? A simple but powerful data structure called `deque` (pronounced *“deck”*).

If you’re dealing with queues, rate limits, or just need to add/remove items from both ends of a list quickly, this little built-in feature might be exactly what you need.


## What is `deque`?

`deque` stands for **Double-Ended Queue**. It lives in Python’s `collections` module, and you use it like this:

```python
from collections import deque
```

It works a lot like a list—but it’s built for speed, especially when you’re adding or removing items from **either end**.



## How is it different from a regular list?

Here’s the short version:

| Operation                     | List Time Complexity | `deque` Time Complexity |
|------------------------------|----------------------|--------------------------|
| `append()` (end)             | Fast (O(1))          | Fast (O(1))              |
| `pop()` (end)                | Fast (O(1))          | Fast (O(1))              |
| `insert(0, item)` (start)    | **Slow** (O(n))      | `appendleft()` = Fast (O(1)) |
| `pop(0)` (start)             | **Slow** (O(n))      | `popleft()` = Fast (O(1)) |

The difference is massive when you’re working with larger data, especially when you’re removing items from the front. Lists have to shift every other element to close the gap. `deque` just updates a pointer.



## Under the hood: Why is `deque` faster?

Python lists are dynamic arrays. They’re great at random access (getting item by index), but not so great at adding/removing items at the front. That’s because arrays need to keep elements in order in memory, so any time you insert at the front, everything else has to slide down one spot.

`deque`, on the other hand, is more like a chain of blocks (technically a doubly-linked list under the hood). Adding or removing from either end is a matter of updating pointers—no shifting required.


## Rate Limiting with `deque`

Here’s what I was dealing with: I needed to track the **timestamps of recent API calls**—say, only the ones made in the last 60 seconds.

That means:

- Every time I make a call, I need to **add** the current time.
- Before making a call, I need to **remove** any timestamps older than 60 seconds.

This is a classic sliding window problem.

### Why `deque` works perfectly here:

```python
from collections import deque
from time import time

GEMINI_CALL_TIMESTAMPS = deque()

def can_make_call():
    now = time()
    
    # Remove old timestamps
    while GEMINI_CALL_TIMESTAMPS and now - GEMINI_CALL_TIMESTAMPS[0] > 60:
        GEMINI_CALL_TIMESTAMPS.popleft()  # O(1)
    
    # Check if under limit
    if len(GEMINI_CALL_TIMESTAMPS) < 10:
        GEMINI_CALL_TIMESTAMPS.append(now)
        return True
    else:
        return False
```

If I’d used a list here and called `pop(0)` instead of `popleft()`, the cleanup step would get slower the more timestamps there were—because lists shift everything after the first item. That’s a performance hit you *feel* when you're doing this frequently.



## size limits with `maxlen`

You can also give your `deque` a fixed size like this:

```python
history = deque(maxlen=100)
```

Now, when it’s full and you add a new item, it automatically drops one from the other end. Great for logs, recent history, or metrics.



## TL;DR

If you need fast operations at **both ends** of a sequence, `deque` is your friend. 

It’s especially handy when:

- You’re implementing a **queue** or **stack**.
- You want a **sliding window** of data.
- You need to regularly remove the oldest items from a growing collection.

In my case, switching to `deque` made my rate limiter clean, fast, and reliable—no more slowdowns from shifting long lists.

It’s a small change, but it made a big difference.