Refactor API

Author: JavaScriptDude

README.md

@@ -56,45 +56,35 @@ Sort rows_dict by _grade_, descending, then _attend_, ascending and put None fir
 ```
 from multisort import multisort
 rows_sorted = multisort(rows_dict, [
-         ('grade', {'reverse': False})
-        ,'attend'
+        ('grade', reverse=False),
+        ('attend')
 ])
 
 ```
 Sort rows_dict by _grade_, descending, then _attend_ and call upper() for _grade_:
 ```
 from multisort import multisort
 rows_sorted = multisort(rows_dict, [
-         ('grade', {'reverse': False, 'clean': lambda s: None if s is None else s.upper()})
-        ,'attend'
+        mscol('grade', 'reverse'=False, clean=lambda s: None if s is None else s.upper()),
+        ('attend')
 ])
 
 ```
 `multisort` parameters:
 option|dtype|description
 ---|---|---
-`key`|int or str|Key to access data. int for tuple or list
-`spec`|str, int, list|Sort specification. Can be as simple as a column key / index
+`rows`|int or str|Key to access data. int for tuple or list
+`spec`|str, int, list|Sort specification. Can be as simple as a column key / index or `mscol`
 `reverse`|bool|Reverse order of final sort (defalt = False)
 
-`multisort` `spec` options:
+`multisort` spec options:
 option|dtype|description
 ---|---|---
-reverse|bool|Reverse sort of column
-clean|func|Function / lambda to clean the value. These calls can cause a significant slowdown.
-required|bool|Default True. If false, will substitute None or default if key not found (not applicable for list or tuple rows)
-default|any|Value to substitute if required==False and key does not exist or None is found. Can be used to achive similar functionality to pandas `na_position`
-
-
-
-### `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'])
-))
-```
+`key`|int or str|Key to access data. int for tuple or list
+`reverse`|bool|Reverse sort of column
+`clean`|func|Function / lambda to clean the value. These calls can cause a significant slowdown.
+`required`|bool|Default True. If false, will substitute None or default if key not found (not applicable for list or tuple rows)
+`default`|any|Value to substitute if required==False and key does not exist or None is found. Can be used to achive similar functionality to pandas `na_position`
 
 
 ### `sorted` with `cmp_func`
@@ -112,7 +102,17 @@ def cmp_student(a,b):
 rows_sorted = sorted(rows_dict, key=cmp_func(cmp_student), reverse=True)
 ```
 
-
+### For reference: `superfast` methodology with list of dicts:
+```
+def key_grade(student):
+    grade = student['grade']
+    return grade is None, grade
+def key_attend(student):
+    attend = student['attend']
+    return attend is None, attend
+students_sorted = sorted(students, key=key_attend)
+students_sorted.sort(key=key_grade, reverse=True)
+```
 
 ### Object Examples
 For data:
