Add natural_sorted Python function

Author: bdrung

README.md

@@ -3,6 +3,12 @@ Various code snippets
 
 This repository contains various code snippet that are used in several places.
 
+natural_sorted
+--------------
+
+The Python function `natural_sorted` behaves like the built-in function
+`sorted`, but it returns a naturally sorted list instead.
+
 python_tests
 ------------
 

natural_sorted.py

@@ -0,0 +1,44 @@
+# Copyright (C) 2018, Benjamin Drung <[email protected]>
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+import re
+
+def natural_sorted(iterable, key=None, reverse=False):
+    """Return a new naturally sorted list from the items in *iterable*.
+
+    The returned list is in natural sort order. The string is ordered
+    lexicographically (using the Unicode code point number to order individual
+    characters), except that multi-digit numbers are ordered as a single character.
+
+    Has two optional arguments which must be specified as keyword arguments.
+
+    *key* specifies a function of one argument that is used to extract a comparison
+    key from each list element: ``key=str.lower``.  The default value is ``None``
+    (compare the elements directly).
+
+    *reverse* is a boolean value.  If set to ``True``, then the list elements are
+    sorted as if each comparison were reversed.
+
+    The :func:`natural_sorted` function is guaranteed to be stable. A sort is
+    stable if it guarantees not to change the relative order of elements that
+    compare equal --- this is helpful for sorting in multiple passes (for
+    example, sort by department, then by salary grade).
+    """
+    prog = re.compile(r"(\d+)")
+
+    def alphanum_key(element):
+        """Split given key in list of strings and digits"""
+        return [int(c) if c.isdigit() else c for c in prog.split(key(element) if key else element)]
+
+    return sorted(iterable, key=alphanum_key, reverse=reverse)