First release

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 JavaScriptDude
+Copyright (c) 2022 Timothy C. Quinn <javascriptdude [at] protonmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+include pyproject.toml

README.md

@@ -0,0 +1,208 @@
+## `multisort` - NoneType Safe Multi Column Sorting
+
+Simplified multi-column sorting of lists of tuples, dicts, lists or objects that are NoneType safe.
+
+### Installation
+
+```
+python3 -m pip install multisort
+```
+
+### Dependencies
+None
+
+### Performance
+Average over 10 iterations with 500 rows.
+Test | Secs
+---|---
+cmp_func|0.0054
+pandas|0.0061
+reversor|0.0149
+msorted|0.0179
+
+As you can see, if the `cmp_func` is by far the fastest methodology as long as the number of cells in the table are 500 rows for 5 columns. However for larger data sets, `pandas` is the performance winner and scales extremely well. In such large dataset cases, where performance is key, `pandas` should be the first choice.
+
+The surprising thing from testing is that `cmp_func` far outperforms `reversor` which which is the only other methodology for multi-columnar sorting that can handle `NoneType` values.
+
+### Note on `NoneType` and sorting
+If your data may contain None, it would be wise to ensure your sort algorithm is tuned to handle them. This is because sorted uses `<` comparisons; which is not supported by `NoneType`. For example, the following error will result: `TypeError: '>' not supported between instances of 'NoneType' and 'str'`.
+
+### Methodologies
+Method|Descr|Notes
+---|---|---
+cmp_func|Multi column sorting in the model `java.util.Comparator`|Fastest for small to medium size data
+reversor|Enable multi column sorting with column specific reverse sorting|Medium speed. [Source](https://stackoverflow.com/a/56842689/286807)
+msorted|Simple one-liner designed after `multisort` [example from python docs](https://docs.python.org/3/howto/sorting.html#sort-stability-and-complex-sorts)|Slowest of the bunch but not by much
+
+
+
+### Dictionary Examples
+For data:
+```
+rows_dict = [
+     {'idx': 0, 'name': 'joh', 'grade': 'C', 'attend': 100}
+    ,{'idx': 1, 'name': 'jan', 'grade': 'a', 'attend': 80}
+    ,{'idx': 2, 'name': 'dav', 'grade': 'B', 'attend': 85}
+    ,{'idx': 3, 'name': 'bob' , 'grade': 'C', 'attend': 85}
+    ,{'idx': 4, 'name': 'jim' , 'grade': 'F', 'attend': 55}
+    ,{'idx': 5, 'name': 'joe' , 'grade': None, 'attend': 55}
+]
+```
+
+### `msorted`
+Sort rows_dict by _grade_, descending, then _attend_, ascending and put None first in results:
+```
+from multisort import msorted
+rows_sorted = msorted(rows_dict, [
+         ('grade', {'reverse': False, 'none_first': True})
+        ,'attend'
+])
+
+```
+
+Sort rows_dict by _grade_, descending, then _attend_ and call upper() for _grade_:
+```
+from multisort import msorted
+rows_sorted = msorted(rows_dict, [
+         ('grade', {'reverse': False, 'clean': lambda s:None if s is None else s.upper()})
+        ,'attend'
+])
+
+```
+
+### `sorted` with `reversor`
+Sort rows_dict by _grade_, descending, then _attend_ and call upper() for _grade_:
+```
+rows_sorted = sorted(rows_dict, key=lambda o: (
+             reversor(None if o['grade'] is None else o['grade'].upper())
+            ,o['attend'])
+))
+```
+
+
+### `sorted` with `cmp_func`
+Sort rows_dict by _grade_, descending, then _attend_ and call upper() for _grade_:
+```
+def cmp_student(a,b):
+    k='grade'; va=a[k]; vb=b[k]
+    if va != vb: 
+        if va is None: return -1
+        if vb is None: return 1
+        return -1 if va > vb else 1
+    k='attend'; va=a[k]; vb=b[k]; 
+    if va != vb: return -1 if va < vb else 1
+    return 0
+rows_sorted = sorted(rows_dict, key=cmp_func(cmp_student), reverse=True)
+```
+
+
+
+### Object Examples
+For data:
+```
+class Student():
+    def __init__(self, idx, name, grade, attend):
+        self.idx = idx
+        self.name = name
+        self.grade = grade
+        self.attend = attend
+    def __str__(self): return f"name: {self.name}, grade: {self.grade}, attend: {self.attend}"
+    def __repr__(self): return self.__str__()
+
+rows_obj = [
+     Student(0, 'joh', 'C', 100)
+    ,Student(1, 'jan', 'a', 80)
+    ,Student(2, 'dav', 'B', 85)
+    ,Student(3, 'bob', 'C', 85)
+    ,Student(4, 'jim', 'F', 55)
+    ,Student(5, 'joe', None, 55)
+]
+```
+
+### `msorted`
+(Same syntax as with 'dict' example)
+
+
+### `sorted` with `reversor`
+Sort rows_obj by _grade_, descending, then _attend_ and call upper() for _grade_:
+```
+rows_sorted = sorted(rows_obj, key=lambda o: (
+             reversor(None if o.grade is None else o.grade.upper())
+            ,o.attend)
+))
+```
+
+
+### `sorted` with `cmp_func`
+Sort rows_obj by _grade_, descending, then _attend_ and call upper() for _grade_:
+```
+def cmp_student(a,b):
+    if a.grade != b.grade: 
+        if a.grade is None: return -1
+        if b.grade is None: return 1
+        return -1 if a.grade > b.grade else 1
+    if a.attend != b.attend: 
+        return -1 if a.attend < b.attend else 1
+    return 0
+rows_sorted = sorted(rows_obj, key=cmp_func(cmp_student), reverse=True)
+```
+
+
+### List / Tuple Examples
+For data:
+```
+rows_tuple = [
+     (0, 'joh', 'a'  , 100)
+    ,(1, 'joe', 'B'  , 80)
+    ,(2, 'dav', 'A'  , 85)
+    ,(3, 'bob', 'C'  , 85)
+    ,(4, 'jim', None , 55)
+    ,(5, 'jan', 'B'  , 70)
+]
+(COL_IDX, COL_NAME, COL_GRADE, COL_ATTEND) = range(0,4)
+```
+
+### `msorted`
+Sort rows_tuple by _grade_, descending, then _attend_, ascending and put None first in results:
+```
+from multisort import msorted
+rows_sorted = msorted(rows_tuple, [
+         (COL_GRADE, {'reverse': False, 'none_first': True})
+        ,COL_ATTEND
+])
+
+```
+
+
+### `sorted` with `reversor`
+Sort rows_tuple by _grade_, descending, then _attend_ and call upper() for _grade_:
+```
+rows_sorted = sorted(rows_tuple, key=lambda o: (
+             reversor(None if o[COL_GRADE] is None else o[COL_GRADE].upper())
+            ,o[COL_ATTEND])
+))
+```
+
+
+### `sorted` with `cmp_func`
+Sort rows_tuple by _grade_, descending, then _attend_ and call upper() for _grade_:
+```
+def cmp_student(a,b):
+    k=COL_GRADE; va=a[k]; vb=b[k]
+    if va != vb: 
+        if va is None: return -1
+        if vb is None: return 1
+        return -1 if va > vb else 1
+    k=COL_ATTEND; va=a[k]; vb=b[k]; 
+    if va != vb: 
+        return -1 if va < vb else 1
+    return 0
+rows_sorted = sorted(rows_tuple, key=cmp_func(cmp_student), reverse=True)
+```
+
+### Tests / Samples
+Name|Descr|Other
+---|---|---
+tests/test_msorted.py|msorted unit tests|- 
+tests/performance_tests.py|Tunable performance tests using asyncio | requires pandas
+tests/hand_test.py|Hand testing|-

dev.env

@@ -0,0 +1 @@
+PYTHONPATH=./src:${PYTHONPATH}

pyproject.toml

@@ -0,0 +1,33 @@
+[tool.poetry]
+name = "multisort"
+version = "0.1.0"
+description = "NoneType Safe Multi Column Sorting For Python"
+license = "MIT"
+authors = ["Timothy C. Quinn"]
+readme = "README.md"
+homepage = "https://pypi.org/project/multisort"
+repository = "https://github.com/JavaScriptDude/multisort"
+classifiers = [
+    'Development Status :: 4 - Beta',
+    'Environment :: Console',
+    'Intended Audience :: Developers',
+    'Operating System :: POSIX :: Linux',
+    'Operating System :: POSIX :: BSD',
+    'Operating System :: POSIX :: SunOS/Solaris',
+    'Operating System :: MacOS :: MacOS X',
+    'Programming Language :: Python :: 3 :: Only',
+    'Programming Language :: Python :: 3.7',
+    'Programming Language :: Python :: 3.8',
+    'Programming Language :: Python :: 3.9',
+    'Programming Language :: Python :: 3.10',
+    'Topic :: Utilities',
+]
+
+[tool.poetry.dependencies]
+python = "^3.7.9"
+
+[tool.poetry.dev-dependencies]
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"

src/multisort/__init__.py

@@ -0,0 +1 @@
+from .multisort import msorted, cmp_func, reversor

src/multisort/multisort.py

@@ -0,0 +1,110 @@
+#########################################
+# .: multisort.py :.
+# Simplified Multi-Column Sorting For Lists of records
+# Installation:
+# . pip install multisort
+# Author: Timothy C. Quinn
+# Home: https://pypi.org/project/multisort
+# Licence: MIT
+#########################################
+from functools import cmp_to_key
+cmp_func = cmp_to_key
+
+
+# .: msorted :.
+# spec is a list one of the following
+#    <key>
+#    (<key>,)
+#    (<key>, <opts>)
+# where:
+#  <key> Property, Key or Index for 'column' in row
+#  <opts> dict. Options:
+#       reverse: opt - reversed sort (defaults to False)
+#       clean: opt - callback to clean / alter data in 'field'
+#       none_first: opt - If True, None will be at top of sort. Default is False (bottom)
+class Comparator:
+    @classmethod
+    def new(cls, *args):
+        if len(args) == 1 and isinstance(args[0], (int,str)):
+            _c = Comparator(spec=args[0])
+        else:
+            _c = Comparator(spec=args)
+        return cmp_to_key(_c._compare_a_b)
+
+    def __init__(self, spec): 
+        if isinstance(spec, (int, str)):
+            self.spec = ( (spec, False, None, False), )
+        else:
+            a=[]
+            for s_c in spec:
+                if isinstance(s_c, (int, str)):
+                    a.append((s_c, None, None, False))
+                else:
+                    assert isinstance(s_c, tuple) and len(s_c) in (1,2),\
+                        f"Invalid spec. Must have 1 or 2 params per record. Got: {s_c}"
+                    if len(s_c) == 1:
+                        a.append((s_c[0], None, None, False))
+                    elif len(s_c) == 2:
+                        s_opts = s_c[1]
+                        assert not s_opts is None and isinstance(s_opts, dict), f"Invalid Spec. Second value must be a dict. Got {getClassName(s_opts)}"
+                        a.append((s_c[0], s_opts.get('reverse', False), s_opts.get('clean', None), s_opts.get('none_first', False)))
+
+            self.spec = a
+
+    def _compare_a_b(self, a, b):
+        if a is None: return 1
+        if b is None: return -1
+        for k, desc, clean, none_first in self.spec:
+            try:
+                try:
+                    va = a[k]; vb = b[k]
+                except Exception as ex:
+                    va = getattr(a, k); vb = getattr(b, k)
+
+            except Exception as ex:
+                raise KeyError(f"Key {k} is not available in object(s) given a: {a.__class__.__name__}, b: {a.__class__.__name__}")
+
+            if clean:
+                va = clean(va)
+                vb = clean(vb)
+
+            if va != vb:
+                if va is None: return -1 if none_first else 1
+                if vb is None: return 1 if none_first else -1
+                if desc:
+                    return -1 if va > vb else 1
+                else:
+                    return 1 if va > vb else -1
+
+        return 0
+
+
+def msorted(rows, spec, reverse:bool=False):
+    if isinstance(spec, (int, str)):
+        _c = Comparator.new(spec)
+    else:
+        _c = Comparator.new(*spec)
+    return sorted(rows, key=_c, reverse=reverse)
+
+# For use in the multi column sorted syntax to sort by 'grade' and then 'attend' descending
+# dict example:
+#    rows_sorted = sorted(rows, key=lambda o: ((None if o['grade'] is None else o['grade'].lower()), reversor(o['attend'])), reverse=True)
+# object example:
+#    rows_sorted = sorted(rows, key=lambda o: ((None if o.grade is None else o.grade.lower()), reversor(o.attend)), reverse=True)
+# list, tuple example:
+#    rows_sorted = sorted(rows, key=lambda o: ((None if o[COL_GRADE] is None else o[COL_GRADE].lower()), reversor(o[COL_ATTEND])), reverse=True)
+#    where: COL_GRADE and COL_ATTEND are column indexes for values
+class reversor:
+    def __init__(self, obj):
+        self.obj = obj
+    def __eq__(self, other):
+        return other.obj == self.obj
+    def __lt__(self, other):
+        return False if self.obj is None else \
+               True if other.obj is None else \
+               other.obj < self.obj
+
+
+def getClassName(o):
+    return None if o == None else type(o).__name__
+