Right, I agree compare_networks() is behaving correctly according to its original design. However:

- it was designed for Python 2, where cmp() style idioms were still more common. Those idioms have largely been removed in Python 3 (no cmp() builtin, no __cmp__ magic method, no cmp argument to list.sort() and sorted())

- it was designed for the ipaddr data model, where network equality comparisons are more like ipaddress.ip_interface comparisons than they ipaddress.ip_network comparisons

Since there isn't any real maintenance burden in keeping the code around, I'm flipping this to be purely a documentation issue and suggesting that we:

- mark the method as deprecated in the docs, but *not* in the code (using the method form is just kind of pointless, not actively harmful)

- update the docs to say that it uses the same ordering and comparison algorithm as "<", "==", and ">" (the current confusion stems from the fact that the algorithms were different in ipaddr, but in the stdlib that other algorithm is the one used by interface objects, not network objects)