add distinct_by(), except_by() to Enumerable class; removed distinct_by() from MoreEnumerable; renamed except_by() to except_by2() for MoreEnumerable

an essential breaking change

Author: cleoold

doc/api/more/types_linq.more.more_enumerable.rst

@@ -12,8 +12,9 @@ MoreEnumerable provides more query methods. Instances of this class can be creat
 constructing, using as_more(), or invoking MoreEnumerable methods that return MoreEnumerable
 instead of Enumerable.
 
-Some APIs are subject to change as updates to .NET (6) are happening - they will move to Enumerable
-class if one day they appear in the official .NET doc.
+These APIs may have breaking changes more frequently than those in Enumerable class because updates
+in .NET are happening and sometimes ones of these APIs could be moved to Enumerable with modification,
+or changed to accommodate changes to Enumerable.
 
 Bases
 ======
@@ -82,25 +83,6 @@ Returns the original MoreEnumerable reference.
 
 ----
 
-instancemethod ``distinct_by(key_selector)``
-----------------------------------------------
-
-Parameters
-  - `key_selector` (``Callable[[TSource_co], object]``)
-
-Returns
-  - ``MoreEnumerable[TSource_co]``
-
-Returns distinct elements from the sequence where "distinctness" is determined by the value
-returned by the selector.
-
-Example
-    >>> ints = [1, 4, 5, 6, 4, 3, 1, 99]
-    >>> MoreEnumerable(ints).distinct_by(lambda x: x // 2).to_list()
-    [1, 4, 6, 3, 99]
-
-----
-
 instancemethod ``enumerate(start=0)``
 ---------------------------------------
 
@@ -120,8 +102,8 @@ Example
 
 ----
 
-instancemethod ``except_by(second, key_selector)``
-----------------------------------------------------
+instancemethod ``except_by2(second, key_selector)``
+-----------------------------------------------------
 
 Parameters
   - `second` (``Iterable[TSource_co]``)
@@ -136,7 +118,7 @@ determines "distinctness". Note the second iterable is homogenous to self.
 Example
     >>> first = [(16, 'x'), (9, 'y'), (12, 'd'), (16, 't')]
     >>> second = [(24, 'd'), (77, 'y')]
-    >>> MoreEnumerable(first).except_by(second, lambda x: x[1]).to_list()
+    >>> MoreEnumerable(first).except_by2(second, lambda x: x[1]).to_list()
     [(16, 'x'), (16, 't')]
 
 ----

doc/api/types_linq.enumerable.rst

@@ -680,6 +680,25 @@ Example
 
 ----
 
+instancemethod ``distinct_by(key_selector)``
+----------------------------------------------
+
+Parameters
+  - `key_selector` (``Callable[[TSource_co], object]``)
+
+Returns
+  - ``Enumerable[TSource_co]``
+
+Returns distinct elements from the sequence where "distinctness" is determined by the value
+returned by the selector.
+
+Example
+    >>> ints = [1, 4, 5, 6, 4, 3, 1, 99]
+    >>> Enumerable(ints).distinct_by(lambda x: x // 2).to_list()
+    [1, 4, 6, 3, 99]
+
+----
+
 instancemethod ``element_at(index)``
 --------------------------------------
 
@@ -777,6 +796,27 @@ Example
 
 ----
 
+instancemethod ``except_by[TKey](second, key_selector)``
+----------------------------------------------------------
+
+Parameters
+  - `second` (``Iterable[TKey]``)
+  - `key_selector` (``Callable[[TSource_co], TKey]``)
+
+Returns
+  - ``Enumerable[TSource_co]``
+
+Produces the set difference of two sequences: self - second, according to a key selector that
+determines "distinctness".
+
+Example
+    >>> first = [(16, 'x'), (9, 'y'), (12, 'd'), (16, 't')]
+    >>> second = ['y', 'd']
+    >>> Enumerable(first).except_by(second, lambda x: x[1]).to_list()
+    [(16, 'x'), (16, 't')]
+
+----
+
 instancemethod ``first()``
 ----------------------------
 

doc/api_spec.py

@@ -58,9 +58,11 @@ class ClassSpec(TypedDict):
                     'count',
                     'default_if_empty',
                     'distinct',
+                    'distinct_by',
                     'element_at',
                     'empty',
                     'except1',
+                    'except_by',
                     'first',
                     'first2',
                     'group_by',
@@ -188,9 +190,8 @@ class ClassSpec(TypedDict):
                 'methods': {
                     'aggregate_right',
                     'as_more',
-                    'distinct_by',
                     'enumerate',
-                    'except_by',
+                    'except_by2',
                     'flatten',
                     'flatten2',
                     'for_each',

tests/test_more_usage.py

@@ -71,25 +71,19 @@ def test_enumerate_start(self):
         assert en.enumerate(1).to_list() == [(1, '2'), (2, '4'), (3, '6')]
 
 
-class TestDistinctByMethod:
-    def test_distinct_by(self):
-        en = MoreEnumerable([1, 4, 5, 6, 4, 3, 1, 99])
-        assert en.distinct_by(lambda x: x // 2).to_list() == [1, 4, 6, 3, 99]
-
-
-class TestExceptByMethod:
-    def test_except_by(self):
+class TestExceptBy2Method:
+    def test_except_by2(self):
         en = MoreEnumerable(['aaa', 'bb', 'c', 'dddd'])
-        assert en.except_by(['xx', 'y'], len).to_list() == ['aaa', 'dddd']
+        assert en.except_by2(['xx', 'y'], len).to_list() == ['aaa', 'dddd']
 
     def test_unhashable(self):
         en = MoreEnumerable([['aaa'], ['bb'], ['c'], ['dddd']])
-        q = en.except_by([['xx'], ['y']], lambda x: len(x[0]))
+        q = en.except_by2([['xx'], ['y']], lambda x: len(x[0]))
         assert q.to_list() == [['aaa'], ['dddd']]
 
     def test_no_repeat(self):
         en = MoreEnumerable(['aaa', 'bb', 'c', 'dddd', 'aaa'])
-        assert en.except_by(['xx', 'y'], len).to_list() == ['aaa', 'dddd']
+        assert en.except_by2(['xx', 'y'], len).to_list() == ['aaa', 'dddd']
 
     def test_remove_nothing(self):
         i = -1
@@ -98,7 +92,7 @@ def selector(_):
             return i
         strs = ['aaa', 'bb', 'c', 'dddd', 'dddd']
         en = MoreEnumerable(strs)
-        assert en.except_by((), selector).to_list() == strs
+        assert en.except_by2((), selector).to_list() == strs
 
 
 class TestFlattenMethod:

tests/test_usage.py

@@ -344,6 +344,12 @@ def test_distinct(self):
         assert distinct == [1, 4, 5, 6, 3, 99]
 
 
+class TestDistinctByMethod:
+    def test_distinct_by(self):
+        en = Enumerable([1, 4, 5, 6, 4, 3, 1, 99])
+        assert en.distinct_by(lambda x: x // 2).to_list() == [1, 4, 6, 3, 99]
+
+
 class TestReverseMethod:
     def test_delayed(self):
         gen = (i for i in range(5))
@@ -452,6 +458,18 @@ def test_remove_nothing(self):
         assert exc.to_list() == ints
 
 
+class TestExceptByMethod:
+    def test_except_by1(self):
+        first = [(16, 'x'), (9, 'y'), (12, 'd'), (16, 't')]
+        en = Enumerable(first)
+        exc = en.except_by(['y', 'd'], lambda x: x[1])
+        assert exc.to_list() == [(16, 'x'), (16, 't')]
+
+    def test_no_repeat(self):
+        en = Enumerable(['aaa', 'bb', 'c', 'dddd', 'aaa'])
+        assert en.except_by([2, 1], len).to_list() == ['aaa', 'dddd']
+
+
 class TestFirstMethod:
     def test_first_overload1_yes(self):
         lst = ('a', 'b', 5, 'c')

types_linq/enumerable.py

@@ -319,6 +319,9 @@ def inner():
     def distinct(self) -> Enumerable[TSource_co]:
         return self.except1(())
 
+    def distinct_by(self, key_selector: Callable[[TSource_co], object]) -> Enumerable[TSource_co]:
+        return self.except_by((), key_selector)
+
     def element_at(self, index: int, *args: TDefault) -> Union[TSource_co, TDefault]:
         if len(args) == 0:
             return self._getitem_impl(index, fallback=True)  # type: ignore
@@ -334,12 +337,19 @@ def empty() -> Enumerable[TSource_co]:
         return Enumerable(())
 
     def except1(self, second: Iterable[TSource_co]) -> Enumerable[TSource_co]:
+        return self.except_by(second, lambda x: x)
+
+    def except_by(self,
+        second: Iterable[TKey],
+        key_selector: Callable[[TSource_co], TKey],
+    ) -> Enumerable[TSource_co]:
         def inner():
             s = ComposeSet(second)
             for elem in self:
-                if elem in s:
+                key = key_selector(elem)
+                if key in s:
                     continue
-                s.add(elem)
+                s.add(key)
                 yield elem
         return Enumerable(inner)
 

types_linq/enumerable.pyi

@@ -509,6 +509,17 @@ class Enumerable(Sequence[TSource_co], Generic[TSource_co]):
             [1, 4, 5, 6, 3, 99]
         '''
 
+    def distinct_by(self, key_selector: Callable[[TSource_co], object]) -> Enumerable[TSource_co]:
+        '''
+        Returns distinct elements from the sequence where "distinctness" is determined by the value
+        returned by the selector.
+
+        Example
+            >>> ints = [1, 4, 5, 6, 4, 3, 1, 99]
+            >>> Enumerable(ints).distinct_by(lambda x: x // 2).to_list()
+            [1, 4, 6, 3, 99]
+        '''
+
     @overload
     def element_at(self, index: int) -> TSource_co:
         '''
@@ -578,6 +589,21 @@ class Enumerable(Sequence[TSource_co], Generic[TSource_co]):
             [2, 4]
         '''
 
+    def except_by(self,
+        second: Iterable[TKey],
+        key_selector: Callable[[TSource_co], TKey],
+    ) -> Enumerable[TSource_co]:
+        '''
+        Produces the set difference of two sequences: self - second, according to a key selector that
+        determines "distinctness".
+
+        Example
+            >>> first = [(16, 'x'), (9, 'y'), (12, 'd'), (16, 't')]
+            >>> second = ['y', 'd']
+            >>> Enumerable(first).except_by(second, lambda x: x[1]).to_list()
+            [(16, 'x'), (16, 't')]
+        '''
+
     @overload
     def first(self) -> TSource_co:
         '''

types_linq/more/more_enumerable.py

@@ -37,13 +37,10 @@ def aggregate_right(self, *args) -> Any:
     def as_more(self) -> MoreEnumerable[TSource_co]:  # pyright: reportIncompatibleMethodOverride=false
         return self
 
-    def distinct_by(self, key_selector: Callable[[TSource_co], object]) -> MoreEnumerable[TSource_co]:
-        return self.except_by((), key_selector)
-
     def enumerate(self, start: int = 0) -> MoreEnumerable[Tuple[int, TSource_co]]:
         return MoreEnumerable(lambda: enumerate(self, start))
 
-    def except_by(self,
+    def except_by2(self,
         second: Iterable[TSource_co],
         key_selector: Callable[[TSource_co], object],
     ) -> MoreEnumerable[TSource_co]:

types_linq/more/more_enumerable.pyi

@@ -22,8 +22,9 @@ class MoreEnumerable(Enumerable[TSource_co]):
     constructing, using as_more(), or invoking MoreEnumerable methods that return MoreEnumerable
     instead of Enumerable.
 
-    Some APIs are subject to change as updates to .NET (6) are happening - they will move to Enumerable
-    class if one day they appear in the official .NET doc.
+    These APIs may have breaking changes more frequently than those in Enumerable class because updates
+    in .NET are happening and sometimes ones of these APIs could be moved to Enumerable with modification,
+    or changed to accommodate changes to Enumerable.
     '''
 
     @overload
@@ -66,17 +67,6 @@ class MoreEnumerable(Enumerable[TSource_co]):
         Returns the original MoreEnumerable reference.
         '''
 
-    def distinct_by(self, key_selector: Callable[[TSource_co], object]) -> MoreEnumerable[TSource_co]:
-        '''
-        Returns distinct elements from the sequence where "distinctness" is determined by the value
-        returned by the selector.
-
-        Example
-            >>> ints = [1, 4, 5, 6, 4, 3, 1, 99]
-            >>> MoreEnumerable(ints).distinct_by(lambda x: x // 2).to_list()
-            [1, 4, 6, 3, 99]
-        '''
-
     def enumerate(self, start: int = 0) -> MoreEnumerable[Tuple[int, TSource_co]]:
         '''
         Returns a sequence of tuples containing the index and the value from the source sequence. `start`
@@ -88,7 +78,7 @@ class MoreEnumerable(Enumerable[TSource_co]):
             [(0, 2), (1, 4), (2, 6)]
         '''
 
-    def except_by(self,
+    def except_by2(self,
         second: Iterable[TSource_co],
         key_selector: Callable[[TSource_co], object],
     ) -> MoreEnumerable[TSource_co]:
@@ -99,7 +89,7 @@ class MoreEnumerable(Enumerable[TSource_co]):
         Example
             >>> first = [(16, 'x'), (9, 'y'), (12, 'd'), (16, 't')]
             >>> second = [(24, 'd'), (77, 'y')]
-            >>> MoreEnumerable(first).except_by(second, lambda x: x[1]).to_list()
+            >>> MoreEnumerable(first).except_by2(second, lambda x: x[1]).to_list()
             [(16, 'x'), (16, 't')]
         '''