If you want more detailed examples than given on this page, please see https://github.com/SethMMorton/natsort/tree/master/test_natsort.
In the most basic use case, simply import natsorted() and use it as you would sorted():
>>> a = ['a2', 'a9', 'a1', 'a4', 'a10']
>>> sorted(a)
['a1', 'a10', 'a2', 'a4', 'a9']
>>> from natsort import natsorted, ns
>>> natsorted(a)
['a1', 'a2', 'a4', 'a9', 'a10']
As of natsort version >= 4.0.0, natsorted() will now properly sort version numbers. The old function versorted() exists for backwards compatibility but new development should use natsorted().
By default, if you wish to sort versions with a non-strict versioning scheme, you may not get the results you expect:
>>> a = ['1.2', '1.2rc1', '1.2beta2', '1.2beta1', '1.2alpha', '1.2.1', '1.1', '1.3']
>>> natsorted(a)
['1.1', '1.2', '1.2.1', '1.2alpha', '1.2beta1', '1.2beta2', '1.2rc1', '1.3']
To make the ‘1.2’ pre-releases come before ‘1.2.1’, you need to use the following recipe:
>>> natsorted(a, key=lambda x: x.replace('.', '~'))
['1.1', '1.2', '1.2alpha', '1.2beta1', '1.2beta2', '1.2rc1', '1.2.1', '1.3']
If you also want ‘1.2’ after all the alpha, beta, and rc candidates, you can modify the above recipe:
>>> natsorted(a, key=lambda x: x.replace('.', '~')+'z')
['1.1', '1.2alpha', '1.2beta1', '1.2beta2', '1.2rc1', '1.2', '1.2.1', '1.3']
Please see this issue to see why this works.
In some cases when sorting file paths with OS-Generated names, the default natsorted algorithm may not be sufficient. In cases like these, you may need to use the ns.PATH option:
>>> a = ['./folder/file (1).txt',
... './folder/file.txt',
... './folder (1)/file.txt',
... './folder (10)/file.txt']
>>> natsorted(a)
['./folder (1)/file.txt', './folder (10)/file.txt', './folder/file (1).txt', './folder/file.txt']
>>> natsorted(a, alg=ns.PATH)
['./folder/file.txt', './folder/file (1).txt', './folder (1)/file.txt', './folder (10)/file.txt']
You can instruct natsort to use locale-aware sorting with the ns.LOCALE option. In addition to making this understand non-ASCII characters, it will also properly interpret non-‘.’ decimal separators and also properly order case. It may be more convenient to just use the humansorted() function:
>>> from natsort import humansorted
>>> import locale
>>> locale.setlocale(locale.LC_ALL, 'en_US.UTF-8')
'en_US.UTF-8'
>>> a = ['Apple', 'corn', 'Corn', 'Banana', 'apple', 'banana']
>>> natsorted(a, alg=ns.LOCALE)
['apple', 'Apple', 'banana', 'Banana', 'corn', 'Corn']
>>> humansorted(a)
['apple', 'Apple', 'banana', 'Banana', 'corn', 'Corn']
You may find that if you do not explicitly set the locale your results may not be as you expect... I have found that it depends on the system you are on. If you use PyICU (see below) then you should not need to do this.
If you find that ns.LOCALE (or humansorted()) does not give the results you expect, before filing a bug report please try to first install PyICU; this especially applies to users on BSD-based systems (like Mac OS X). There are some known bugs with the locale module from the standard library that are solved when using PyICU; you can read about them here: http://bugs.python.org/issue23195.
If you have problems with ns.LOCALE (or humansorted()), especially on BSD-based systems, you can try the following:
- Use “*.ISO8859-1” locale (i.e. ‘en_US.ISO8859-1’) rather than “*.UTF-8” locale. These locales do not suffer from as many problems as “UTF-8” and thus should give expected results.
- Use PyICU. If PyICU is installed, natsort will use it under the hood; this will give more reliable cross-platform results in the long run. natsort will not require (or check) that PyICU is installed at installation. Please visit https://github.com/SethMMorton/natsort/issues/21 for more details and how to install on Mac OS X. Please note that using PyICU is the only way to guarantee correct results for all input on BSD-based systems, since every other suggestion is a workaround.
- Do nothing. As of natsort version 4.0.0, natsort is configured to compensate for a broken locale library in terms of case-handling; if you do not need to be able to properly handle non-ASCII characters then this may be the best option for you.
Note that the above solutions should not be required for Windows or Linux since in Linux-based systems and Windows systems locale should work just fine.
For non-numbers, by default natsort used ordinal sorting (i.e. it sorts by the character’s value in the ASCII table). For example:
>>> a = ['Apple', 'corn', 'Corn', 'Banana', 'apple', 'banana']
>>> natsorted(a)
['Apple', 'Banana', 'Corn', 'apple', 'banana', 'corn']
There are times when you wish to ignore the case when sorting, you can easily do this with the ns.IGNORECASE option:
>>> natsorted(a, alg=ns.IGNORECASE)
['Apple', 'apple', 'Banana', 'banana', 'corn', 'Corn']
Note thats since Python’s sorting is stable, the order of equivalent elements after lowering the case is the same order they appear in the original list.
Upper-case letters appear first in the ASCII table, but many natural sorting methods place lower-case first. To do this, use ns.LOWERCASEFIRST:
>>> natsorted(a, alg=ns.LOWERCASEFIRST)
['apple', 'banana', 'corn', 'Apple', 'Banana', 'Corn']
It may be undesirable to have the upper-case letters grouped together and the lower-case letters grouped together; most would expect all “a”s to bet together regardless of case, and all “b”s, and so on. To achieve this, use ns.GROUPLETTERS:
>>> natsorted(a, alg=ns.GROUPLETTERS)
['Apple', 'apple', 'Banana', 'banana', 'Corn', 'corn']
You might combine this with ns.LOWERCASEFIRST to get what most would expect to be “natural” sorting:
>>> natsorted(a, alg=ns.G | ns.LF)
['apple', 'Apple', 'banana', 'Banana', 'corn', 'Corn']
You can make natsorted() search for any float that would be a valid Python float literal, such as 5, 0.4, -4.78, +4.2E-34, etc. using the ns.FLOAT key. You can disable the exponential component of the number with ns.NOEXP.
>>> a = ['a50', 'a51.', 'a+50.4', 'a5.034e1', 'a+50.300']
>>> natsorted(a, alg=ns.FLOAT)
['a50', 'a5.034e1', 'a51.', 'a+50.300', 'a+50.4']
>>> natsorted(a, alg=ns.FLOAT | ns.SIGNED)
['a50', 'a+50.300', 'a5.034e1', 'a+50.4', 'a51.']
>>> natsorted(a, alg=ns.FLOAT | ns.SIGNED | ns.NOEXP)
['a5.034e1', 'a50', 'a+50.300', 'a+50.4', 'a51.']
For convenience, the ns.REAL option is provided which is a shortcut for ns.FLOAT | ns.SIGNED and can be used to sort on real numbers. This can be easily accessed with the realsorted() convenience function. Please note that the behavior of the realsorted() function was the default behavior of natsorted() for natsort version < 4.0.0:
>>> natsorted(a, alg=ns.REAL)
['a50', 'a+50.300', 'a5.034e1', 'a+50.4', 'a51.']
>>> from natsort import realsorted
>>> realsorted(a)
['a50', 'a+50.300', 'a5.034e1', 'a+50.4', 'a51.']
Like the built-in sorted function, natsorted can accept a custom sort key so that:
>>> from operator import attrgetter, itemgetter
>>> a = [['a', 'num4'], ['b', 'num8'], ['c', 'num2']]
>>> natsorted(a, key=itemgetter(1))
[['c', 'num2'], ['a', 'num4'], ['b', 'num8']]
>>> class Foo:
... def __init__(self, bar):
... self.bar = bar
... def __repr__(self):
... return "Foo('{0}')".format(self.bar)
>>> b = [Foo('num3'), Foo('num5'), Foo('num2')]
>>> natsorted(b, key=attrgetter('bar'))
[Foo('num2'), Foo('num3'), Foo('num5')]
If you need to sort a list in-place, you cannot use natsorted(); you need to pass a key to the list.sort() method. The function natsort_keygen() is a convenient way to generate these keys for you:
>>> from natsort import natsort_keygen
>>> a = ['a50', 'a51.', 'a50.4', 'a5.034e1', 'a50.300']
>>> natsort_key = natsort_keygen(alg=ns.FLOAT)
>>> a.sort(key=natsort_key)
>>> a
['a50', 'a50.300', 'a5.034e1', 'a50.4', 'a51.']
natsort_keygen() has the same API as natsorted() (minus the reverse option).
Sometimes you have multiple lists, and you want to sort one of those lists and reorder the other lists according to how the first was sorted. To achieve this you could use the index_natsorted() in combination with the convenience function order_by_index():
>>> from natsort import index_natsorted, order_by_index
>>> a = ['a2', 'a9', 'a1', 'a4', 'a10']
>>> b = [4, 5, 6, 7, 8]
>>> c = ['hi', 'lo', 'ah', 'do', 'up']
>>> index = index_natsorted(a)
>>> order_by_index(a, index)
['a1', 'a2', 'a4', 'a9', 'a10']
>>> order_by_index(b, index)
[6, 4, 7, 5, 8]
>>> order_by_index(c, index)
['ah', 'hi', 'do', 'lo', 'up']
Just like the sorted() built-in function, you can supply the reverse option to return the results in reverse order:
>>> a = ['a2', 'a9', 'a1', 'a4', 'a10']
>>> natsorted(a, reverse=True)
['a10', 'a9', 'a4', 'a2', 'a1']
Python 3 is rather strict about comparing strings and bytes, and this can make it difficult to deal with collections of both. Because of the challenge of guessing which encoding should be used to decode a bytes array to a string, natsort does not try to guess and automatically convert for you; in fact, the official stance of natsort is to not support sorting bytes. Instead, some decoding convenience functions have been provided to you (see Help With Bytes On Python 3) that allow you to provide a codec for decoding bytes through the key argument that will allow natsort to convert byte arrays to strings for sorting; these functions know not to raise an error if the input is not a byte array, so you can use the key on any arbitrary collection of data.
>>> from natsort import as_ascii
>>> 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_ascii) == [14.0, b'a', 'b']
True
Additionally, regular expressions cannot be run on byte arrays, making it so that natsort cannot parse them for numbers. As a result, if you run natsort on a list of bytes, you will get results that are like Python’s default sorting behavior. Of course, you can use the decoding functions to solve this:
>>> from natsort import as_utf8
>>> a = [b'a56', b'a5', b'a6', b'a40']
>>> natsorted(a)
[b'a40', b'a5', b'a56', b'a6']
>>> natsorted(a, key=as_utf8) == [b'a5', b'a6', b'a40', b'a56']
True
If you need a codec different from ASCII or UTF-8, you can use decoder() to generate a custom key:
>>> from natsort import decoder
>>> a = [b'a56', b'a5', b'a6', b'a40']
>>> natsorted(a, key=decoder('latin1')) == [b'a5', b'a6', b'a40', b'a56']
True
As of Pandas version 0.16.0, the sorting methods do not accept a key argument, so you cannot simply pass natsort_keygen() to a Pandas DataFrame and sort. This request has been made to the Pandas devs; see issue 3942 if you are interested. If you need to sort a Pandas DataFrame, please check out this answer on StackOverflow for ways to do this without the key argument to sort.