Skip to content

utils.cmp | Ordering and Comparison

DeprecatedOrdering: te.TypeAlias = t.Literal[0, -1, 1] module-attribute

This type refers to that Python2 uses to represent ordering in, for example, the sorted function.

SupportsIntoOrdering: te.TypeAlias = t.Union['Ordering', int, float, DeprecatedOrdering] module-attribute

Type that can be turned into an Ordering.

Ordering

Bases: IntEnum

Basic ordering enum.

This enum represents an ordering between two items.

Python does not offer a standard way to represent ordering, and has different usages in different versions (e.g. Python2 uses positive/negative number). And this util class is used to standardize the ordering.

Some of the api offered by this library will use this representation, and translations from other types is also available.

Source code in monad_std/utils/cmp.py 
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
@unique
class Ordering(IntEnum):
    """Basic ordering enum.

    This enum represents an ordering between two items.

    Python does not offer a standard way to represent ordering,
    and has different usages in different versions
    (e.g. Python2 uses positive/negative number).
    And this util class is used to standardize the ordering.

    Some of the api offered by this library will use this representation,
    and translations from other types is also available."""
    Greater = 0
    Equal = 1
    Less = 2

    def to_cmp(self) -> DeprecatedOrdering:
        """Transfer the ordering to the deprecated ordering representation.

        Returns:
            See [`DeprecatedOrdering`][monad_std.utils.cmp.DeprecatedOrdering] for more information.
        """
        if self == Ordering.Greater:
            return 1
        elif self == Ordering.Less:
            return -1
        else:
            return 0

    @staticmethod
    def parse(arg: SupportsIntoOrdering) -> "Ordering":
        """Detect an ordering and returns an `Ordering`.

        Examples:
            ```python
            o1 = Ordering.parse(Ordering.Less)
            o2 = Ordering.parse(-1)
            o3 = Ordering.parse(-4.2)
            assert o1 == o2 == o3
            ```
        """
        if isinstance(arg, Ordering):
            return arg
        elif isinstance(arg, (int, float)):
            return Ordering.from_num(arg)
        else:
            raise ValueError("Unknown ordering type, expect `Ordering`, `int` or `float`")

    @staticmethod
    def from_cmp(cmp: DeprecatedOrdering) -> "Ordering":
        """Construct the ordering from the deprecated ordering representation.

        This has the same internal implementation as the [`from_num`][monad_std.utils.cmp.Ordering.from_num] method.
        However, this takes `DeprecatedOrdering` as argument instead of anything that can compare with `0`.
        The motivation of this specialized method is to guarantee type safety.

        It's also recommended to use this method to specify your target and what you want.
        But for more general use, you can also choose to use `from_num` instead.

        Args:
            cmp: See [`DeprecatedOrdering`][monad_std.utils.cmp.DeprecatedOrdering] for more information.

        Examples:
            ```python
            assert Ordering.from_cmp(0) == Ordering.Equal
            assert Ordering.from_cmp(1) == Ordering.Greater
            assert Ordering.from_cmp(-1) == Ordering.Less
            ```
        """
        if cmp > 0:
            return Ordering.Greater
        elif cmp < 0:
            return Ordering.Less
        else:
            return Ordering.Equal

    @staticmethod
    def from_num(n: "td.cmp.SupportsAllComparisons[int]") -> "Ordering":
        """Construct the ordering from the deprecated ordering representation.

        This accepts any value that can compare with `int` (or more explicitly `0`),
        different from [`from_cmp`][monad_std.utils.cmp.Ordering.from_cmp].

        It's generally discouraged to use this method.

        Examples:
            ```python
            assert Ordering.from_num(0.0) == Ordering.Equal
            assert Ordering.from_num(1.5) == Ordering.Greater
            assert Ordering.from_num(-3.2) == Ordering.Less
            ```
        """
        if n > 0:
            return Ordering.Greater
        elif n < 0:
            return Ordering.Less
        else:
            return Ordering.Equal

    def is_ne(self) -> bool:
        """If the ordering represents **not equal**."""
        return self != Ordering.Equal

    def is_le(self) -> bool:
        """If the ordering represents **less than or equal**."""
        return self != Ordering.Greater

    def is_ge(self) -> bool:
        """If the ordering represents **greater than or equal**."""
        return self != Ordering.Less

from_cmp(cmp) staticmethod

Construct the ordering from the deprecated ordering representation.