@@ -140,16 +140,6 @@ rows_obj = [
 (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_:
 ```
@@ -184,23 +174,12 @@ Sort rows_tuple by _grade_, descending, then _attend_, ascending and put None fi
 ```
 from multisort import multisort
 rows_sorted = multisort(rows_tuple, [
-         (COL_GRADE, {'reverse': False, 'none_first': True})
-        ,COL_ATTEND
+        mscol(COL_GRADE, reverse=False, default='0'),
+        (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_:
 ```

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "multisort"
-version = "0.1.2"
+version = "0.1.3"
 description = "NoneType Safe Multi Column Sorting For Python"
 license = "MIT"
 authors = ["Timothy C. Quinn"]

src/multisort/__init__.py

@@ -1 +1 @@
-from .multisort import multisort, cmp_func, reversor
+from .multisort import multisort, mscol, cmp_func, reversor

src/multisort/multisort.py

@@ -14,32 +14,32 @@
 # .: multisort :.
 # 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'
+#    spec
+# spec options:
+#   key Property, Key or Index for 'column' in row
+#   reverse: opt - reversed sort (defaults to False)
+#   clean: opt - callback to clean / alter data in 'field' 
+#   default: Value to default if None is found or required = False
+#   required: Will not fail if key not found
+#   Use mscol helper to ease passing of variables or just pass lists of args:
+#     spec=mscol('colname1', reverse=True), mscol('colname2', reverse=True)]
+#       -or-
+#     spec=[('colname1', True),('colname2',True)]
+
+def mscol(key, reverse=False, clean=None, default=None, required=True):
+    return (key, reverse, clean, default, required)
+
 def multisort(rows, spec, reverse:bool=False):
-    key=clean=rows_sorted=default=None
-    col_reverse=False
-    required=True
-    for s_c in reversed([spec] if isinstance(spec, (int, str)) else spec):
-        if isinstance(s_c, (int, str)):
-            key = s_c
+    rows_sorted=None
+    if isinstance(spec, (int, str)): spec = [mscol(spec)]
+    for spec_c in reversed(spec):
+        spec_c_t = type(spec_c)
+        if spec_c_t in(int, str):
+            (key, col_reverse, clean, default, required) = (spec_c, False, None, None, True)
         else:
-            if len(s_c) == 1:
-                key = s_c[0]
-            elif len(s_c) == 2:
-                key = s_c[0]
-                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)}"
-                col_reverse = s_opts.get('reverse', False)
-                clean = s_opts.get('clean', None)
-                default = s_opts.get('default', None)
-                required = s_opts.get('required', True)
-
+            assert spec_c_t in (list, tuple), f"Invalid spec. Got: {spec_c_t.__name__}. See docs"
+            if len(spec_c) < 5: spec_c = mscol(*spec_c)
+            (key, col_reverse, clean, default, required) = spec_c
         def _sort_column(row): # Throws MSIndexError, MSKeyError
             ex1=None
             try:
@@ -94,7 +94,6 @@ def _sort_column(row): # Throws MSIndexError, MSKeyError
 
 
     return reversed(rows_sorted) if reverse else rows_sorted
-        
 
 class MultiSortBaseExc(Exception):
     def __init__(self, msg, row, cause):

tests/hand_test.py

@@ -1,16 +1,17 @@
 import sys
-from multisort import multisort, cmp_func, reversor
+from multisort import multisort, mscol, cmp_func, reversor
 import test_util as util
 pc = util.pc
 
 def main():
-    # test_multisort_dict_single()
-    # test_multisort_obj_single()
-    # test_multisort_tuple_single()
+
+    test_multisort_dict_single()
+    test_multisort_obj_single()
+    test_multisort_tuple_single()
 
     test_multisort_dict_multi()
-    # test_multisort_obj_multi()
-    # test_multisort_tuple_multi()
+    test_multisort_obj_multi()
+    test_multisort_tuple_multi()
 
 
 students_dict = [
@@ -69,19 +70,25 @@ def test_multisort_tuple_single():
 
 def test_multisort_dict_multi():
     _sorted = multisort(students_dict, [
-             ('grade', {'reverse': True, 'clean': lambda s: None if s is None else s.upper(), 'default': '0', 'required': True}),
+             mscol('grade', reverse=True, clean=lambda s: None if s is None else s.upper(), default='0', required=True),
             # ('attend', {'reverse': False}),
     ], reverse=False)
     _print_stud(_sorted)
 
 
 def test_multisort_obj_multi():
-    _sorted = multisort(students_obj, [('grade', {'reverse': True}), 'attend'], reverse=False)
+    _sorted = multisort(students_obj, [
+            mscol('grade', reverse=True), 
+            mscol('attend')
+    ], reverse=False)
     _print_stud(_sorted)
 
 
 def test_multisort_tuple_multi():
-    _sorted = multisort(student_tuple, [(COL_GRADE, {'reverse': True}), COL_ATTEND], reverse=False)
+    _sorted = multisort(student_tuple, [
+            mscol(COL_GRADE, reverse=True), 
+            mscol(COL_ATTEND)
+    ], reverse=False)
     _print_stud(_sorted)
 
 

tests/performance_tests.py

@@ -2,7 +2,7 @@
 import pandas
 from random import randint
 from operator import itemgetter
-from multisort import multisort, cmp_func, reversor
+from multisort import multisort, mscol, cmp_func, reversor
 import test_util as util
 pc = util.pc
 
@@ -14,7 +14,7 @@
     ,{'idx': 4, 'name': 'jim' , 'grade': 'F', 'attend': 55}
     ,{'idx': 5, 'name': 'joe' , 'grade': None, 'attend': 55}
 ]
-ITERATIONS = 5
+ITERATIONS = 10
 EXTRA_ROW = 1000
 
 def main():
@@ -70,28 +70,25 @@ def cmp_student(a,b):
 
     return ('cmp_func', sw.elapsed(prec=7))
 
-
-
 async def run_multisort(rows):
     sw = util.StopWatch()
     for i in range(0,ITERATIONS):
-        rows_sorted = multisort(rows, spec=(
-                ('grade', {'reverse': True, 'clean': lambda v: None if v is None else v.lower()})
-               ,('attend', {'reverse': True})
-        ), reverse=True)
+        def clean_grade(v): return v.lower()
+        rows_sorted = multisort(rows, [
+                mscol('grade', reverse=True, clean=clean_grade),
+                mscol('attend', reverse=True),
+        ], reverse=True)
     return ('multisort w/ clean', sw.elapsed(prec=7))
 
-
 async def run_multisort_noclean(rows):
     sw = util.StopWatch()
     for i in range(0,ITERATIONS):
-        rows_sorted = multisort(rows, spec=(
-                ('grade', {'reverse': True})
-               ,('attend', {'reverse': True})
-        ), reverse=True)
+        rows_sorted = multisort(rows, [
+                mscol('grade', reverse=True),
+                mscol('attend', reverse=True),
+        ], reverse=True)
     return ('multisort noclean', sw.elapsed(prec=7))
 
-
 async def run_reversor(rows):
     sw = util.StopWatch()
     for i in range(0,ITERATIONS):
@@ -119,7 +116,8 @@ def key_grade(student):
         grade = student['grade']
         return grade is None, grade
     def key_attend(student):
-        return student['attend']
+        attend = student['attend']
+        return attend is None, attend
     students_sorted = sorted(students, key=key_attend)
     students_sorted.sort(key=key_grade, reverse=True)
 

tests/test_multisort.py

@@ -1,6 +1,6 @@
 import sys
 import unittest
-from multisort import multisort
+from multisort import multisort, mscol
 import test_util as util
 pc = util.pc
 
@@ -23,14 +23,14 @@ def clean_grade(v):
 
 
 MSORTED_TESTS=[
-    ( (2,0,5,1,3,4), [(COL_GRADE, {'reverse': False, 'clean': clean_grade}) , (COL_ATTEND, {'reverse': False})]),
-    ( (0,2,1,5,3,4), [(COL_GRADE, {'reverse': False, 'clean': clean_grade}) , (COL_ATTEND, {'reverse': True})]),
-    ( (0,2,1,5,3,4), [(COL_GRADE, {'reverse': False, 'clean': clean_grade}) , (COL_ATTEND, {'reverse': True})]),
-    ( (4,3,1,5,0,2), [(COL_GRADE, {'reverse': True , 'clean': clean_grade}) , (COL_ATTEND, {'reverse': True})]),
-    ( (4,3,5,1,2,0), [(COL_GRADE, {'reverse': True , 'clean': clean_grade}) , (COL_ATTEND, {'reverse': False})]),
+    ( (2,0,5,1,3,4), [mscol(COL_GRADE, reverse=False, clean=clean_grade) , mscol(COL_ATTEND, reverse=False)]),
+    ( (0,2,1,5,3,4), [mscol(COL_GRADE, reverse=False, clean=clean_grade) , mscol(COL_ATTEND, reverse=True)]),
+    ( (0,2,1,5,3,4), [mscol(COL_GRADE, reverse=False, clean=clean_grade) , mscol(COL_ATTEND, reverse=True)]),
+    ( (4,3,1,5,0,2), [mscol(COL_GRADE, reverse=True , clean=clean_grade) , mscol(COL_ATTEND, reverse=True)]),
+    ( (4,3,5,1,2,0), [mscol(COL_GRADE, reverse=True , clean=clean_grade) , mscol(COL_ATTEND, reverse=False)]),
     ( (2,1,5,3,0,4), COL_GRADE),
     ( (2,1,5,3,0,4), [COL_GRADE]),
-    ( (2,5,1,3,0,4), [COL_GRADE, COL_NAME]),
+    ( (4,0,3,5,1,2), [[COL_GRADE, True], COL_NAME]),
 ]
 
 
@@ -158,16 +158,10 @@ def test_tuple_of_objects(self):
 
 def norm_spec_item(spec_c):
     if isinstance(spec_c, (int, str)):
-        return (spec_c, None, None)
+        return (spec_c, False, None, None, True)
     else:
-        assert isinstance(spec_c, tuple) and len(spec_c) in (1,2),\
-            f"Invalid spec. Must have 1 or 2 params per record. Got: {spec_c}"
-        if len(spec_c) == 1:
-            return (spec_c[0], None, None)
-        elif len(spec_c) == 2:
-            s_opts = spec_c[1]
-            assert not s_opts is None and isinstance(s_opts, dict), f"Invalid Spec. Second value must be a dict. Got {util.getClassName(s_opts)}"
-            return (spec_c[0], s_opts.get('reverse', False), s_opts.get('clean', None))
+        if len(spec_c) < 5: return mscol(*spec_c)
+        return spec_c
 
 
 def dump_sort(stest_no, spec, rows, rows_as, row_as, expected, reverse):
@@ -179,13 +173,13 @@ def dump_sort(stest_no, spec, rows, rows_as, row_as, expected, reverse):
         sb.a(spec).a(" (a)")
     else:
         for i, spec_c in enumerate(spec):
-            (key, desc, clean) = norm_spec_item(spec_c)
+            (key, col_reverse, clean, default, required) = norm_spec_item(spec_c)
             if i > 0: sb.a(", ")
             if indexable:
                 sb.a(STUDENT_COLS[key])
             else:
                 sb.a(key)
-            sb.a(' (d)' if desc else ' (a)')
+            sb.a(' (d)' if col_reverse else ' (a)')
 
     if reverse: sb.a(' (reversed)')