Skip to main content

Simple natural order sorting API for Python

Project description

https://travis-ci.org/xolox/python-naturalsort.svg?branch=master https://coveralls.io/repos/xolox/python-naturalsort/badge.png?branch=master

The natsort.natsort() function in the naturalsort package is a very simple alternative to Python’s sorted() function that implements natural order sorting in Python. The package is available on PyPI, so getting started is very simple:

$ pip install naturalsort
$ python
> from natsort import natsort
> versions = ['1.8.1-r26', '1.8.1-r30', '2.0-r2', '2.0-r7', '2.0-r11']
> natsort(['my-package-%s' % v for v in versions])
['my-package-1.8.1-r26',
 'my-package-1.8.1-r30',
 'my-package-2.0-r2',
 'my-package-2.0-r7',
 'my-package-2.0-r11']

Usage

Here’s an example of regular sorting (based on the ASCII order of individual characters) compared to natural order sorting:

> # Import the sorted() alternative.
> from natsort import natsort
>
> # This is plain old sorting (what we DON'T want).
> sorted(['1', '5', '10', '50'])
['1', '10', '5', '50']
>
> # This is natural order sorting (what we DO want).
> natsort(['1', '5', '10', '50'])
['1', '5', '10', '50']
>
> # natsort() accepts a optional ``reverse`` argument for consistency with
> the built-in sorted() function.
> natsort(['1', '5', '10', '50'], reverse=True)
['50', '10', '5', '1']

Custom comparison keys

The main use case that the naturalsort package was originally created for is sorting of filenames with versions numbers embedded in them. Unfortunately this won’t always work out of the box; you may need to define a custom comparison key. Here’s an example where a custom comparison key is required to get the proper results:

> from natsort import natsort
> from pprint import pprint
> versions = ['package-name_1_all.deb',
...           'package-name_1.5_all.deb',
...           'package-name_2_all.deb']

This is what happens by default:

> pprint(natsort(versions))
['package-name_1.5_all.deb',
 'package-name_1_all.deb',
 'package-name_2_all.deb']

Here’s how to get the right results:

> from os.path import basename, splitext
> def version_from_fname(filename):
...   filename, extension = splitext(basename(filename))
..    name, version, architecture = filename.split('_')
...   return version
...
> pprint(natsort(versions, key=version_from_fname))
['package-name_1_all.deb',
 'package-name_1.5_all.deb',
 'package-name_2_all.deb']

Why another natsort module?!

The natsort package on PyPI is more advanced and configurable than my naturalsort package, so depending on your use case you may prefer to use that package instead. Here are the differences:

  1. My naturalsort package implements only a small subset of the functionality of the natsort package, specifically the following calls result in the same sorting order:

    naturalsort package:

    natsort.natsort(['1-1', '1-2'])

    natsort package:

    natsort.natsorted(['1-1', '1-2'], number_type=None)

    This example shows the different goals of the two packages: The naturalsort package is intended to sort version numbers while the natsort package by default interprets dashes as a negative sign and requires the keyword argument number_type=None to disable this behavior.

  2. The naturalsort package works on Python 2.4 and 2.5 while the natsort package requires at least Python 2.6.

Contact

The latest version of naturalsort is available on PyPI and GitHub. For bug reports please create an issue on GitHub. If you have questions, suggestions, etc. feel free to send me an e-mail at peter@peterodding.com.

License

This software is licensed under the MIT license.

© 2015 Peter Odding.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

naturalsort-1.5.1.tar.gz (7.4 kB view details)

Uploaded Source

File details

Details for the file naturalsort-1.5.1.tar.gz.

File metadata

  • Download URL: naturalsort-1.5.1.tar.gz
  • Upload date:
  • Size: 7.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for naturalsort-1.5.1.tar.gz
Algorithm Hash digest
SHA256 172b5ed6e7ba3420c08ba2ded1c52fe74878f5d769dc5d9dec2b6a53e7117356
MD5 a7b7dcd79686ae1e5de24ec104bf7a2b
BLAKE2b-256 0c84ce1985c8c61d2ac21a4b3a5d586ed0794b855f925ecc47adca546f0c7022

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page