This has the same internal implementation as the from_num method. However, this takes DeprecatedOrdering as argument instead of anything that can compare with 0. The motivation of this specialized method is to guarantee type safety.

It's also recommended to use this method to specify your target and what you want. But for more general use, you can also choose to use from_num instead.

Parameters:

Name Type Description Default
cmp DeprecatedOrdering

See DeprecatedOrdering for more information.

 required

Examples:

1
2
3
assert Ordering.from_cmp(0) == Ordering.Equal
assert Ordering.from_cmp(1) == Ordering.Greater
assert Ordering.from_cmp(-1) == Ordering.Less
Source code in monad_std/utils/cmp.py 
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
@staticmethod
def from_cmp(cmp: DeprecatedOrdering) -> "Ordering":
    """Construct the ordering from the deprecated ordering representation.

    This has the same internal implementation as the [`from_num`][monad_std.utils.cmp.Ordering.from_num] method.
    However, this takes `DeprecatedOrdering` as argument instead of anything that can compare with `0`.
    The motivation of this specialized method is to guarantee type safety.

    It's also recommended to use this method to specify your target and what you want.
    But for more general use, you can also choose to use `from_num` instead.

    Args:
        cmp: See [`DeprecatedOrdering`][monad_std.utils.cmp.DeprecatedOrdering] for more information.

    Examples:
        ```python
        assert Ordering.from_cmp(0) == Ordering.Equal
        assert Ordering.from_cmp(1) == Ordering.Greater
        assert Ordering.from_cmp(-1) == Ordering.Less
        ```
    """
    if cmp > 0:
        return Ordering.Greater
    elif cmp < 0:
        return Ordering.Less
    else:
        return Ordering.Equal

from_num(n) staticmethod

Construct the ordering from the deprecated ordering representation.

This accepts any value that can compare with int (or more explicitly 0), different from from_cmp.

It's generally discouraged to use this method.

Examples:

1
2
3
assert Ordering.from_num(0.0) == Ordering.Equal
assert Ordering.from_num(1.5) == Ordering.Greater
assert Ordering.from_num(-3.2) == Ordering.Less
Source code in monad_std/utils/cmp.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
@staticmethod
def from_num(n: "td.cmp.SupportsAllComparisons[int]") -> "Ordering":
    """Construct the ordering from the deprecated ordering representation.

    This accepts any value that can compare with `int` (or more explicitly `0`),
    different from [`from_cmp`][monad_std.utils.cmp.Ordering.from_cmp].

    It's generally discouraged to use this method.

    Examples:
        ```python
        assert Ordering.from_num(0.0) == Ordering.Equal
        assert Ordering.from_num(1.5) == Ordering.Greater
        assert Ordering.from_num(-3.2) == Ordering.Less
        ```
    """
    if n > 0:
        return Ordering.Greater
    elif n < 0:
        return Ordering.Less
    else:
        return Ordering.Equal

is_ge()

If the ordering represents greater than or equal.

Source code in monad_std/utils/cmp.py 
128
129
130
def is_ge(self) -> bool:
    """If the ordering represents **greater than or equal**."""
    return self != Ordering.Less

is_le()

If the ordering represents less than or equal.

Source code in monad_std/utils/cmp.py 
124
125
126
def is_le(self) -> bool:
    """If the ordering represents **less than or equal**."""
    return self != Ordering.Greater

is_ne()

If the ordering represents not equal.

Source code in monad_std/utils/cmp.py 
120
121
122
def is_ne(self) -> bool:
    """If the ordering represents **not equal**."""
    return self != Ordering.Equal

parse(arg) staticmethod

Detect an ordering and returns an Ordering.

Examples:

1
2
3
4
o1 = Ordering.parse(Ordering.Less)
o2 = Ordering.parse(-1)
o3 = Ordering.parse(-4.2)
assert o1 == o2 == o3
Source code in monad_std/utils/cmp.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
@staticmethod
def parse(arg: SupportsIntoOrdering) -> "Ordering":
    """Detect an ordering and returns an `Ordering`.

    Examples:
        ```python
        o1 = Ordering.parse(Ordering.Less)
        o2 = Ordering.parse(-1)
        o3 = Ordering.parse(-4.2)
        assert o1 == o2 == o3
        ```
    """
    if isinstance(arg, Ordering):
        return arg
    elif isinstance(arg, (int, float)):
        return Ordering.from_num(arg)
    else:
        raise ValueError("Unknown ordering type, expect `Ordering`, `int` or `float`")

