<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Sorting HOW TO — Python v2.7.1 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '2.7.1',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python v2.7.1 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Python v2.7.1 documentation" href="../index.html" />
<link rel="up" title="Python HOWTOs" href="index.html" />
<link rel="next" title="Unicode HOWTO" href="unicode.html" />
<link rel="prev" title="Socket Programming HOWTO" href="sockets.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../modindex.html" title="Global Module Index"
accesskey="M">modules</a> |</li>
<li class="right" >
<a href="unicode.html" title="Unicode HOWTO"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="sockets.html" title="Socket Programming HOWTO"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="../index.html">Python v2.7.1 documentation</a> »</li>
<li><a href="index.html" accesskey="U">Python HOWTOs</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="sorting-how-to">
<span id="sortinghowto"></span><h1>Sorting HOW TO<a class="headerlink" href="#sorting-how-to" title="Permalink to this headline">¶</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Andrew Dalke and Raymond Hettinger</td>
</tr>
<tr class="field"><th class="field-name">Release:</th><td class="field-body">0.1</td>
</tr>
</tbody>
</table>
<p>Python lists have a built-in <tt class="xref docutils literal"><span class="pre">list.sort()</span></tt> method that modifies the list
in-place and a <a title="sorted" class="reference external" href="../library/functions.html#sorted"><tt class="xref docutils literal"><span class="pre">sorted()</span></tt></a> built-in function that builds a new sorted list
from an iterable.</p>
<p>In this document, we explore the various techniques for sorting data using Python.</p>
<div class="section" id="sorting-basics">
<h2>Sorting Basics<a class="headerlink" href="#sorting-basics" title="Permalink to this headline">¶</a></h2>
<p>A simple ascending sort is very easy: just call the <a title="sorted" class="reference external" href="../library/functions.html#sorted"><tt class="xref docutils literal"><span class="pre">sorted()</span></tt></a> function. It
returns a new sorted list:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nb">sorted</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">4</span><span class="p">])</span>
<span class="go">[1, 2, 3, 4, 5]</span>
</pre></div>
</div>
<p>You can also use the <tt class="xref docutils literal"><span class="pre">list.sort()</span></tt> method of a list. It modifies the list
in-place (and returns <em>None</em> to avoid confusion). Usually it’s less convenient
than <a title="sorted" class="reference external" href="../library/functions.html#sorted"><tt class="xref docutils literal"><span class="pre">sorted()</span></tt></a> - but if you don’t need the original list, it’s slightly
more efficient.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="p">[</span><span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">4</span><span class="p">]</span>
<span class="gp">>>> </span><span class="n">a</span><span class="o">.</span><span class="n">sort</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">a</span>
<span class="go">[1, 2, 3, 4, 5]</span>
</pre></div>
</div>
<p>Another difference is that the <tt class="xref docutils literal"><span class="pre">list.sort()</span></tt> method is only defined for
lists. In contrast, the <a title="sorted" class="reference external" href="../library/functions.html#sorted"><tt class="xref docutils literal"><span class="pre">sorted()</span></tt></a> function accepts any iterable.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nb">sorted</span><span class="p">({</span><span class="mi">1</span><span class="p">:</span> <span class="s">'D'</span><span class="p">,</span> <span class="mi">2</span><span class="p">:</span> <span class="s">'B'</span><span class="p">,</span> <span class="mi">3</span><span class="p">:</span> <span class="s">'B'</span><span class="p">,</span> <span class="mi">4</span><span class="p">:</span> <span class="s">'E'</span><span class="p">,</span> <span class="mi">5</span><span class="p">:</span> <span class="s">'A'</span><span class="p">})</span>
<span class="go">[1, 2, 3, 4, 5]</span>
</pre></div>
</div>
</div>
<div class="section" id="key-functions">
<h2>Key Functions<a class="headerlink" href="#key-functions" title="Permalink to this headline">¶</a></h2>
<p>Starting with Python 2.4, both <tt class="xref docutils literal"><span class="pre">list.sort()</span></tt> and <a title="sorted" class="reference external" href="../library/functions.html#sorted"><tt class="xref docutils literal"><span class="pre">sorted()</span></tt></a> added a
<em>key</em> parameter to specify a function to be called on each list element prior to
making comparisons.</p>
<p>For example, here’s a case-insensitive string comparison:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nb">sorted</span><span class="p">(</span><span class="s">"This is a test string from Andrew"</span><span class="o">.</span><span class="n">split</span><span class="p">(),</span> <span class="n">key</span><span class="o">=</span><span class="nb">str</span><span class="o">.</span><span class="n">lower</span><span class="p">)</span>
<span class="go">['a', 'Andrew', 'from', 'is', 'string', 'test', 'This']</span>
</pre></div>
</div>
<p>The value of the <em>key</em> parameter should be a function that takes a single argument
and returns a key to use for sorting purposes. This technique is fast because
the key function is called exactly once for each input record.</p>
<p>A common pattern is to sort complex objects using some of the object’s indices
as keys. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">student_tuples</span> <span class="o">=</span> <span class="p">[</span>
<span class="go"> ('john', 'A', 15),</span>
<span class="go"> ('jane', 'B', 12),</span>
<span class="go"> ('dave', 'B', 10),</span>
<span class="go">]</span>
<span class="gp">>>> </span><span class="nb">sorted</span><span class="p">(</span><span class="n">student_tuples</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">student</span><span class="p">:</span> <span class="n">student</span><span class="p">[</span><span class="mi">2</span><span class="p">])</span> <span class="c"># sort by age</span>
<span class="go">[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]</span>
</pre></div>
</div>
<p>The same technique works for objects with named attributes. For example:</p>
<blockquote>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">Student</span><span class="p">:</span>
<span class="go"> def __init__(self, name, grade, age):</span>
<span class="go"> self.name = name</span>
<span class="go"> self.grade = grade</span>
<span class="go"> self.age = age</span>
<span class="go"> def __repr__(self):</span>
<span class="go"> return repr((self.name, self.grade, self.age))</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">student_objects</span> <span class="o">=</span> <span class="p">[</span>
<span class="go"> Student('john', 'A', 15),</span>
<span class="go"> Student('jane', 'B', 12),</span>
<span class="go"> Student('dave', 'B', 10),</span>
<span class="go">]</span>
<span class="gp">>>> </span><span class="nb">sorted</span><span class="p">(</span><span class="n">student_objects</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">student</span><span class="p">:</span> <span class="n">student</span><span class="o">.</span><span class="n">age</span><span class="p">)</span> <span class="c"># sort by age</span>
<span class="go">[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]</span>
</pre></div>
</div>
</blockquote>
</div>
<div class="section" id="operator-module-functions">
<h2>Operator Module Functions<a class="headerlink" href="#operator-module-functions" title="Permalink to this headline">¶</a></h2>
<p>The key-function patterns shown above are very common, so Python provides
convenience functions to make accessor functions easier and faster. The operator
module has <a title="operator.itemgetter" class="reference external" href="../library/operator.html#operator.itemgetter"><tt class="xref docutils literal"><span class="pre">operator.itemgetter()</span></tt></a>, <a title="operator.attrgetter" class="reference external" href="../library/operator.html#operator.attrgetter"><tt class="xref docutils literal"><span class="pre">operator.attrgetter()</span></tt></a>, and
starting in Python 2.5 a <a title="operator.methodcaller" class="reference external" href="../library/operator.html#operator.methodcaller"><tt class="xref docutils literal"><span class="pre">operator.methodcaller()</span></tt></a> function.</p>
<p>Using those functions, the above examples become simpler and faster:</p>
<blockquote>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">operator</span> <span class="kn">import</span> <span class="n">itemgetter</span><span class="p">,</span> <span class="n">attrgetter</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nb">sorted</span><span class="p">(</span><span class="n">student_tuples</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">itemgetter</span><span class="p">(</span><span class="mi">2</span><span class="p">))</span>
<span class="go">[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nb">sorted</span><span class="p">(</span><span class="n">student_objects</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">attrgetter</span><span class="p">(</span><span class="s">'age'</span><span class="p">))</span>
<span class="go">[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]</span>
</pre></div>
</div>
</blockquote>
<p>The operator module functions allow multiple levels of sorting. For example, to
sort by <em>grade</em> then by <em>age</em>:</p>
<blockquote>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nb">sorted</span><span class="p">(</span><span class="n">student_tuples</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">itemgetter</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">))</span>
<span class="go">[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nb">sorted</span><span class="p">(</span><span class="n">student_objects</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">attrgetter</span><span class="p">(</span><span class="s">'grade'</span><span class="p">,</span> <span class="s">'age'</span><span class="p">))</span>
<span class="go">[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]</span>
</pre></div>
</div>
</blockquote>
</div>
<div class="section" id="ascending-and-descending">
<h2>Ascending and Descending<a class="headerlink" href="#ascending-and-descending" title="Permalink to this headline">¶</a></h2>
<p>Both <tt class="xref docutils literal"><span class="pre">list.sort()</span></tt> and <a title="sorted" class="reference external" href="../library/functions.html#sorted"><tt class="xref docutils literal"><span class="pre">sorted()</span></tt></a> accept a <em>reverse</em> parameter with a
boolean value. This is using to flag descending sorts. For example, to get the
student data in reverse <em>age</em> order:</p>
<blockquote>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nb">sorted</span><span class="p">(</span><span class="n">student_tuples</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">itemgetter</span><span class="p">(</span><span class="mi">2</span><span class="p">),</span> <span class="n">reverse</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="go">[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nb">sorted</span><span class="p">(</span><span class="n">student_objects</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">attrgetter</span><span class="p">(</span><span class="s">'age'</span><span class="p">),</span> <span class="n">reverse</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="go">[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]</span>
</pre></div>
</div>
</blockquote>
</div>
<div class="section" id="sort-stability-and-complex-sorts">
<h2>Sort Stability and Complex Sorts<a class="headerlink" href="#sort-stability-and-complex-sorts" title="Permalink to this headline">¶</a></h2>
<p>Starting with Python 2.2, sorts are guaranteed to be <a class="reference external" href="http://en.wikipedia.org/wiki/Sorting_algorithm#Stability">stable</a>. That means that
when multiple records have the same key, their original order is preserved.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">[(</span><span class="s">'red'</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="s">'blue'</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="s">'red'</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="s">'blue'</span><span class="p">,</span> <span class="mi">2</span><span class="p">)]</span>
<span class="gp">>>> </span><span class="nb">sorted</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">itemgetter</span><span class="p">(</span><span class="mi">0</span><span class="p">))</span>
<span class="go">[('blue', 1), ('blue', 2), ('red', 1), ('red', 2)]</span>
</pre></div>
</div>
<p>Notice how the two records for <em>blue</em> retain their original order so that
<tt class="docutils literal"><span class="pre">('blue',</span> <span class="pre">1)</span></tt> is guaranteed to precede <tt class="docutils literal"><span class="pre">('blue',</span> <span class="pre">2)</span></tt>.</p>
<p>This wonderful property lets you build complex sorts in a series of sorting
steps. For example, to sort the student data by descending <em>grade</em> and then
ascending <em>age</em>, do the <em>age</em> sort first and then sort again using <em>grade</em>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">s</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">student_objects</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">attrgetter</span><span class="p">(</span><span class="s">'age'</span><span class="p">))</span> <span class="c"># sort on secondary key</span>
<span class="gp">>>> </span><span class="nb">sorted</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">attrgetter</span><span class="p">(</span><span class="s">'grade'</span><span class="p">),</span> <span class="n">reverse</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> <span class="c"># now sort on primary key, descending</span>
<span class="go">[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]</span>
</pre></div>
</div>
<p>The <a class="reference external" href="http://en.wikipedia.org/wiki/Timsort">Timsort</a> algorithm used in Python
does multiple sorts efficiently because it can take advantage of any ordering
already present in a dataset.</p>
</div>
<div class="section" id="the-old-way-using-decorate-sort-undecorate">
<h2>The Old Way Using Decorate-Sort-Undecorate<a class="headerlink" href="#the-old-way-using-decorate-sort-undecorate" title="Permalink to this headline">¶</a></h2>
<p>This idiom is called Decorate-Sort-Undecorate after its three steps:</p>
<ul class="simple">
<li>First, the initial list is decorated with new values that control the sort order.</li>
<li>Second, the decorated list is sorted.</li>
<li>Finally, the decorations are removed, creating a list that contains only the
initial values in the new order.</li>
</ul>
<p>For example, to sort the student data by <em>grade</em> using the DSU approach:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">decorated</span> <span class="o">=</span> <span class="p">[(</span><span class="n">student</span><span class="o">.</span><span class="n">grade</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">student</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">student</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">student_objects</span><span class="p">)]</span>
<span class="gp">>>> </span><span class="n">decorated</span><span class="o">.</span><span class="n">sort</span><span class="p">()</span>
<span class="gp">>>> </span><span class="p">[</span><span class="n">student</span> <span class="k">for</span> <span class="n">grade</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">student</span> <span class="ow">in</span> <span class="n">decorated</span><span class="p">]</span> <span class="c"># undecorate</span>
<span class="go">[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]</span>
</pre></div>
</div>
<p>This idiom works because tuples are compared lexicographically; the first items
are compared; if they are the same then the second items are compared, and so
on.</p>
<p>It is not strictly necessary in all cases to include the index <em>i</em> in the
decorated list, but including it gives two benefits:</p>
<ul class="simple">
<li>The sort is stable – if two items have the same key, their order will be
preserved in the sorted list.</li>
<li>The original items do not have to be comparable because the ordering of the
decorated tuples will be determined by at most the first two items. So for
example the original list could contain complex numbers which cannot be sorted
directly.</li>
</ul>
<p>Another name for this idiom is
<a class="reference external" href="http://en.wikipedia.org/wiki/Schwartzian_transform">Schwartzian transform</a>,
after Randal L. Schwartz, who popularized it among Perl programmers.</p>
<p>For large lists and lists where the comparison information is expensive to
calculate, and Python versions before 2.4, DSU is likely to be the fastest way
to sort the list. For 2.4 and later, key functions provide the same
functionality.</p>
</div>
<div class="section" id="the-old-way-using-the-cmp-parameter">
<h2>The Old Way Using the <em>cmp</em> Parameter<a class="headerlink" href="#the-old-way-using-the-cmp-parameter" title="Permalink to this headline">¶</a></h2>
<p>Many constructs given in this HOWTO assume Python 2.4 or later. Before that,
there was no <a title="sorted" class="reference external" href="../library/functions.html#sorted"><tt class="xref docutils literal"><span class="pre">sorted()</span></tt></a> builtin and <tt class="xref docutils literal"><span class="pre">list.sort()</span></tt> took no keyword
arguments. Instead, all of the Py2.x versions supported a <em>cmp</em> parameter to
handle user specified comparison functions.</p>
<p>In Py3.0, the <em>cmp</em> parameter was removed entirely (as part of a larger effort to
simplify and unify the language, eliminating the conflict between rich
comparisons and the <a title="object.__cmp__" class="reference external" href="../reference/datamodel.html#object.__cmp__"><tt class="xref docutils literal"><span class="pre">__cmp__()</span></tt></a> magic method).</p>
<p>In Py2.x, sort allowed an optional function which can be called for doing the
comparisons. That function should take two arguments to be compared and then
return a negative value for less-than, return zero if they are equal, or return
a positive value for greater-than. For example, we can do:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">def</span> <span class="nf">numeric_compare</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">):</span>
<span class="go"> return x - y</span>
<span class="gp">>>> </span><span class="nb">sorted</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="nb">cmp</span><span class="o">=</span><span class="n">numeric_compare</span><span class="p">)</span>
<span class="go">[1, 2, 3, 4, 5]</span>
</pre></div>
</div>
<p>Or you can reverse the order of comparison with:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">def</span> <span class="nf">reverse_numeric</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">):</span>
<span class="go"> return y - x</span>
<span class="gp">>>> </span><span class="nb">sorted</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="nb">cmp</span><span class="o">=</span><span class="n">reverse_numeric</span><span class="p">)</span>
<span class="go">[5, 4, 3, 2, 1]</span>
</pre></div>
</div>
<p>When porting code from Python 2.x to 3.x, the situation can arise when you have
the user supplying a comparison function and you need to convert that to a key
function. The following wrapper makes that easy to do:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">cmp_to_key</span><span class="p">(</span><span class="n">mycmp</span><span class="p">):</span>
<span class="s">'Convert a cmp= function into a key= function'</span>
<span class="k">class</span> <span class="nc">K</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">obj</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">obj</span> <span class="o">=</span> <span class="n">obj</span>
<span class="k">def</span> <span class="nf">__lt__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
<span class="k">return</span> <span class="n">mycmp</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">obj</span><span class="p">,</span> <span class="n">other</span><span class="o">.</span><span class="n">obj</span><span class="p">)</span> <span class="o"><</span> <span class="mi">0</span>
<span class="k">def</span> <span class="nf">__gt__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
<span class="k">return</span> <span class="n">mycmp</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">obj</span><span class="p">,</span> <span class="n">other</span><span class="o">.</span><span class="n">obj</span><span class="p">)</span> <span class="o">></span> <span class="mi">0</span>
<span class="k">def</span> <span class="nf">__eq__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
<span class="k">return</span> <span class="n">mycmp</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">obj</span><span class="p">,</span> <span class="n">other</span><span class="o">.</span><span class="n">obj</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span>
<span class="k">def</span> <span class="nf">__le__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
<span class="k">return</span> <span class="n">mycmp</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">obj</span><span class="p">,</span> <span class="n">other</span><span class="o">.</span><span class="n">obj</span><span class="p">)</span> <span class="o"><=</span> <span class="mi">0</span>
<span class="k">def</span> <span class="nf">__ge__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
<span class="k">return</span> <span class="n">mycmp</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">obj</span><span class="p">,</span> <span class="n">other</span><span class="o">.</span><span class="n">obj</span><span class="p">)</span> <span class="o">>=</span> <span class="mi">0</span>
<span class="k">def</span> <span class="nf">__ne__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
<span class="k">return</span> <span class="n">mycmp</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">obj</span><span class="p">,</span> <span class="n">other</span><span class="o">.</span><span class="n">obj</span><span class="p">)</span> <span class="o">!=</span> <span class="mi">0</span>
<span class="k">return</span> <span class="n">K</span>
</pre></div>
</div>
<p>To convert to a key function, just wrap the old comparison function:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nb">sorted</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">key</span><span class="o">=</span><span class="n">cmp_to_key</span><span class="p">(</span><span class="n">reverse_numeric</span><span class="p">))</span>
<span class="go">[5, 4, 3, 2, 1]</span>
</pre></div>
</div>
<p>In Python 2.7, the <a title="functools.cmp_to_key" class="reference external" href="../library/functools.html#functools.cmp_to_key"><tt class="xref docutils literal"><span class="pre">functools.cmp_to_key()</span></tt></a> function was added to the
functools module.</p>
</div>
<div class="section" id="odd-and-ends">
<h2>Odd and Ends<a class="headerlink" href="#odd-and-ends" title="Permalink to this headline">¶</a></h2>
<ul>
<li><p class="first">For locale aware sorting, use <a title="locale.strxfrm" class="reference external" href="../library/locale.html#locale.strxfrm"><tt class="xref docutils literal"><span class="pre">locale.strxfrm()</span></tt></a> for a key function or
<a title="locale.strcoll" class="reference external" href="../library/locale.html#locale.strcoll"><tt class="xref docutils literal"><span class="pre">locale.strcoll()</span></tt></a> for a comparison function.</p>
</li>
<li><p class="first">The <em>reverse</em> parameter still maintains sort stability (i.e. records with
equal keys retain the original order). Interestingly, that effect can be
simulated without the parameter by using the builtin <a title="reversed" class="reference external" href="../library/functions.html#reversed"><tt class="xref docutils literal"><span class="pre">reversed()</span></tt></a> function
twice:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="p">[(</span><span class="s">'red'</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="s">'blue'</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="s">'red'</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">(</span><span class="s">'blue'</span><span class="p">,</span> <span class="mi">2</span><span class="p">)]</span>
<span class="gp">>>> </span><span class="k">assert</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">reverse</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> <span class="o">==</span> <span class="nb">list</span><span class="p">(</span><span class="nb">reversed</span><span class="p">(</span><span class="nb">sorted</span><span class="p">(</span><span class="nb">reversed</span><span class="p">(</span><span class="n">data</span><span class="p">))))</span>
</pre></div>
</div>
</li>
<li><p class="first">The sort routines are guaranteed to use <a title="object.__lt__" class="reference external" href="../reference/datamodel.html#object.__lt__"><tt class="xref docutils literal"><span class="pre">__lt__()</span></tt></a> when making comparisons
between two objects. So, it is easy to add a standard sort order to a class by
defining an <a title="object.__lt__" class="reference external" href="../reference/datamodel.html#object.__lt__"><tt class="xref docutils literal"><span class="pre">__lt__()</span></tt></a> method:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">Student</span><span class="o">.</span><span class="n">__lt__</span> <span class="o">=</span> <span class="k">lambda</span> <span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">age</span> <span class="o"><</span> <span class="n">other</span><span class="o">.</span><span class="n">age</span>
<span class="gp">>>> </span><span class="nb">sorted</span><span class="p">(</span><span class="n">student_objects</span><span class="p">)</span>
<span class="go">[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]</span>
</pre></div>
</div>
</li>
<li><p class="first">Key functions need not depend directly on the objects being sorted. A key
function can also access external resources. For instance, if the student grades
are stored in a dictionary, they can be used to sort a separate list of student
names:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">students</span> <span class="o">=</span> <span class="p">[</span><span class="s">'dave'</span><span class="p">,</span> <span class="s">'john'</span><span class="p">,</span> <span class="s">'jane'</span><span class="p">]</span>
<span class="gp">>>> </span><span class="n">newgrades</span> <span class="o">=</span> <span class="p">{</span><span class="s">'john'</span><span class="p">:</span> <span class="s">'F'</span><span class="p">,</span> <span class="s">'jane'</span><span class="p">:</span><span class="s">'A'</span><span class="p">,</span> <span class="s">'dave'</span><span class="p">:</span> <span class="s">'C'</span><span class="p">}</span>
<span class="gp">>>> </span><span class="nb">sorted</span><span class="p">(</span><span class="n">students</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">newgrades</span><span class="o">.</span><span class="n">__getitem__</span><span class="p">)</span>
<span class="go">['jane', 'dave', 'john']</span>
</pre></div>
</div>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference external" href="#">Sorting HOW TO</a><ul>
<li><a class="reference external" href="#sorting-basics">Sorting Basics</a></li>
<li><a class="reference external" href="#key-functions">Key Functions</a></li>
<li><a class="reference external" href="#operator-module-functions">Operator Module Functions</a></li>
<li><a class="reference external" href="#ascending-and-descending">Ascending and Descending</a></li>
<li><a class="reference external" href="#sort-stability-and-complex-sorts">Sort Stability and Complex Sorts</a></li>
<li><a class="reference external" href="#the-old-way-using-decorate-sort-undecorate">The Old Way Using Decorate-Sort-Undecorate</a></li>
<li><a class="reference external" href="#the-old-way-using-the-cmp-parameter">The Old Way Using the <em>cmp</em> Parameter</a></li>
<li><a class="reference external" href="#odd-and-ends">Odd and Ends</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="sockets.html"
title="previous chapter">Socket Programming HOWTO</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="unicode.html"
title="next chapter">Unicode HOWTO</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li><a href="../_sources/howto/sorting.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../modindex.html" title="Global Module Index"
>modules</a> |</li>
<li class="right" >
<a href="unicode.html" title="Unicode HOWTO"
>next</a> |</li>
<li class="right" >
<a href="sockets.html" title="Socket Programming HOWTO"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="../index.html">Python v2.7.1 documentation</a> »</li>
<li><a href="index.html" >Python HOWTOs</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2010, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="http://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Nov 27, 2010.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.7.
</div>
</body>
</html>
