Skip to content

Examples and Recipes

Jump to bottom Edit New page
Seth Morton edited this page May 18, 2024 · 19 revisions

If you want more detailed examples than given on this page, please see https://github.com/SethMMorton/natsort/tree/main/tests.

Basic Usage

In the most basic use case, simply import natsorted() and use it as you would sorted():

>>> a = ['2 ft 7 in', '1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '7 ft 6 in']
>>> sorted(a)
['1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '2 ft 7 in', '7 ft 6 in']
>>> from natsort import natsorted, ns
>>> natsorted(a)
['1 ft 5 in', '2 ft 7 in', '2 ft 11 in', '7 ft 6 in', '10 ft 2 in']

Sort Version Numbers

As of natsort version >= 4.0.0, natsorted() will work for well-behaved version numbers, like MAJOR.MINOR.PATCH.

Sorting More Expressive Versioning Schemes

By default, if you wish to sort versions that are not as simple as MAJOR.MINOR.PATCH (or similar), 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.

Sorting Rigorously Defined Versioning Schemes (e.g. SemVer or PEP 440)

If you know you are using a versioning scheme that follows a well-defined format for which there is third-party module support, you should use those modules to assist in sorting. Some examples might be PEP 440 or SemVer.

If we are being honest, using these methods to parse a version means you don't need to use natsort - you should probably just use sorted() directly. Here's an example with SemVer:

>>> from semver import VersionInfo
>>> a = ['3.4.5-pre.1', '3.4.5', '3.4.5-pre.2+build.4']
>>> sorted(a, key=VersionInfo.parse)
['3.4.5-pre.1', '3.4.5-pre.2+build.4', '3.4.5']

Sort OS-Generated Paths

In some cases when sorting file paths with OS-Generated names, the default natsort 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']

Locale-Aware Sorting (Human Sorting)

NOTE: Please read Possible Issues with natsort.humansorted or ns.LOCALE before using ns.LOCALE, humansorted(), or index_humansorted().

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 then you should not need to do this.

Controlling Case When Sorting

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 that's 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']

Customizing Float Definition

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.']

Using a Custom Sorting Key

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('{}')".format(self.bar)
>>> b = [Foo('num3'), Foo('num5'), Foo('num2')]
>>> natsorted(b, key=attrgetter('bar'))
[Foo('num2'), Foo('num3'), Foo('num5')]

Sorting Strings Containing Hex

This example demonstrates a general strategy for handling custom numeric data, which is to use a regular expression to transform that into standard decimal notation in a key function and then sort that.

>>> import re
>>>
>>> import natsort

>>> # Regex to identify hex numbers in a string
>>> # This can be customized to fit your specific needs
>>> hex_finder = re.compile(
...     r"""
...         (?<!\w)           # The number cannot be preceded by an alphanumeric character
...         (                 # Begin the capturing group
...             0[xX]         # Must start with a 0x
...             [0-9a-fA-F]+  # The hex number itself
...         )                 # End the capturing group
...         (?!\w)            # The number cannot be followed by an alphanumeric character
...     """
...     flags=re.VERBOSE
... )
>>>
>>> def hex_normalizer(matchobj):
...     """Convert a hex number into a decimal number"""
...     return str(int(matchobj.group(1), base=16))
>>>
>>> def hex_key(x):
...     return hex_finder.sub(hex_normalizer, x)
>>>
>>> data = ['0xca', 'BABE', "104"]
>>> natsort.natsorted(data)
['0xca', '104', 'BABE']
>>> natsort.natsorted(data, key=hex_key)
['104', '0xca', 'BABE']

Accounting for Units When Sorting

natsort does not come with any pre-built mechanism to sort units, but you can write your own key to do this. Below, I will demonstrate sorting imperial lengths (e.g. feet an inches), but of course you can extend this to any set of units you need. This example is based on code from this issue, and uses the function natsort.numeric_regex_chooser() to build a regular expression that will parse numbers in the same manner as natsort itself.

>>> import re
>>> import natsort
>>>
>>> # Define how each unit will be transformed
>>> conversion_mapping = {
...         "in": 1,
...         "inch": 1,
...         "inches": 1,
...         "ft": 12,
...         "feet": 12,
...         "foot": 12,
... }
>>>
>>> # This regular expression searches for numbers and units
>>> all_units = "|".join(conversion_mapping.keys())
>>> float_re = natsort.numeric_regex_chooser(natsort.FLOAT | natsort.SIGNED)
>>> unit_finder = re.compile(r"({})\s*({})".format(float_re, all_units), re.IGNORECASE)
>>>
>>> def unit_replacer(matchobj):
...     """
...     Given a regex match object, return a replacement string where units are modified
...     """
...     number = matchobj.group(1)
...     unit = matchobj.group(2)
...     new_number = float(number) * conversion_mapping[unit]
...     return "{} in".format(new_number)
...
>>> # Demo time!
>>> data = ['1 ft', '5 in', '10 ft', '2 in']
>>> [unit_finder.sub(unit_replacer, x) for x in data]
['12.0 in', '5.0 in', '120.0 in', '2.0 in']
>>>
>>> natsort.natsorted(data, key=lambda x: unit_finder.sub(unit_replacer, x))
['2 in', '5 in', '1 ft', '10 ft']

Generating a Natsort Key

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).

Sorting Multiple Lists According to a Single List

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']

Returning Results in Reverse Order

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']

Sorting Bytes

Python 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) 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']
>>> # 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)  # doctest: +SKIP
[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

Sorting a Pandas DataFrame

Starting from Pandas version 1.1.0, the sorting methods accept a "key" argument, so you can simply pass natsort_keygen() to the sorting methods and sort:

import pandas as pd
from natsort import natsort_keygen
s = pd.Series(['2 ft 7 in', '1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '7 ft 6 in'])
s.sort_values(key=natsort_keygen())
# 1     1 ft 5 in
# 0     2 ft 7 in
# 3    2 ft 11 in
# 4     7 ft 6 in
# 2    10 ft 2 in
# dtype: object

(If you have a DataFrame instead of a Series you'll need to use the by keyword argument to specify the columns to send to the key.)

To sort an index it is recommended to use a different method:

import pandas as pd
from natsort import natsorted
df = pd.DataFrame(
    {
        'a': ['a5', 'a1', 'a10', 'a2', 'a12'],
        'b': ['b1', 'b1', 'b2', 'b2', 'b1']
    },
    index=['0hr', '128hr', '72hr', '48hr', '96hr'],
)
df.reindex(index=natsorted(df.index))
#         a   b
# 0hr     a5  b1
# 48hr    a2  b2
# 72hr   a10  b2
# 96hr   a12  b1
# 128hr   a1  b1

We use this method because the output of natsort_keygen() is not intepreted properly by the sort_index() method of a DataFrame (see https://github.com/SethMMorton/natsort/issues/172).

Here are a couple of other methods that return equivalent results:

df.loc[natsorted(df.index)]
#         a   b
# 0hr     a5  b1
# 48hr    a2  b2
# 72hr   a10  b2
# 96hr   a12  b1
# 128hr   a1  b1

df.iloc[index_natsorted(df.index)]
#         a   b
# 0hr     a5  b1
# 48hr    a2  b2
# 72hr   a10  b2
# 96hr   a12  b1
# 128hr   a1  b1

Check out this answer on StackOverflow for a longer discussion on this.

Add a custom footer
Add a custom sidebar
Clone this wiki locally