to_cmp()

Transfer the ordering to the deprecated ordering representation.

Returns:

Type Description
DeprecatedOrdering

See DeprecatedOrdering for more information.
Source code in monad_std/utils/cmp.py 
37
38
39
40
41
42
43
44
45
46
47
48
def to_cmp(self) -> DeprecatedOrdering:
    """Transfer the ordering to the deprecated ordering representation.

    Returns:
        See [`DeprecatedOrdering`][monad_std.utils.cmp.DeprecatedOrdering] for more information.
    """
    if self == Ordering.Greater:
        return 1
    elif self == Ordering.Less:
        return -1
    else:
        return 0

compare(a, b)

Compare two item and generate the ordering.

Examples:

1
2
3
assert compare(0, 1) == Ordering.Less
assert compare(5.0, -3) == Ordering.Greater
assert compare(5, 5.0) == Ordering.Equal
Source code in monad_std/utils/cmp.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
def compare(a: "RichCmpA", b: "RichCmpB") -> Ordering:
    """Compare two item and generate the ordering.

    Examples:
        ```python
        assert compare(0, 1) == Ordering.Less
        assert compare(5.0, -3) == Ordering.Greater
        assert compare(5, 5.0) == Ordering.Equal
        ```
    """
    if a > b:
        return Ordering.Greater
    elif a < b:
        return Ordering.Less
    else:
        return Ordering.Equal

max_by(a, b, fn)

Use the given function to calculate the maximum value in a and b.

The fn parameter should return SupportsIntoOrdering. See its documentation for more information.

If the function returns Ordering.Equal, then b is returned.

Examples:

1
2
3
4
a = 0
b = 1
assert max_by(a, b, lambda x, y: compare(x, y)) == b
assert max_by(a, b, lambda x, y: compare(y, x)) == a    # reverse the comparison here.

The latter case is same as the following: 

1
assert -max(-a, -b) == a

Source code in monad_std/utils/cmp.py 
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
def max_by(a: T, b: T, fn: t.Callable[[T, T], SupportsIntoOrdering]) -> T:
    """Use the given function to calculate the maximum value in a and b.

    The `fn` parameter should return [`SupportsIntoOrdering`][monad_std.utils.cmp.SupportsIntoOrdering].
    See its documentation for more information.

    If the function returns `Ordering.Equal`, then `b` is returned.

    Examples:
        ```python
        a = 0
        b = 1
        assert max_by(a, b, lambda x, y: compare(x, y)) == b
        assert max_by(a, b, lambda x, y: compare(y, x)) == a    # reverse the comparison here.
        ```

        The latter case is same as the following:
        ```python
        assert -max(-a, -b) == a
        ```
    """
    ores = fn(a, b)
    ordering = Ordering.parse(ores)
    if ordering.is_le():
        return b
    else:
        return a

min_by(a, b, fn)

Use the given function to calculate the minimum value in a and b.

The fn parameter should return SupportsIntoOrdering. See its documentation for more information.

If the function returns Ordering.Equal, then b is returned.

Examples:

1
2
3
4
a = 0
b = 1
assert min_by(a, b, lambda x, y: compare(x, y)) == a
assert min_by(a, b, lambda x, y: compare(y, x)) == b    # reverse the comparison here.

The latter case is same as the following: 

1
assert -min(-a, -b) == b

Source code in monad_std/utils/cmp.py 
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
def min_by(a: T, b: T, fn: t.Callable[[T, T], SupportsIntoOrdering]) -> T:
    """Use the given function to calculate the minimum value in a and b.

    The `fn` parameter should return [`SupportsIntoOrdering`][monad_std.utils.cmp.SupportsIntoOrdering].
    See its documentation for more information.

    If the function returns `Ordering.Equal`, then `b` is returned.

    Examples:
        ```python
        a = 0
        b = 1
        assert min_by(a, b, lambda x, y: compare(x, y)) == a
        assert min_by(a, b, lambda x, y: compare(y, x)) == b    # reverse the comparison here.
        ```

        The latter case is same as the following:
        ```python
        assert -min(-a, -b) == b
        ```
    """
    ores = fn(a, b)
    ordering = Ordering.parse(ores)
    if ordering.is_ge():
        return b
    else:
        return a