diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/source/changelog.rst | 11 | ||||
-rw-r--r-- | docs/source/examples.rst | 28 | ||||
-rw-r--r-- | docs/source/intro.rst | 45 |
3 files changed, 72 insertions, 12 deletions
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index 2803377..834373a 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog.rst @@ -3,6 +3,17 @@ Changelog --------- +05-17-2015 v. 4.0.0 +''''''''''''''''''' + + - Made default behavior of 'natsort' search for unsigned ints, + rather than signed floats. This is a backwards-incompatible + change but in 99% of use cases it should not required any + end-user changes. + - Improved handling of locale-aware sorting on systems where the + underlying locale library is broken. + - Greatly improved all unit tests by adding the hypothesis library. + 04-06-2015 v. 3.5.6 ''''''''''''''''''' diff --git a/docs/source/examples.rst b/docs/source/examples.rst index 53aa6f9..02783f4 100644 --- a/docs/source/examples.rst +++ b/docs/source/examples.rst @@ -29,6 +29,8 @@ As of :mod:`natsort` version >= 4.0.0, :func:`~natsorted` will now properly sort version numbers. The old function :func:`~versorted` exists for backwards compatibility but new development should use :func:`~natsorted`. +.. _rc_sorting: + Sorting with Alpha, Beta, and Release Candidates ++++++++++++++++++++++++++++++++++++++++++++++++ @@ -107,6 +109,32 @@ with the ``locale`` module from the standard library that are solved when using `PyICU <https://pypi.python.org/pypi/PyICU>`_; you can read about them here: http://bugs.python.org/issue23195. +If you have problems with ``ns.LOCALE`` (or :func:`~humansorted`), +especially on BSD-based systems, you can try the following: + + 1. Use "\*.ISO8859-1" locale (i.e. 'en_US.ISO8859-1') rather than "\*.UTF-8" + encoding. These encodings do not suffer from as many problems as "UTF-8" + and thus should give expected results. + 2. Use `PyICU <https://pypi.python.org/pypi/PyICU>`_. If + `PyICU <https://pypi.python.org/pypi/PyICU>`_ is installed, ``natsort`` + will use it under the hood if it is installed; this will give more + reliable cross-platform results in the long run. ``natsort`` will not + require (or check) that `PyICU <https://pypi.python.org/pypi/PyICU>`_ + is installed at installation. Please visit + https://github.com/SethMMorton/natsort/issues/21 for more details and + how to install on Mac OS X. **Please note** that using + `PyICU <https://pypi.python.org/pypi/PyICU>`_ is the only way to + guarantee correct results for all input on BSD-based systems, since + every other suggestion is a workaround. + 3. Do nothing. As of ``natsort`` version 4.0.0, ``natsort`` is configured + to compensate for a broken ``locale`` library in terms of case-handling; + if you do not need to be able to properly handle non-ASCII characters + then this may be the best option for you. + +Note that the above solutions *should not* be required for Windows or +Linux since in Linux-based systems and Windows systems ``locale`` *should* work +just fine. + Controlling Case When Sorting ----------------------------- diff --git a/docs/source/intro.rst b/docs/source/intro.rst index 86c6fbf..d454094 100644 --- a/docs/source/intro.rst +++ b/docs/source/intro.rst @@ -50,7 +50,7 @@ or as versions. Using :func:`~natsorted` is simple:: :func:`~natsorted` identifies numbers anywhere in a string and sorts them naturally. -Sorting is handled properly by default (as of :mod:`natsort` version >= 4.0.0): +Sorting versions is handled properly by default (as of :mod:`natsort` version >= 4.0.0): .. code-block:: python @@ -58,6 +58,9 @@ Sorting is handled properly by default (as of :mod:`natsort` version >= 4.0.0): >>> natsorted(a) ['version-1.9', 'version-1.10', 'version-1.11', 'version-2.0'] +If you need to sort release candidates, please see :ref:`rc_sorting` for +a useful hack. + 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 :func:`~humansorted` function:: @@ -155,9 +158,9 @@ If you want to build this documentation, enter:: python setup.py build_sphinx -:mod:`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 <https://pypi.python.org/pypi/argparse>`_ module is required. +:mod:`natsort` requires Python version 2.7 or greater or Python 3.3 or greater. +Python 2.6 and 3.2 are no longer officially supported (no unit tests are performed) +but it should work. The most efficient sorting can occur if you install the `fastnumbers <https://pypi.python.org/pypi/fastnumbers>`_ package (it helps @@ -167,14 +170,32 @@ recommended you include this as a dependency. ``natsort`` will not require (or check) that `fastnumbers <https://pypi.python.org/pypi/fastnumbers>`_ is installed. 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 <https://pypi.python.org/pypi/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 <https://pypi.python.org/pypi/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. +can be buggy (please see http://bugs.python.org/issue23195); ``locale`` is +used for the ``ns.LOCALE`` option and ``humansorted`` function.. To remedy this, +one can + + 1. Use "\*.ISO8859-1" locale (i.e. 'en_US.ISO8859-1') rather than "\*.UTF-8" + encoding. These encodings do not suffer from as many problems as "UTF-8" + and thus should give expected results. + 2. Use `PyICU <https://pypi.python.org/pypi/PyICU>`_. If + `PyICU <https://pypi.python.org/pypi/PyICU>`_ is installed, ``natsort`` + will use it under the hood if it is installed; this will give more + reliable cross-platform results in the long run. ``natsort`` will not + require (or check) that `PyICU <https://pypi.python.org/pypi/PyICU>`_ + is installed at installation. Please visit + https://github.com/SethMMorton/natsort/issues/21 for more details and + how to install on Mac OS X. **Please note** that using + `PyICU <https://pypi.python.org/pypi/PyICU>`_ is the only way to + guarantee correct results for all input on BSD-based systems, since + every other suggestion is a workaround. + 3. Do nothing. As of ``natsort`` version 4.0.0, ``natsort`` is configured + to compensate for a broken ``locale`` library in terms of case-handling; + if you do not need to be able to properly handle non-ASCII characters + then this may be the best option for you. + +Note that the above solutions *should not* be required for Windows or +Linux since in Linux-based systems and Windows systems ``locale`` *should* work +just fine. :mod:`natsort` comes with a shell script called :mod:`natsort`, or can also be called from the command line with ``python -m natsort``. The command line script is |