Skip to content

Add MinHeap and MaxHeap classes to heapq (object-oriented interface) #153357

Closed as duplicate

Description

@facundobatista

Feature or enhancement

Proposal:

Add two classes, MinHeap and MaxHeap, to the heapq module, providing an object-oriented interface on top of the existing functions.

Today heapq exposes only module-level functions that operate on a bare list that the caller has to create and pass around on every call:

import heapq

heap = []
heapq.heappush(heap, 3)
heapq.heappush(heap, 1)
smallest = heapq.heappop(heap)

This works, but it is easy to misuse: nothing ties the list to the heap invariant, an ordinary list method can silently break it, and the caller must remember to always go through heapq. An object that owns its data and exposes the operations as methods is a more natural, discoverable interface:

from heapq import MinHeap

heap = MinHeap([3, 1, 2])
heap.push(0)
smallest = heap.pop()

Proposed API: Two classes that share the same interface (only the direction of the ordering differs):

  • MinHeap(iterable=None) / MaxHeap(iterable=None): create a heap, optionally initialized from an iterable
  • push(item) / pop() / etc.: mimic the interface of the module's functions
  • __len__, __bool__, __repr__: special methods to make the object Pythonic

Has this already been discussed elsewhere?

I have already discussed this feature proposal on Discourse

Links to previous discussion of this feature:

The idea of an object-oriented wrapper for heapq was originally proposed on python-ideas back in 2009. At the time the module only offered a min-heap, but the idea is extensible. The topic came up again recently on Discourse, in the context of sorted priority-queue data structures in the standard library.

Linked PRs

Activity

  1. added
    stdlibStandard Library Python modules in the Lib/ directory
    on Jul 8, 2026
  2. Twix1288 commented on Jul 8, 2026

    @Twix1288
    Contributor

    I would love to take a look at it, happy to send a PR as soon as see it through

  3. rhettinger commented on Jul 10, 2026

    @rhettinger
    Contributor

    -1 for this. It provides almost nothing in the way of new functionality and goes against the original design decision to not roll these is classes. The concept is that a heap isn't an object; rather, it is just a particular arrangement of a list just like sorting.

  4. jonathandung commented on Jul 11, 2026

    @jonathandung
    Contributor

    #62034, #143326, dpo thread, Reddit discussion, This functionality in boltons if you really want it. Should be sufficient cause to have this closed as dup/not planned

  5. facundobatista commented on Jul 14, 2026

    @facundobatista
    MemberAuthor

    Indeed

  6. jsbueno commented on Jul 16, 2026

    @jsbueno
    Contributor

    @rhettinger : sorry - I'd disagree that these "original design decision" is still valid today. TLDR: the wrapper becomes non trivial at a certain point, and is needless friction when coding - the "book definition" of "unpythonic" if we can say so.

    Also, "it adds no value" is really a subjective argument, as it will add value for a whole public category.

    So, if you haven't I'd invite you to take a look at the discourse thread, and at least acknowledge you are aware of that, before dismissing this based on 20+ year old context - https://discuss.python.org/t/sorted-data-structure-in-the-stdlib/107994

  7. facundobatista commented on Jul 16, 2026

    @facundobatista
    MemberAuthor

    FTR, this is the PR for this issue, to prove that the layer is simple and doesn't have really that much of a cost: #153821

  8. picnixz commented on Jul 17, 2026

    @picnixz
    Member

    @jsbueno Raymond is the maintainer of the heap module so his decision weighs more in general (at least implicitly). Even if people want to have an OO interface, it doesn't mean that we need to add one in the stdlib. I should say that I agree with:

    The concept is that a heap isn't an object;

    I should also mention that C++ doesn't consider heaps as objects and only provides functions on that: https://en.cppreference.com/cpp/algorithm/make_heap.

    So I would be rather -0.5 on this one. I acknowledge the possibility of misusing the API, but in this case, I don't think the stdlib should be responsible. There are other cases where we prefer trusting the users.

    Also, "it adds no value" is really a subjective argument, as it will add value for a whole public category.

    I agree here that it's subjective, but it also adds burden on maintainers just to maintain the code. What if someone wants to extends the API at some point "for convenience" reasons? that's usually a can of worms we don't want to open (that's also why we usually don't introduce that many new classes in the stdlib). If something really needs to be convenient, we usually leave it to 3rd party packages.

  9. jsbueno commented on Jul 17, 2026

    @jsbueno
    Contributor

    I should also mention that C++ doesn't consider heaps as objects and only provides functions on that: https://en.cppreference.com/cpp/algorithm/make_heap.

    Since this is Python, not C++, you argument sonds to me as in favor of making it easier to use. Who wants Python as hard to use as C++?

    And I am not saying Raymond doesn't have more weight here - I am just inviting him - as I do to you - to read the reasonings that showed up in the linked discourse thread.

    @facundobatista btw - may it is worth editing the first post here to include a link to that discourse thread - what do you say?

  10. facundobatista commented on Jul 17, 2026

    @facundobatista
    MemberAuthor

    @jsbueno it's already included in the "Links to previous discussion of this feature" section.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

stdlibStandard Library Python modules in the Lib/ directorytype-featureA feature request or enhancement

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions