Simple yet flexible natural sorting in Python.
Project description
Simple yet flexible natural sorting in Python.
Source Code: https://github.com/SethMMorton/natsort
Downloads: https://pypi.org/project/natsort/
Documentation: http://natsort.readthedocs.io/
NOTE: The old documentation at pythonhosted.org has been taken down with no redirects. Please see this post for an explanation into why.
fastnumbers >= 0.7.1
PyICU >= 1.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 = ['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']
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” (“naturally” is rather ill-defined, but in general it means sorting based on meaning and not computer code point). Using natsorted is simple:
>>> from natsort import natsorted
>>> a = ['2 ft 7 in', '1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '7 ft 6 in']
>>> natsorted(a)
['1 ft 5 in', '2 ft 7 in', '2 ft 11 in', '7 ft 6 in', '10 ft 2 in']
natsorted identifies numbers anywhere in a string and sorts them naturally. Below are some other things you can do with natsort (also see the examples for a quick start guide, or the api for complete details).
Note: natsorted is designed to be a drop-in replacement for the built-in sorted function. Like sorted, natsorted does not sort in-place. To sort a list and assign the output to the same variable, you must explicitly assign the output to a variable:
>>> a = ['2 ft 7 in', '1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '7 ft 6 in']
>>> natsorted(a)
['1 ft 5 in', '2 ft 7 in', '2 ft 11 in', '7 ft 6 in', '10 ft 2 in']
>>> print(a) # 'a' was not sorted; "natsorted" simply returned a sorted list
['2 ft 7 in', '1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '7 ft 6 in']
>>> a = natsorted(a) # Now 'a' will be sorted because the sorted list was assigned to 'a'
>>> print(a)
['1 ft 5 in', '2 ft 7 in', '2 ft 11 in', '7 ft 6 in', '10 ft 2 in']
Please see Generating a Reusable Sorting Key and Sorting In-Place for an alternate way to sort in-place naturally.
Sorting Versions
This is handled properly by default (as of natsort version >= 4.0.0):
>>> a = ['version-1.9', 'version-2.0', 'version-1.11', 'version-1.10']
>>> natsorted(a)
['version-1.9', 'version-1.10', 'version-1.11', 'version-2.0']
If you need to sort release candidates, please see this useful hack.
Sorting by Real Numbers (i.e. Signed Floats)
This is useful in scientific data analysis and was the default behavior of natsorted for natsort version < 4.0.0. Use the realsorted function:
>>> from natsort import realsorted, ns
>>> # Note that when interpreting as signed floats, the below numbers are
>>> # +5.10, -3.00, +5.30, +2.00
>>> a = ['position5.10.data', 'position-3.data', 'position5.3.data', 'position2.data']
>>> natsorted(a)
['position2.data', 'position5.3.data', 'position5.10.data', 'position-3.data']
>>> natsorted(a, alg=ns.REAL)
['position-3.data', 'position2.data', 'position5.10.data', 'position5.3.data']
>>> realsorted(a) # shortcut for natsorted with alg=ns.REAL
['position-3.data', 'position2.data', 'position5.10.data', 'position5.3.data']
Locale-Aware Sorting (or “Human Sorting”)
This is where the non-numeric characters are also ordered based on their meaning, not on their ordinal value, and a locale-dependent thousands separator and decimal separator is accounted for in the number. This can be achieved with the humansorted function:
>>> a = ['Apple', 'apple15', 'Banana', 'apple14,689', 'banana']
>>> natsorted(a)
['Apple', 'Banana', 'apple14,689', 'apple15', 'banana']
>>> import locale
>>> locale.setlocale(locale.LC_ALL, 'en_US.UTF-8')
'en_US.UTF-8'
>>> natsorted(a, alg=ns.LOCALE)
['apple15', 'apple14,689', 'Apple', 'banana', 'Banana']
>>> from natsort import humansorted
>>> humansorted(a) # shortcut for natsorted with alg=ns.LOCALE
['apple15', 'apple14,689', '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 locale issues and the Optional Dependencies section below before using the humansorted function.
Further Customizing Natsort
If you need to combine multiple algorithm modifiers (such as ns.REAL, ns.LOCALE, and ns.IGNORECASE), you can combine the options using the bitwise OR operator (|). For example,
>>> a = ['Apple', 'apple15', 'Banana', 'apple14,689', 'banana']
>>> natsorted(a, alg=ns.REAL | ns.LOCALE | ns.IGNORECASE)
['Apple', 'apple15', 'apple14,689', 'Banana', 'banana']
>>> # The ns enum provides long and short forms for each option.
>>> ns.LOCALE == ns.L
True
>>> # You can also customize the convenience functions, too.
>>> natsorted(a, alg=ns.REAL | ns.LOCALE | ns.IGNORECASE) == realsorted(a, alg=ns.L | ns.IC)
True
>>> natsorted(a, alg=ns.REAL | ns.LOCALE | ns.IGNORECASE) == humansorted(a, alg=ns.R | ns.IC)
True
All of the available customizations can be found in the documentation for the ns enum.
Sorting Mixed Types
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
Handling Bytes on Python 3
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
Generating a Reusable Sorting Key and Sorting In-Place
Under the hood, natsorted works by generating a custom sorting key using natsort_keygen and then passes that to the built-in sorted. You can use the natsort_keygen function yourself to generate a custom sorting key to sort in-place using the list.sort method.
>>> from natsort import natsort_keygen
>>> natsort_key = natsort_keygen()
>>> a = ['2 ft 7 in', '1 ft 5 in', '10 ft 2 in', '2 ft 11 in', '7 ft 6 in']
>>> natsorted(a) == sorted(a, key=natsort_key)
True
>>> a.sort(key=natsort_key)
>>> a
['1 ft 5 in', '2 ft 7 in', '2 ft 11 in', '7 ft 6 in', '10 ft 2 in']
All of the algorithm customizations mentioned in the Further Customizing Natsort section can also be applied to natsort_keygen through the alg keyword option.
Other Useful Things
recursively descend into lists of lists
automatic unicode normalization of input data
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 or Python 3.3 or greater. It may run on (but is not tested against) Python 3.2.
Optional Dependencies
fastnumbers
The most efficient sorting can occur if you install the fastnumbers package (version >=0.7.1); 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
It is recommended that you install PyICU if you wish to sort in a locale-dependent manner, see http://natsort.readthedocs.io/en/master/locale_issues.html for an explanation why.
Installation and Testing
To install natsort, it is simplest to use pip:
pip install natsort
You can also add the requirements.txt file; it will ensure that argparse is installed for Python 2.6 but does nothing on any other Python version:
pip install -rrequirements.txt natsort
If you want to install the optional dependencies fastnumbers and PyICU, add the optional-requirements.txt file:
pip install -roptional-requirements.txt natsort
If you wish to run the tests, please note that natsort is NOT set-up to support python setup.py test. The preferred way to run the tests is to use tox. If you want to run unit tests on (for example) Python 2.7, you can execute the following:
pip install tox tox -e py27
This will install all the necessary dependencies to run the natsort test suite. If you prefer not to use tox, you can run the tests manually using pytest:
pip install -rtesting-requirements.txt python -m pytest
History
These are the last three entries of the changelog. See the package documentation for the complete changelog.
02-14-2017 v. 5.2.0
Add ns.NUMAFTER to cause numbers to be placed after non-numbers.
Add natcmp function (Python 2 only).
11-11-2017 v. 5.1.1
Added additional unicode number support for Python 3.7.
Added information on how to install and test.
08-19-2017 v. 5.1.0
Fixed StopIteration warning on Python 3.6+.
All Unicode input is now normalized.
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 Distribution
Built Distribution
Hashes for natsort-5.2.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a9156f61336a8d743f67a8c9f336b1287529f67a07fe6001c7d4b5673a42308e |
|
MD5 | 0ec88b16543dad6efc431d43af8728ec |
|
BLAKE2b-256 | dd0f02359ee61e2b7ace625618ad87c336cbfa11b0e7b4f7a3ed9fc7b71cce6e |