Sort documentation could be improved for complex sorting

[FabriceSalvaire]

BPO	35956
Nosy	@rhettinger, @csabella, @FabriceSalvaire

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/rhettinger'
closed_at = <Date 2019-02-20.16:59:10.361>
created_at = <Date 2019-02-10.16:33:39.002>
labels = ['invalid', 'type-feature', '3.7', 'docs']
title = 'Sort documentation could be improved for complex sorting'
updated_at = <Date 2019-02-20.16:59:10.360>
user = 'https://github.com/FabriceSalvaire'

bugs.python.org fields:

activity = <Date 2019-02-20.16:59:10.360>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2019-02-20.16:59:10.361>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2019-02-10.16:33:39.002>
creator = 'FabriceSalvaire'
dependencies = []
files = []
hgrepos = []
issue_num = 35956
keywords = []
message_count = 4.0
messages = ['335163', '335164', '335167', '335187']
nosy_count = 5.0
nosy_names = ['rhettinger', 'SilentGhost', 'docs@python', 'cheryl.sabella', 'FabriceSalvaire']
pr_nums = []
priority = 'normal'
resolution = 'not a bug'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue35956'
versions = ['Python 3.7']

[FabriceSalvaire]

I just implemented Graham Scan algorithm in Python 3 and have to read carefully the sort documentation. Notice this is a good algorithm for a large audience language like Python.

Since Python 3, the old order function cmp is depicted as an old way to proceed.

But some sorting procedure require complex order like this

    def sort_by_y(p0, p1):
        return p0.x - p1.x if (p0.y == p1.y) else p0.y - p1.y
    sorted(points, key=cmp_to_key(sort_by_y))

which is less natural to implement than

    def sort_by_y(p0, p1):
        return p0.x < p1.x if (p0.y == p1.y) else p0.y < p1.y
    sorted(points, cmp=sort_by_y)

Since Python 3 we should do this

    points.sort(key=attrgetter('x'))
    points.sort(key=attrgetter('y'))

But we must take care to the chaining order !!! Here we must sort first on x then on y.

I think the documentation could explain much better how to perform complex sort and the performance of the Python sort algorithm. Is the old way faster than the new one ??? What about short and large array ??? What happen when we sort a zillion of short array ???

[SilentGhost]

Is this not equivalent to the following?

  sorted(points, key=lambda p: (p.y, p.x))

[csabella]

Take a look at bpo-35020 which discusses multisort.

[rhettinger]

It seems to me that the sorting howto covers this topic.

If I'm reading the OP's task correctly, it isn't complex at all:

   points.sort(key=attrgetter('x', 'y'))  # x is primary key; y is secondary