3.2. natsort_key()

natsort.natsort_key(val, key=None, number_type=<type 'float'>, signed=None, exp=None, as_path=None, py3_safe=None, alg=0)

Key to sort strings and numbers naturally.

Key to sort strings and numbers naturally, not lexicographically. It is designed for use in passing to the ‘sorted’ builtin or ‘sort’ attribute of lists.

Note

Depreciated since version 3.4.0. This function remains in the publicly exposed API for backwards-compatibility reasons, but future development should use the newer natsort_keygen function. It is planned to remove this from the public API in natsort version 4.0.0. A DeprecationWarning will be raised via the warnings module; set warnings.simplefilter(“always”) to raise them to see if your code will work in version 4.0.0.

Parameters:

val : {str, unicode}

The value used by the sorting algorithm

key : callable, optional

A key used to manipulate the input value before parsing for numbers. It is not applied recursively. It should accept a single argument and return a single value.

number_type : {None, float, int}, optional

Depreciated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the alg argument for all future development. See ns class documentation for details.

signed : {True, False}, optional

Depreciated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the alg argument for all future development. See ns class documentation for details.

exp : {True, False}, optional

Depreciated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the alg argument for all future development. See ns class documentation for details.

as_path : {True, False}, optional

Depreciated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the alg argument for all future development. See ns class documentation for details.

py3_safe : {True, False}, optional

Depreciated as of version 3.5.0 and will become an undocumented keyword-only argument in 4.0.0. Please use the alg argument for all future development. See ns class documentation for details.

alg : ns enum, optional

This option is used to control which algorithm natsort uses when sorting. For details into these options, please see the ns class documentation. The default is ns.FLOAT.

Returns:

out : tuple

The modified value with numbers extracted.

See also

natsort_keygen
Generates a properly wrapped natsort_key.

Notes

Iterables are parsed recursively so you can sort lists of lists:

>>> natsort_key(('a1', 'a10'))
((u'a', 1.0), (u'a', 10.0))

Strings that lead with a number get an empty string at the front of the tuple. This is designed to get around the “unorderable types” issue of Python3:

>>> natsort_key('15a')
(u'', 15.0, u'a')

You can give bare numbers, too:

>>> natsort_key(10)
(u'', 10)

If you have a case where one of your string has two numbers in a row, you can turn on the “py3_safe” option to try to add a “” between sets of two numbers:

>>> natsort_key('43h7+3', py3_safe=True)
(u'', 43.0, u'h', 7.0, u'', 3.0)

Examples

Using natsort_key is just like any other sorting key in python:

>>> a = ['num3', 'num5', 'num2']
>>> a.sort(key=natsort_key)
>>> a
[u'num2', u'num3', u'num5']

It works by separating out the numbers from the strings:

>>> natsort_key('num2')
(u'num', 2.0)

If you need to call natsort_key with the number_type argument, or get a special attribute or item of each element of the sequence, please use the natsort_keygen function. Actually, please just use the natsort_keygen function.