{ "componentChunkName": "component---src-templates-post-js", "path": "/python-heap/", "result": {"data":{"markdownRemark":{"html":"

Implementing a Heap in Python

\n

In this post, we're going to implement a heap data structure from scratch in Python.

\n

Along the way, we'll learn why heaps are useful, how they are represented internally, and how Python's heapq module works under the hood.

\n

We'll also leverage the Python Data Model to make our implementation behave like a native Python collection.

\n

PREREQUISITES

\n\n

Goals

\n\n
\n

What is a Heap?

\n

A heap is a specialized tree-based data structure that satisfies the Heap Property.

\n

In a Min Heap, every parent node is smaller than or equal to its children.

\n
        2\n      /   \\\n     4     5\n    / \\   /\n   8  10 7
\n

Notice that:

\n
2 <= 4, 5\n4 <= 8, 10\n5 <= 7
\n

The smallest element is always at the root.

\n

This allows heaps to efficiently support operations like:

\n\n
\n

A Heap is Actually Just a List

\n

While heaps are typically drawn as trees, most implementations store them inside an array.

\n

For example:

\n
        2\n      /   \\\n     4     5\n    / \\   /\n   8  10 7
\n

Can be stored as:

\n
[2, 4, 5, 8, 10, 7]
\n

This works because the position of every node determines the position of its children.

\n

For a node at index i:

\n
left_child  = 2 * i + 1\nright_child = 2 * i + 2\nparent      = (i - 1) // 2
\n

Let's visualize that.

\n
graph TD\n A[\"0 : 2\"]\n B[\"1 : 4\"]\n C[\"2 : 5\"]\n D[\"3 : 8\"]\n E[\"4 : 10\"]\n F[\"5 : 7\"]\n\n A --> B\n A --> C\n B --> D\n B --> E\n C --> F
\n

Pretty neat.

\n

No node objects required.

\n
\n

The Heap Class

\n

Let's create a simple heap.

\n
class Heap:\n\n    def __init__(self):\n        self.data = []
\n

Creating a heap:

\n
>>> h = Heap()\n>>> h.data\n[]
\n

Nothing exciting yet.

\n

Let's start inserting values.

\n
\n

Inserting Values

\n

Suppose we insert:

\n
10
\n

The heap becomes:

\n
[10]
\n

Easy enough.

\n

Now let's insert:

\n
5
\n

Our array becomes:

\n
[10, 5]
\n

But there's a problem.

\n
10\n/\n5
\n

The heap property has been violated.

\n

The parent is larger than the child.

\n

We need to fix it.

\n
\n

Bubble Up

\n

When a new element is inserted, we place it at the end of the array and repeatedly swap it with its parent until the heap property is restored.

\n

This process is called Bubble Up (sometimes called Sift Up).

\n
graph TD\n A[\"10\"]\n B[\"5\"]\n\n A --> B
\n

Swap:

\n
graph TD\n A[\"5\"]\n B[\"10\"]\n\n A --> B
\n

The result:

\n
[5, 10]
\n

Let's implement it.

\n
def _bubble_up(self, index):\n\n    while index > 0:\n\n        parent = (index - 1) // 2\n\n        if self.data[index] < self.data[parent]:\n\n            self.data[index], self.data[parent] = (\n                self        self.data[index]\n            )\n\n            index = parent\n\n        else:\n            break
\n

Now insertion becomes:

\n
def push(self, value):\n\n    self.data.append(value)\n    self._bubble_up(len(self.data) - 1)
\n

Let's test it.

\n
>>> h.push(10)\n>>> h.push(5)\n>>> h.push(20)\n\n>>> h.data\n\n[5, 10, 20]
\n

Much better.

\n
\n

Building a Heap

\n

Let's insert several values.

\n
>>> h.push(15)\n>>> h.push(5)\n>>> h.push(3)\n>>> h.push(20)\n>>> h.push(7)\n>>> h.push(12)
\n

The resulting heap looks like:

\n
graph TD\n A[\"3\"]\n B[\"7\"]\n C[\"5\"]\n D[\"20\"]\n E[\"15\"]\n F[\"12\"]\n\n A --> B\n A --> C\n B --> D\n B --> E\n C --> F
\n

Notice that the smallest value naturally rises to the top.

\n
\n

Finding the Minimum

\n

This is the easiest heap operation.

\n

The minimum element is always:

\n
self.data[0]
\n

Let's expose that.

\n
def peek(self):\n\n    return self.data[0]
\n

Now:

\n
>>> h.peek()\n3
\n

Constant time.

\n

No searching required.

\n
\n

Removing the Minimum

\n

Here's where things get interesting.

\n

Suppose we remove:

\n
3
\n

from this heap:

\n
graph TD\n A[\"3\"]\n B[\"7\"]\n C[\"5\"]\n D[\"20\"]\n E[\"15\"]\n F[\"12\"]\n\n A --> B\n A --> C\n B --> D\n B --> E\n C --> F
\n

The last element takes the root position:

\n
graph TD\n A[\"12\"]\n B[\"7\"]\n C[\"5\"]\n D[\"20\"]\n E[\"15\"]\n\n A --> B\n A --> C\n B --> D\n B --> E
\n

Now the heap property is broken.

\n

We need another balancing operation.

\n
\n

Bubble Down

\n

This time we repeatedly swap the root with its smaller child.

\n
12\n/ \\\n7  5
\n

The smaller child is:

\n
5
\n

Swap them.

\n
5\n/ \\\n7 12
\n

Heap property restored.

\n

Let's implement that.

\n
def _bubble_down(self, index):\n\n    size = len(self.data)\n\n    while True:\n\n        smallest = index\n\n        left = 2 * index + 1\n        right = 2 * index + 2\n\n        if (\n            left < size and\n            self.data[left] < self.data[smallest]\n        ):\n            smallest = left\n\n        if (\n            right < size and\n            self.data[right] < self.data[smallest]\n        ):\n            smallest = right\n\n        if smallest == index:\n            break\n\n        self.data[index], self.data[smallest] = (\n            self.data[smallest],\n            self.data[index]\n        )\n\n        index = smallest
\n
\n

Implementing Pop

\n

Now we can remove the smallest value.

\n
def pop(self):\n\n    if not self.data:\n        raise IndexError(\"Heap is empty\")\n\n    minimum = self.data[0]\n\n    last = self.data.pop()\n\n    if self.data:\n        self.data[0] = last\n        self._bubble_down(0)\n\n    return minimum
\n

Let's try it.

\n
>>> h.pop()\n3\n\n>>> h.pop()\n5\n\n>>> h.pop()\n7
\n

Interesting.

\n

The values are coming out in sorted order.

\n
\n

Why Does Heap Sort Work?

\n

Let's repeatedly remove elements.

\n
>>> values = []\n\n>>> while len(h):\n...     values.append(h.pop())\n\n>>> values\n\n[3, 5, 7, 12, 15, 20]
\n

We accidentally discovered Heap Sort.

\n

The heap is continuously maintaining the smallest element at the root.

\n

Every removal gives us the next smallest value.

\n
\n

Implementing __len__

\n

Just like our Linked List implementation, we can integrate with Python's built-in functions.

\n
def __len__(self):\n    return len(self.data)
\n

Now:

\n
>>> len(h)\n6
\n

Very Pythonic.

\n
\n

Implementing __contains__

\n
def __contains__(self, value):\n    return value in self.data
\n

Now:

\n
>>> 15 in h\nTrue\n\n>>> 99 in h\nFalse
\n
\n

Implementing __iter__

\n

Let's allow iteration.

\n
def __iter__(self):\n    yield from self.data
\n

Now:

\n
>>> for value in h:\n...     print(value)
\n

works exactly as expected.

\n
\n

Priority Queues

\n

One of the most common uses of a heap is a priority queue.

\n

Suppose we have tasks:

\n
(1, \"Production Outage\")\n(2, \"Customer Escalation\")\n(5, \"Update Documentation\")
\n

Smaller numbers indicate higher priority.

\n

We push them into the heap.

\n
heap.push((1, \"Production Outage\"))\nheap.push((2, \"Customer Escalation\"))\nheap.push((5, \"Update Documentation\"))
\n

Removing elements gives:

\n
>>> heap.pop()\n\n(1, \"Production Outage\")
\n

The most important task always comes first.

\n

This pattern appears everywhere:

\n\n
\n

How Python's heapq Works

\n

Python's built-in implementation uses exactly the same ideas.

\n
import heapq\n\nnumbers = []\n\nheapq.heappush(numbers, 10)\nheapq.heappush(numbers, 5)\nheapq.heappush(numbers, 20)
\n

The smallest element remains at the front.

\n
>>> heapq.heappop(numbers)\n\n5
\n

No magic involved.

\n

Just clever use of arrays and a couple of balancing operations.

\n
\n

Time Complexity

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OperationComplexity
PeekO(1)
InsertO(log n)
Remove MinO(log n)
SearchO(n)
Build HeapO(n)
\n

The logarithmic insert and removal operations make heaps ideal for priority queues.

\n
\n

Conclusion

\n

At this point we've implemented:

\n
push()\npop()\npeek()\n__len__()\n__contains__()\n__iter__()
\n

All while storing the heap inside a simple Python list.

\n

The real lesson isn't just building a heap.

\n

It's understanding how a relatively simple structure can support efficient operations that power real-world systems like task schedulers, graph algorithms, and operating systems.

\n

Once you understand:

\n
Bubble Up\nBubble Down\nParent Index\nChild Index
\n

the entire heap data structure becomes surprisingly straightforward.

\n

That's it folks!

","excerpt":"Implementing a Heap in Python In this post, we're going to implement a heap data structure from scratch in Python. Along the way, we'll…","fields":{"slug":"/python-heap/"},"frontmatter":{"title":"Heap in Python","date":"November 23, 2025","tags":["Python"],"categories":["Highlight","Python"],"description":"Implement a heap in Python","comments_off":false,"thumbnail":{"childImageSharp":{"fixed":{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAYAAACNiR0NAAAACXBIWXMAAAsTAAALEwEAmpwYAAADTElEQVQ4y62U32tbZRjH80fojXZbfpyTnPP+OEnTJEu7xDQN6ZqWtGnSNs7ClMwfeDMojrmCMKWbU1ejsyqj6uKFRYUhTLyqUGcZXggDQZzghaAXFvSiigxU3D6SkzSkth0qXjy87/O8vN/n99ejlKIjUiKldO+GEHhtG59td2xb553E0600P2ilMIXggXiMy/kcT6cOufZ/ArYDsAkWkpJ02OG7UhGqU9yqVjgxkMRnC5z/AmhIScHR/FLI81OpyJ/jY5xPxPCKfwG4lY7WLVBLSurRCBu5DGv9CdJSYimF036/U/qe7oJbQYGSCqkVAcvitTPPMXK4gM80CTsaMyixbOk63gvUjdC2Wo8DQxG0o5CiKYK33n6HyXIF0zAJWZrhrGYgqTBMuWekHikkkajm+OtZzl8bZW55CB2x2dezj0tvNhgbLXDX3fey+FQvf3wVY+OzPmYrTgt0l0g9IUOQr/Zx4foY9WtFXvw8z9mLT3BxqcHVT9ZZWbnMhcVn+e3LNLe/icHGQT6+FGG/VxJ2dklZWJLEoGbuvRSnVzPMvT/AxOwwM5UjlMtlZqarlCZKfLEShRsKbjgsPak54Jc4zh41tEKCzHicU8sPki0nCPhN/AE/hhEgaATw+UwGkxafNkosnx5ECQutdGeMutNuNcW26XMiLL3wCvFwL3Zz5hwHqTV+KTG0oscb4JmFl7l/9hHu8fpcu1+IbVvWAtQaO2iQqdSYf/c62ZnHXF0oTa9SLKRT1LMZek2Dev0ljtZqFGyLN3JDPJ48SFD8rSkiZBLPjXPsys/UVuHhj27SPzLNAcPnfqJagZkKV/I5Xl1u8PzJeb4eybtreXN6kloiTqBrizzC9BGfPs7RVXj0w00eWoP+Iyfw+nq4mh3k96kSm6Ui309OcPbcIo2T8/w6dpgfpya5VSqykIixXwjCnRpKgYz0kT6zxugHt0mfW8eJJjGEzbGww7epJD+k+zkVcfBaFsq2WYlH2cwcYj0Z5772quptu2yHkNpBp0dRTtjVm3ZTSlJKkVWKYPuT3W7AsFJElXTZaVtTWhfdIteQQTPipr7FjSHZojTdzZttZ0LtJAvP9jnSHW+yi9J012h0mGmXGdzBh/+H/AU0ybul6zgNGwAAAABJRU5ErkJggg==","width":150,"height":150,"src":"/static/2f09907c40dc42fcfb059056336ea5ad/92ab1/heap.png","srcSet":"/static/2f09907c40dc42fcfb059056336ea5ad/92ab1/heap.png 1x,\n/static/2f09907c40dc42fcfb059056336ea5ad/668a7/heap.png 1.5x,\n/static/2f09907c40dc42fcfb059056336ea5ad/56e34/heap.png 2x"}}}}}},"pageContext":{"slug":"/python-heap/","previous":{"id":"087dbd34-3805-535e-8065-c7821b1a37da","frontmatter":{"title":"Python Idioms","tags":["Python"],"categories":["Highlight","Python"],"template":"post"},"fields":{"slug":"/python-idioms/"}},"next":{"id":"b2df600b-944a-5bb9-86ed-3118b169f6ba","frontmatter":{"title":"Graphs in Python","tags":["Python"],"categories":["Highlight","Python"],"template":"post"},"fields":{"slug":"/python-graphs/"}}}}, "staticQueryHashes": []}