On Wed, Nov 22, 2017 at 9:22 PM, bunslow <bunslow@gmail.com> wrote:
Something *should* be object oriented with the functions in question all operate on the same data type, and in particular, those functions/verbs *are only well defined for that type*.

But here you are missing something that I think is important. These functions are valid on *any* data type that has the methods of a mutable sequence and has had heapq.heapify called on it. This is part of the brilliance of heapq.

Suppose we wanted to create a list-like data-type backed by a filesystem or database. I have done exactly such a thing like:

from collections import MutableSequence

class MyFileSystemList(MutableSequence): ...

data = MyFileSystemList('dir-path')

heapq.heapify(data)

heapq.heappush(data, 'text')

And it will work! The heap algorithm is exposed through a high-level functional interface so that you can take advantage of duck-typing. This is an important Python feature.

heapq.heappush(list-not-heap, item) is perfectly valid code in the current interface, but doesn't make any sense at all. And list.sort is *not* function based, it's an object oriented method. sorted() provides the same functionality for other types, given that it's a well defined function for a wide variety of sequences (unlike heappush). (list.sort is a method because unlike sorted(), it operates inplace, and is thus only meaningful for mutable, "complete" (all in memory, not "lazy") sequences -- i.e., a list.)

Personally, I find it irritating that list.sort will not similarly work until I inherit from list. I would prefer if it worked on mutable sequences. But regardless, if you inherit from "list", define all your own methods to store data in a file system, database, whatever then "list.sort" will work just fine as if it were a function:

class MyFileSystemList(list): ...  # Define methods to read/write from file system.

data = MyFileSystemList()

list.sort(data)

So it's not the case that list.sort is a method and must only be used as such. Rather, list.sort captures the algorithm known as sorting and works on any mutable sequence (with the unfortunate additional requirement that it inherits from list).

I've never used bisect, so I'll refrain from commenting on it.

At the end of the day, the patch proposed is merely a wrapper around the functional approach; you are welcome to continue using it as you like, it's not going anywhere. I would propose that the docs put the OOP version first though. 
 
On Wed, Nov 22, 2017 at 11:11 PM, Grant Jenks <grant.jenks@gmail.com> wrote:
Honestly, I don't see the value in a thin object-oriented wrapper around heapq functions. I'm a big -1 on the idea.

I'm the author of sortedcontainers (https://pypi.python.org/pypi/sortedcontainers/) so I interact with a lot of people using sorted collections types. My observations show folk's needs tend to fit a bimodal distribution. At one end are those who get by with list.sort, bisect, or heapq and they seem to appreciate the simple function-based approach those modules provide. At the other end are those who want a SortedList data type and we have some good options on PyPI and some good building-blocks in the standard library.

Personally, I think "sorted", "bisect" and "heapq" in the standard library are brilliant examples of the Python-way or "zen." I've learned a lot by studying their code and I encourage others to do the same. Just because something can be object-oriented doesn't mean it should be. There's a lot to be said for simplicity. I also think Nick's arguments are valid but I don't find them convincing.

What I think would be sufficient is a "See also:" blurb like that under https://docs.python.org/3/library/bisect.html#bisect.insort which also references SortedContainers at http://www.grantjenks.com/docs/sortedcontainers/ and the same blurb on heapq. I think that would be a reasonable next-step before we include any new data type in the standard library.

Grant