Metadata-Version: 2.2
Name: naturalsort
Version: 1.5.1
Summary: Simple natural order sorting API for Python
Home-page: https://github.com/xolox/python-naturalsort
Author: Peter Odding
Author-email: peter@peterodding.com
Classifier: Development Status :: 6 - Mature
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Text Processing :: General
License-File: LICENSE.txt
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: summary

Simple natural order sorting API for Python
===========================================

.. image:: https://travis-ci.org/xolox/python-naturalsort.svg?branch=master
   :target: https://travis-ci.org/xolox/python-naturalsort

.. image:: https://coveralls.io/repos/xolox/python-naturalsort/badge.png?branch=master
   :target: https://coveralls.io/r/xolox/python-naturalsort?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.

.. External references:
.. _ASCII: http://en.wikipedia.org/wiki/ASCII
.. _GitHub: https://github.com/xolox/python-naturalsort
.. _MIT license: http://en.wikipedia.org/wiki/MIT_License
.. _natsort: https://pypi.python.org/pypi/natsort
.. _natural order sorting: http://www.codinghorror.com/blog/2007/12/sorting-for-humans-natural-sort-order.htm
.. _naturalsort: https://pypi.python.org/pypi/naturalsort
.. _peter@peterodding.com: peter@peterodding.com
.. _PyPI: https://pypi.python.org/pypi/naturalsort
