From 8f7d4b8c50cdbb5415703fa2215638f7d65e9f41 Mon Sep 17 00:00:00 2001 From: Seth Morton Date: Sun, 26 Feb 2023 20:14:20 -0800 Subject: Improve link handling in README.rst --- README.rst | 207 ++++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 115 insertions(+), 92 deletions(-) diff --git a/README.rst b/README.rst index f4639b1..79ed3ae 100644 --- a/README.rst +++ b/README.rst @@ -22,9 +22,9 @@ Simple yet flexible natural sorting in Python. - Downloads: https://pypi.org/project/natsort/ - Documentation: https://natsort.readthedocs.io/ - - `Examples and Recipes `_ - - `How Does Natsort Work? `_ - - `API `_ + - `Examples and Recipes`_ + - `How Does Natsort Work?`_ + - `API`_ - `Quick Description`_ - `Quick Examples`_ @@ -56,10 +56,10 @@ 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 +`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: +Using `natsorted()`_ is simple: .. code-block:: pycon @@ -68,14 +68,13 @@ Using ``natsorted`` is simple: >>> 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). +`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 and Recipes`_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`` +**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: @@ -109,12 +108,12 @@ Quick Examples Sorting Versions ++++++++++++++++ -``natsort`` does not actually *comprehend* version numbers. +`natsort`_ does not actually *comprehend* version numbers. It just so happens that the most common versioning schemes are designed to work with standard natural sorting techniques; these schemes include ``MAJOR.MINOR``, ``MAJOR.MINOR.PATCH``, ``YEAR.MONTH.DAY``. If your data conforms to a scheme like this, then it will work out-of-the-box with -``natsorted`` (as of ``natsort`` version >= 4.0.0): +`natsorted()`_ (as of `natsort`_ version >= 4.0.0): .. code-block:: pycon @@ -123,14 +122,14 @@ conforms to a scheme like this, then it will work out-of-the-box with ['version-1.9', 'version-1.10', 'version-1.11', 'version-2.0'] If you need to versions that use a more complicated scheme, please see -`these examples `_. +`these version sorting examples`_. Sort Paths Like My File Browser (e.g. Windows Explorer on Windows) ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -Prior to ``natsort`` version 7.1.0, it was a common request to be able to -sort paths like Windows Explorer. As of ``natsort`` 7.1.0, the function -``os_sorted`` has been added to provide users the ability to sort +Prior to `natsort`_ version 7.1.0, it was a common request to be able to +sort paths like Windows Explorer. As of `natsort`_ 7.1.0, the function +`os_sorted()`_ has been added to provide users the ability to sort in the order that their file browser might sort (e.g Windows Explorer on Windows, Finder on MacOS, Dolphin/Nautilus/Thunar/etc. on Linux). @@ -144,17 +143,17 @@ Windows, Finder on MacOS, Dolphin/Nautilus/Thunar/etc. on Linux). Output will be different depending on the operating system you are on. For users **not** on Windows (e.g. MacOS/Linux) it is **strongly** recommended -to also install `PyICU `_, which will help -``natsort`` give results that match most file browsers. If this is not installed, -it will fall back on Python's built-in ``locale`` module and will give good +to also install `PyICU`_, which will help +`natsort`_ give results that match most file browsers. If this is not installed, +it will fall back on Python's built-in `locale`_ module and will give good results for most input, but will give poor results for special characters. 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: +This is useful in scientific data analysis (and was the default behavior +of `natsorted()`_ for `natsort`_ version < 4.0.0). Use the `realsorted()`_ +function: .. code-block:: pycon @@ -175,7 +174,7 @@ 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: +This can be achieved with the `humansorted()`_ function: .. code-block:: pycon @@ -192,9 +191,8 @@ This can be achieved with the ``humansorted`` function: ['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. +(as shown in the example). Please see `locale issues`_ and the +`Optional Dependencies`_ section below before using the `humansorted()`_ function. Further Customizing Natsort +++++++++++++++++++++++++++ @@ -218,7 +216,7 @@ bitwise OR operator (``|``). For example, True All of the available customizations can be found in the documentation for -`the ns enum `_. +`the ns enum`_. You can also add your own custom transformation functions with the ``key`` argument. These can be used with ``alg`` if you wish. @@ -232,8 +230,7 @@ argument. These can be used with ``alg`` if you wish. Sorting Mixed Types +++++++++++++++++++ -You can mix and match ``int``, ``float``, and ``str`` (or ``unicode``) types -when you sort: +You can mix and match `int`_, `float`_, and `str`_ types when you sort: .. code-block:: pycon @@ -245,8 +242,8 @@ when you sort: Handling Bytes ++++++++++++++ -``natsort`` does not officially support the `bytes` type, but -convenience functions are provided that help you decode to `str` first: +`natsort`_ does not officially support the `bytes`_ type, but +convenience functions are provided that help you decode to `str`_ first: .. code-block:: pycon @@ -263,10 +260,10 @@ convenience functions are provided that help you decode to `str` first: 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`` +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. .. code-block:: pycon @@ -282,53 +279,49 @@ method. All of the algorithm customizations mentioned in the `Further Customizing Natsort`_ section can also be applied to -``natsort_keygen`` through the *alg* keyword option. +`natsort_keygen()`_ through the *alg* keyword option. Other Useful Things +++++++++++++++++++ - recursively descend into lists of lists - automatic unicode normalization of input data - - `controlling the case-sensitivity `_ - - `sorting file paths correctly `_ - - `allow custom sorting keys `_ - - `accounting for units `_ + - `controlling the case-sensitivity`_ + - `sorting file paths correctly`_ + - `allow custom sorting keys`_ + - `accounting for units`_ FAQ --- -How do I debug ``natsort.natsorted()``? - The best way to debug ``natsorted()`` is to generate a key using ``natsort_keygen()`` - with the same options being passed to ``natsorted``. One can take a look at +How do I debug `natsorted()`_? + The best way to debug `natsorted()`_ is to generate a key using `natsort_keygen()`_ + with the same options being passed to `natsorted()`_. One can take a look at exactly what is being done with their input using this key - it is highly - recommended - to `look at this issue describing how to debug `_ - for *how* to debug, and also to review the - `How Does Natsort Work? `_ - page for *why* ``natsort`` is doing that to your data. + recommended to `look at this issue describing how to debug`_ for *how* to debug, + and also to review the `How Does Natsort Work?`_ page for *why* `natsort`_ is + doing that to your data. If you are trying to sort custom classes and running into trouble, please take a look at https://github.com/SethMMorton/natsort/issues/60. In short, custom classes are not likely to be sorted correctly if one relies on the behavior of ``__lt__`` and the other rich comparison operators in their custom class - it is better to use a ``key`` function with - ``natsort``, or use the ``natsort`` key as part of your rich comparison + `natsort`_, or use the `natsort`_ key as part of your rich comparison operator definition. -``natsort`` gave me results I didn't expect, and it's a terrible library! +`natsort`_ gave me results I didn't expect, and it's a terrible library! Did you try to debug using the above advice? If so, and you still cannot figure out - the error, then please `file an issue `_. + the error, then please `file an issue`_. -How *does* ``natsort`` work? - If you don't want to read `How Does Natsort Work? `_, +How *does* `natsort`_ work? + If you don't want to read `How Does Natsort Work?`_, here is a quick primer. - ``natsort`` provides a `key function `_ - that can be passed to `list.sort() `_ - or `sorted() `_ in order to - modify the default sorting behavior. This key is generated on-demand with - the key generator ``natsort.natsort_keygen()``. ``natsort.natsorted()`` - is essentially a wrapper for the following code: + `natsort`_ provides a `key function`_ that can be passed to `list.sort()`_ + or `sorted()`_ in order to modify the default sorting behavior. This key + is generated on-demand with the key generator `natsort.natsort_keygen()`_. + `natsorted()_` is essentially a wrapper for the following code: .. code-block:: pycon @@ -337,35 +330,35 @@ How *does* ``natsort`` work? >>> sorted(['1', '10', '2'], key=natsort_key) ['1', '2', '10'] - Users can further customize ``natsort`` sorting behavior with the ``key`` + Users can further customize `natsort`_ sorting behavior with the ``key`` and/or ``alg`` options (see details in the `Further Customizing Natsort`_ section). - The key generated by ``natsort_keygen`` *always* returns a ``tuple``. It + The key generated by `natsort_keygen()`_ *always* returns a `tuple`_. It does so in the following way (*some details omitted for clarity*): 1. Assume the input is a string, and attempt to split it into numbers and non-numbers using regular expressions. Numbers are then converted into - either ``int`` or ``float``. + either `int`_ or `float`_. 2. If the above fails because the input is not a string, assume the input - is some other sequence (e.g. ``list`` or ``tuple``), and recursively + is some other sequence (e.g. `list`_ or `tuple`_), and recursively apply the key to each element of the sequence. 3. If the above fails because the input is not iterable, assume the input - is an ``int`` or ``float``, and just return the input in a ``tuple``. + is an `int`_ or `float`_, and just return the input in a `tuple`_. - Because a ``tuple`` is always returned, a ``TypeError`` should not be common - unless one tries to do something odd like sort an ``int`` against a ``list``. + Because a `tuple`_ is always returned, a `TypeError`_ should not be common + unless one tries to do something odd like sort an `int`_ against a `list`_. Shell script ------------ -``natsort`` comes with a shell script called ``natsort``, or can also be called +`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 3.7 or greater. +`natsort`_ requires Python 3.7 or greater. Optional Dependencies --------------------- @@ -374,20 +367,18 @@ fastnumbers +++++++++++ The most efficient sorting can occur if you install the -`fastnumbers `_ package +`fastnumbers>`_ package (version >=2.0.0); it helps with the string to number conversions. -``natsort`` will still run (efficiently) without the package, but if you need +`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. +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 -https://natsort.readthedocs.io/en/master/locale_issues.html for an explanation why. +It is recommended that you install `PyICU`_ if you wish to sort in a +locale-dependent manner, see this page on `locale issues`_ for an explanation why. Installation ------------ @@ -399,10 +390,8 @@ Use ``pip``! $ pip install natsort If you want to install the `Optional Dependencies`_, you can use the -`"extras" notation `_ -at installation time to install those dependencies as well - use ``fast`` for -`fastnumbers `_ and ``icu`` for -`PyICU `_. +`"extras" notation`_ at installation time to install those dependencies as +well - use ``fast`` for `fastnumbers>`_ and ``icu`` for `PyICU`_. .. code-block:: console @@ -414,11 +403,10 @@ at installation time to install those dependencies as well - use ``fast`` for How to Run Tests ---------------- -Please note that ``natsort`` is NOT set-up to support ``python setup.py test``. +Please note that `natsort`_ is NOT set-up to support ``python setup.py test``. -The recommended way to run tests is with `tox `_. -After installing ``tox``, running tests is as simple as executing the following -in the ``natsort`` directory: +The recommended way to run tests is with `tox`_. After installing ``tox``, +running tests is as simple as executing the following in the `natsort`_ directory: .. code-block:: console @@ -433,7 +421,7 @@ with ``tox --listenvs``. How to Build Documentation -------------------------- -If you want to build the documentation for ``natsort``, it is recommended to +If you want to build the documentation for `natsort`_, it is recommended to use ``tox``: .. code-block:: console @@ -445,7 +433,7 @@ This will place the documentation in ``build/sphinx/html``. Dropped Deprecated APIs ----------------------- -In ``natsort`` version 6.0.0, the following APIs and functions were removed +In `natsort`_ version 6.0.0, the following APIs and functions were removed - ``number_type`` keyword argument (deprecated since 3.4.0) - ``signed`` keyword argument (deprecated since 3.4.0) @@ -467,7 +455,7 @@ can run your code with the following flag $ python -Wdefault::DeprecationWarning my-code.py -By default ``DeprecationWarnings`` are not shown, but this will cause them +By default `DeprecationWarnings`_ are not shown, but this will cause them to be shown. Alternatively, you can just set the environment variable ``PYTHONWARNINGS`` to "default::DeprecationWarning" and then run your code. @@ -479,6 +467,41 @@ Seth M. Morton History ------- -Please visit the changelog -`on GitHub `_ or -`in the documentation `_. +Please visit the changelog `on GitHub`_ or `in the documentation`_. + +.. _natsort: https://natsort.readthedocs.io/en/stable/index.html +.. _natsorted(): https://natsort.readthedocs.io/en/stable/api.html#natsort.natsorted +.. _natsort_keygen(): https://natsort.readthedocs.io/en/stable/api.html#natsort.natsort_keygen +.. _realsorted(): https://natsort.readthedocs.io/en/stable/api.html#natsort.realsorted +.. _humansorted(): https://natsort.readthedocs.io/en/stable/api.html#natsort.humansorted +.. _os_sorted(): https://natsort.readthedocs.io/en/stable/api.html#natsort.os_sorted +.. _the ns enum: https://natsort.readthedocs.io/en/stable/api.html#natsort.ns +.. _fastnumbers: https://github.com/SethMMorton/fastnumbers +.. _sorted(): https://docs.python.org/3/library/functions.html#sorted +.. _list.sort(): https://docs.python.org/3/library/stdtypes.html#list.sort +.. _key function: https://docs.python.org/3/howto/sorting.html#key-functions +.. _locale: https://docs.python.org/3/library/locale.html +.. _int: https://docs.python.org/3/library/functions.html#int +.. _float: https://docs.python.org/3/library/functions.html#float +.. _str: https://docs.python.org/3/library/stdtypes.html#str +.. _bytes: https://docs.python.org/3/library/stdtypes.html#bytes +.. _list: https://docs.python.org/3/library/stdtypes.html#list +.. _tuple: https://docs.python.org/3/library/stdtypes.html#tuple +.. _TypeError: https://docs.python.org/3/library/exceptions.html#TypeError +.. _DeprecationWarnings: https://docs.python.org/3/library/exceptions.html#DeprecationWarning +.. _"extras" notation" https://packaging.python.org/tutorials/installing-packages/#installing-setuptools-extras +.. _PyICU: https://pypi.org/project/PyICU +.. _tox: https://tox.readthedocs.io/en/latest/ +.. _Examples and Recipes: https://natsort.readthedocs.io/en/stable/examples.html +.. _How Does Natsort Work?: https://natsort.readthedocs.io/en/stable/howitworks.html +.. _API: https://natsort.readthedocs.io/en/stable/api.html +.. _on GitHub: https://github.com/SethMMorton/natsort/blob/master/CHANGELOG.md +.. _in the documentation: https://natsort.readthedocs.io/en/stable/changelog.html +.. _file an issue: https://github.com/SethMMorton/natsort/issues/new +.. _look at this issue describing how to debug: https://github.com/SethMMorton/natsort/issues/13#issuecomment-50422375 +.. _controlling the case-sensitivity: https://natsort.readthedocs.io/en/stable/examples.html#case-sort +.. _sorting file paths correctly: https://natsort.readthedocs.io/en/stable/examples.html#path-sort +.. _allow custom sorting keys: https://natsort.readthedocs.io/en/stable/examples.html#custom-sort +.. _accounting for units: https://natsort.readthedocs.io/en/stable/examples.html#accounting-for-units-when-sorting +.. _these version sorting examples: https://natsort.readthedocs.io/en/stable/examples.html#rc-sorting +.. _locale issues: https://natsort.readthedocs.io/en/stable/locale_issues.html \ No newline at end of file -- cgit v1.2.1