Natural sorting for python.
- Source Code: https://github.com/SethMMorton/natsort
- Downloads: https://pypi.python.org/pypi/natsort
- Documentation: http:https://pythonhosted.org/natsort/
Please see Deprecation Notices for an important backwards incompatibility notice
for natsort
version 4.0.0.
When you try to sort a list of strings that contain numbers, the normal python sort algorithm sorts lexicographically, so you might not get the results that you expect:
>>> a = ['a2', 'a9', 'a1', 'a4', 'a10']
>>> sorted(a)
['a1', 'a10', 'a2', 'a4', 'a9']
Notice that it has the order ('1', '10', '2') - this is because the list is being sorted in lexicographical order, which sorts numbers like you would letters (i.e. 'b', 'ba', 'c').
natsort
provides a function natsorted
that helps sort lists "naturally",
either as real numbers (i.e. signed/unsigned floats or ints), or as versions.
Using natsorted
is simple:
>>> from natsort import natsorted
>>> a = ['a2', 'a9', 'a1', 'a4', 'a10']
>>> natsorted(a)
['a1', 'a2', 'a4', 'a9', 'a10']
natsorted
identifies real numbers anywhere in a string and sorts them
naturally.
Sorting version numbers is just as easy with the versorted
function:
>>> from natsort import versorted
>>> a = ['version-1.9', 'version-2.0', 'version-1.11', 'version-1.10']
>>> versorted(a)
['version-1.9', 'version-1.10', 'version-1.11', 'version-2.0']
>>> natsorted(a) # natsorted tries to sort as signed floats, so it won't work
['version-2.0', 'version-1.9', 'version-1.11', 'version-1.10']
You can also perform locale-aware sorting (or "human sorting"), where the
non-numeric characters are ordered based on their meaning, not on their
ordinal value; this can be achieved with the humansorted
function:
>>> a = ['Apple', 'Banana', 'apple', 'banana']
>>> natsorted(a)
['Apple', 'Banana', 'apple', 'banana']
>>> import locale
>>> locale.setlocale(locale.LC_ALL, 'en_US.UTF-8')
'en_US.UTF-8'
>>> from natsort import humansorted
>>> humansorted(a)
['apple', 'Apple', 'banana', 'Banana']
You may find you need to explicitly set the locale to get this to work
(as shown in the example).
Please see the following caveat
and the Optional Dependencies section
below before using the humansorted
function, especially if you are on a
BSD-based system (like Mac OS X).
You can mix and match int
, float
, and str
(or unicode
) types
when you sort:
>>> a = ['4.5', 6, 2.0, '5', 'a']
>>> natsorted(a)
[2.0, '4.5', '5', 6, 'a']
>>> # On Python 2, sorted(a) would return [2.0, 6, '4.5', '5', 'a']
>>> # On Python 3, sorted(a) would raise an "unorderable types" TypeError
natsort
does not officially support the bytes
type on Python 3, but
convenience functions are provided that help you decode to str
first:
>>> from natsort import as_utf8
>>> a = [b'a', 14.0, 'b']
>>> # On Python 2, natsorted(a) would would work as expected.
>>> # On Python 3, natsorted(a) would raise a TypeError (bytes() < str())
>>> natsorted(a, key=as_utf8) == [14.0, b'a', 'b']
True
>>> a = [b'a56', b'a5', b'a6', b'a40']
>>> # On Python 2, natsorted(a) would would work as expected.
>>> # On Python 3, natsorted(a) would return the same results as sorted(a)
>>> natsorted(a, key=as_utf8) == [b'a5', b'a6', b'a40', b'a56']
True
The natsort algorithm does other fancy things like
- recursively descend into lists of lists
- control the case-sensitivity
- sort file paths correctly
- allow custom sorting keys
- exposes a natsort_key generator to pass to
list.sort
Please see the package documentation for more details, including examples and recipes.
natsort
comes with a shell script called natsort
, or can also be called
from the command line with python -m natsort
.
natsort
requires python version 2.6 or greater
(this includes python 3.x). To run version 2.6, 3.0, or 3.1 the
argparse module is required.
The most efficient sorting can occur if you install the
fastnumbers package (it helps
with the string to number conversions.) natsort
will still run (efficiently)
without the package, but if you need to squeeze out that extra juice it is
recommended you include this as a dependency. natsort
will not require (or
check) that fastnumbers is installed
at installation.
On BSD-based systems (this includes Mac OS X), the underlying locale
library
can be buggy (please see http:https://bugs.python.org/issue23195), so natsort
will use
PyICU under the hood if it is installed
on your computer; this will give more reliable cross-platform results.
natsort
will not require (or check) that
PyICU is installed at installation
since in Linux-based systems and Windows systems locale
should work just fine.
Please visit SethMMorton#21 for more details and
how to install on Mac OS X.
- The default sorting algorithm for
natsort
will change in version 4.0.0 from signed floats (with exponents) to unsigned integers. The motivation for this change is that it will causenatsort
to return results that pass the "least astonishment" test for the most common use case, which is sorting version numbers. If you currently rely on the default behavior to be signed floats, it is recommend that you addalg=ns.F
to yournatsort
calls or switch to the newrealsorted
function which behaves identically to the currentnatsorted
with default values.- In
natsort
version 4.0.0, thenumber_type
,signed
,exp
,as_path
, andpy3_safe
options will be removed from the (documented) API, in favor of thealg
option andns
enum. They will remain as keyword-only arguments after that (for the foreseeable future).- In
natsort
version 4.0.0, thenatsort_key
function will be removed from the public API. All future development should usenatsort_keygen
in preparation for this.
Seth M. Morton
These are the last three entries of the changelog. See the package documentation for the complete changelog.
- Added 'UNGROUPLETTERS' algorithm to get the case-grouping behavior of an ordinal sort when using 'LOCALE'.
- Added convenience functions 'decoder', 'as_ascii', and 'as_utf8' for dealing with bytes types.
- Added 'realsorted' and 'index_realsorted' functions for forward-compatibility with >= 4.0.0.
- Made explanation of when to use "TYPESAFE" more clear in the docs.
- Fixed bug where a 'TypeError' was raised if a string containing a leading number was sorted with alpha-only strings when 'LOCALE' is used.