Sort lists naturally
Project description
Natural sorting for python.
Source Code: https://github.com/SethMMorton/natsort
Downloads: https://pypi.python.org/pypi/natsort
Documentation: http://pythonhosted.org/natsort/
Please see Deprecation Notices for an important backwards incompatibility notice for natsort version 4.0.0.
Quick Description
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.
Shell script
natsort comes with a shell script called natsort, or can also be called from the command line with python -m natsort.
Requirements
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.
Optional Dependencies
fastnumbers
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.
PyICU
On BSD-based systems (this includes Mac OS X), the underlying locale library can be buggy (please see http://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 https://github.com/SethMMorton/natsort/issues/21 for more details and how to install on Mac OS X.
Deprecation Notices
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 cause natsort 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 add alg=ns.F to your natsort calls or switch to the new realsorted function which behaves identically to the current natsorted with default values.
In natsort version 4.0.0, the number_type, signed, exp, as_path, and py3_safe options will be removed from the (documented) API, in favor of the alg option and ns enum. They will remain as keyword-only arguments after that (for the foreseeable future).
In natsort version 4.0.0, the natsort_key function will be removed from the public API. All future development should use natsort_keygen in preparation for this.
History
These are the last three entries of the changelog. See the package documentation for the complete changelog.
04-06-2015 v. 3.5.6
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.
04-04-2015 v. 3.5.5
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.
04-02-2015 v. 3.5.4
Fixed bug where a ‘TypeError’ was raised if a string containing a leading number was sorted with alpha-only strings when ‘LOCALE’ is used.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for natsort-3.5.6-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bfbb82c1711463c94923e283fefe92957d791b36de58863cf338b85f1256feb5 |
|
MD5 | 44ec5dcec6ce2942d0a8b1299ceb398f |
|
BLAKE2b-256 | c54f4bb6388d3680566585c10197002d59c764f3fa8033ccc43df7a4a1979fdc |