Comparers

Rational Comparers

calcpy provides extension of rational comparers to support multiple arguments and a parameter key to customize the comparision.

calcpy.eq(*args, key=None)

Check whether all parameters are the same.

Fully compatible with Python’s built-in operator.eq.

Parameters:

• *args

• key (callable)

Return type:

bool

Examples

>>> eq({"a": 1}, {"a": 1}, {"a": 1})
True
>>> eq(1, 1, 2, 2)
False

See also

https://docs.python.org/3/library/operator.html#operator.eq

calcpy.ne(*args, key=None)

Check whether all parameters are distinct.

Fully compatible with Python’s built-in operator.ne.

Parameters:

• *args

• key (callable)

Return type:

bool

Examples

>>> ne([1, 2], [1, 3], [2, 3])
True
>>> ne([1, 2], [1, 3], [1, 3])
False

See also

https://docs.python.org/3/library/operator.html#operator.ne

calcpy.lt(*args, key=None)

Return True when all arguments are lt the next argument.

Fully compatible with Python’s built-in operator.lt.

Parameters:

• *args

• key (callable)

Return type:

bool

Examples

>>> lt()
True
>>> lt(1)
True
>>> lt(1, 1)
False
>>> lt(1, 2)
True
>>> lt(2, 1)
False
>>> lt(1, 1, 2)
False
>>> lt(1, 2, 3)
True
>>> lt(3, 2, 1)
False

See also

https://docs.python.org/3/library/operator.html#operator.lt

calcpy.le(*args, key=None)

Return True when all arguments are le the next argument.

Fully compatible with Python’s built-in operator.le.

Parameters:

• *args

• key (callable)

Return type:

bool

Examples

>>> le()
True
>>> le(1)
True
>>> le(1, 1)
True
>>> le(1, 2)
True
>>> le(2, 1)
False
>>> le(1, 1, 2)
True
>>> le(1, 2, 3)
True
>>> le(3, 2, 1)
False

See also

https://docs.python.org/3/library/operator.html#operator.le

calcpy.ge(*args, key=None)

Return True when all arguments are ge the next argument.

Fully compatible with Python’s built-in operator.ge.

Parameters:

• *args

• key (callable)

Return type:

bool

Examples

>>> ge()
True
>>> ge(1)
True
>>> ge(1, 1)
True
>>> ge(1, 2)
False
>>> ge(2, 1)
True
>>> ge(1, 1, 2)
False
>>> ge(1, 2, 3)
False
>>> ge(3, 2, 1)
True

See also

https://docs.python.org/3/library/operator.html#operator.ge

calcpy.gt(*args, key=None)

Return True when all arguments are gt the next argument.

Fully compatible with Python’s built-in operator.gt.

Parameters:

• *args

• key (callable)

Return type:

bool

Examples

>>> gt()
True
>>> gt(1)
True
>>> gt(1, 1)
False
>>> gt(1, 2)
False
>>> gt(2, 1)
True
>>> gt(1, 1, 2)
False
>>> gt(1, 2, 3)
False
>>> gt(3, 2, 1)
True

See also

https://docs.python.org/3/library/operator.html#operator.gt

Convert among Comparers

Python has three types of comparers:

• Rational Comparers: eq(), ne(), lt(), le(), ge(), gt(). They are provided in the built-in module operator and are extended in calcpy.

• Callable function: Many built-in functions (such as sorted(), min(), max()), as well as many calcpy functions, has a parameter key to specify a callable function, and the return values of this function can be used to compare.

• Three-way ``cmp`` functions: cmp(). It returns 1 when the first argument is greater than the second argument, -1 when the first argument is less than the second argument, and 0 when the two arguments are equal. It is the old style of comparison in early version of Python 2.

calcpy provides APIs to convert among these three types of comparers.

calcpy.eq_to_key(eq=<built-in function eq>)

Convert an equality function to a key function.

Parameters:

eq (callable) – A function that takes two at least arguments and returns True if the arguments are equal, False otherwise.

Return type:

callable

Note

This function is experimental and may change in the future.

calcpy.ne_to_key(ne=<built-in function ne>)

Convert an equality function to a key function.

Parameters:

eq (callable) – A function that takes two arguments and returns True if the arguments are equal, False otherwise.

Return type:

callable

Note

This function is experimental and may change in the future.

calcpy.lt_to_key(lt=<built-in function lt>)

Convert a less-than function to a key function.

Parameters:

lt (callable) – A function that takes two arguments and returns True if the first is less than the second, False otherwise.

Return type:

callable

Examples

>>> import operator
>>> key = lt_to_key(operator.lt)
>>> sorted([3, 1, 2], key=key)
[1, 2, 3]

calcpy.le_to_key(le=<built-in function le>)

Convert a less-than-or-equal-to function to a key function.

Parameters:

le (callable) – A function that takes two arguments and returns True if the first is less than or equal to the second, False otherwise.

Return type:

callable

Examples

>>> import operator
>>> key = le_to_key(operator.le)
>>> sorted([3, 1, 2], key=key)
[1, 2, 3]

calcpy.gt_to_key(gt=<built-in function gt>)

Convert a greater-than function to a key function.

Parameters:

gt (callable) – A function that takes two arguments and returns True if the first is greater than the second, False otherwise.

Return type:

callable

Examples

>>> import operator
>>> key = gt_to_key(operator.gt)
>>> sorted([3, 1, 2], key=key)
[1, 2, 3]

calcpy.ge_to_key(ge=<built-in function ge>)

Convert a greater-than-or-equal-to function to a key function.

Parameters:

ge (callable) – A function that takes two arguments and returns True if the first is greater than or equal to the second, False otherwise.

Return type:

callable

Examples

>>> import operator
>>> key = ge_to_key(operator.ge)
>>> sorted([3, 1, 2], key=key)
[1, 2, 3]

calcpy.cmp_to_key(mycmp)

Convert a cmp= function into a key= function.

mycmp

Function that compares two objects.

calcpy.key_to_cmp(key)

Convert a key function to a comparison function. The comparison function will compare two objects based on the key function.

Parameters:

key (callable) – A function that takes an object and returns a value that can be compared.

Returns:

A comparison function that takes two objects and

returns 1 if the first is greater than or equal to the second, -1 if the first is less than the second, and 0 if they are equal.

Return type:

callable

Examples

>>> cmp = key_to_cmp(len)
>>> cmp("Hello", "World")
0
>>> cmp("Hello", "Python")
-1

calcpy.key_to_eq(key=None)

Convert a key= function to a eq function.

Parameters:

key (callable)

Returns:

A function that takes two arguments and returns True or False based on the comparison.

Return type:

callable

Examples

>>> eq = key_to_eq(len)
>>> eq("Hello", "World")
True

calcpy.key_to_ne(key=None)

Convert a key= function to a ne function.

Parameters:

key (callable)

Returns:

A function that takes two arguments and returns True or False based on the comparison.

Return type:

callable

Examples

>>> ne = key_to_ne(len)
>>> ne("Hello", "World")
False

calcpy.key_to_lt(key=None)

Convert a key= function to a lt function.

Parameters:

key (callable)

Returns:

A function that takes two arguments and returns True or False based on the comparison.

Return type:

callable

Examples

>>> lt = key_to_lt(len)
>>> lt("Hello", "World")
False

calcpy.key_to_le(key=None)

Convert a key= function to a le function.

Parameters:

key (callable)

Returns:

A function that takes two arguments and returns True or False based on the comparison.

Return type:

callable

Examples

>>> le = key_to_le(len)
>>> le("Hello", "World")
True

calcpy.key_to_gt(key=None)

Convert a key= function to a gt function.

Parameters:

key (callable)

Returns:

A function that takes two arguments and returns True or False based on the comparison.

Return type:

callable

Examples

>>> gt = key_to_gt(len)
>>> gt("Hello", "World")
False

calcpy.key_to_ge(key=None)

Convert a key= function to a ge function.

Parameters:

key (callable)

Returns:

A function that takes two arguments and returns True or False based on the comparison.

Return type:

callable

Examples

>>> ge = key_to_ge(len)
>>> ge("Hello", "World")
True

calcpy.eq_to_cmp(eq=<built-in function eq>)

Convert an equality function to a comparison function.

The comparison function will return 0 if the two objects are equal, and 1 otherwise.

Parameters:

eq (callable) – A function that takes at least two arguments and returns True if the first two arguments are equal, False otherwise.

Returns:

A comparison function that takes two objects and

returns 1 if the first is greater than or equal to the second, -1 if the first is less than the second, and 0 if they are equal.

Return type:

callable

Note

This function is experimental and may be changed in the future.

Examples

>>> cmp = eq_to_cmp(operator.eq)
>>> cmp(1, 2)
1
>>> cmp(1, 1)
0
>>> cmp(2, 1)
1

calcpy.ne_to_cmp(ne=<built-in function ne>)

Convert a non-equality function to a comparison function.

The comparison function will return 0 if the two objects are not equal, and 1 otherwise.

Parameters:

ne (callable) – A function that takes two arguments and returns True if the first two arguments are not equal, False otherwise.

Returns:

A comparison function that takes two objects and

returns 1 if the first is greater than or equal to the second, -1 if the first is less than the second, and 0 if they are equal.

Return type:

callable

Note

This function is experimental and may be changed in the future.

Examples

>>> cmp = ne_to_cmp(operator.ne)
>>> cmp(1, 2)
1
>>> cmp(1, 1)
0
>>> cmp(2, 1)
1

calcpy.lt_to_cmp(lt=<built-in function le>)

Convert a less-than function to a comparison function.

Parameters:

lt (callable) – A function that takes at least two arguments and returns True if the first is less than the second, False otherwise.

Returns:

A comparison function that takes two objects and

returns 1 if the first is greater than or equal to the second, -1 if the first is less than the second, and 0 if they are equal.

Return type:

callable

Examples

>>> cmp = lt_to_cmp(operator.lt)
>>> cmp(1, 2)
-1
>>> cmp(1, 1)
0
>>> cmp(2, 1)
1

calcpy.le_to_cmp(le=<built-in function le>)

Convert a less-than-or-equal-to function to a comparison function.

Parameters:

le (callable) – A function that takes at least two arguments and returns True if the first is less than or equal to the second, False otherwise.

Returns:

A comparison function that takes two objects and

returns 1 if the first is greater than or equal to the second, -1 if the first is less than the second, and 0 if they are equal.

Return type:

callable

Examples

>>> cmp = le_to_cmp(operator.le)
>>> cmp(1, 2)
-1
>>> cmp(1, 1)
0
>>> cmp(2, 1)
1

calcpy.ge_to_cmp(ge=<built-in function ge>)

Convert a greater-than-or-equal-to function to a comparison function.

Parameters:

ge (callable) – A function that takes at least two arguments and returns True if the first is greater than or equal to the second, False otherwise.

Returns:

A comparison function that takes two objects and

returns 1 if the first is greater than or equal to the second, -1 if the first is less than the second, and 0 if they are equal.

Return type:

callable

Examples

>>> cmp = ge_to_cmp(operator.ge)
>>> cmp(1, 2)
-1
>>> cmp(1, 1)
0
>>> cmp(2, 1)
1

calcpy.gt_to_cmp(gt=<built-in function ge>)

Convert a greater-than function to a comparison function.

Parameters:

gt (callable) – A function that takes at least two arguments and returns True if the first is greater than the second, False otherwise.

Returns:

A comparison function that takes two objects and

returns 1 if the first is greater than or equal to the second, -1 if the first is less than the second, and 0 if they are equal.

Return type:

callable

Examples

>>> cmp = gt_to_cmp(operator.gt)
>>> cmp(1, 2)
-1
>>> cmp(1, 1)
0
>>> cmp(2, 1)
1

calcpy.cmp_to_eq(cmp)

Convert a cmp= function to a eq= function.

Parameters:

cmp (callable) – A comparison function that takes two arguments and returns -1, 0, or 1 when the first is less than, equal to, or greater than the second.

Return type:

callable

Examples

>>> def cmp(a, b):
...     return (a > b) - (a < b)
>>> eq = cmp_to_eq(cmp)
>>> eq(1, 2)
False

calcpy.cmp_to_ne(cmp)

Convert a cmp= function to a ne= function.

Parameters:

cmp (callable) – A comparison function that takes two arguments and returns -1, 0, or 1 when the first is less than, equal to, or greater than the second.

Return type:

callable

Examples

>>> def cmp(a, b):
...     return (a > b) - (a < b)
>>> ne = cmp_to_ne(cmp)
>>> ne(1, 2)
True

calcpy.cmp_to_lt(cmp)

Convert a cmp= function to a lt= function.

Parameters:

cmp (callable) – A comparison function that takes two arguments and returns -1, 0, or 1 when the first is less than, equal to, or greater than the second.

Return type:

callable

Examples

>>> def cmp(a, b):
...     return (a > b) - (a < b)
>>> lt = cmp_to_lt(cmp)
>>> lt(1, 2)
True

calcpy.cmp_to_le(cmp)

Convert a cmp= function to a le= function.

Parameters:

cmp (callable) – A comparison function that takes two arguments and returns -1, 0, or 1 when the first is less than, equal to, or greater than the second.

Return type:

callable

Examples

>>> def cmp(a, b):
...     return (a > b) - (a < b)
>>> le = cmp_to_le(cmp)
>>> le(1, 2)
True

calcpy.cmp_to_gt(cmp)

Convert a cmp= function to a gt= function.

Parameters:

cmp (callable) – A comparison function that takes two arguments and returns -1, 0, or 1 when the first is less than, equal to, or greater than the second.

Return type:

callable

Examples

>>> def cmp(a, b):
...     return (a > b) - (a < b)
>>> gt = cmp_to_gt(cmp)
>>> gt(1, 2)
False

calcpy.cmp_to_ge(cmp)

Convert a cmp= function to a ge= function.

Parameters:

cmp (callable) – A comparison function that takes two arguments and returns -1, 0, or 1 when the first is less than, equal to, or greater than the second.

Return type:

callable

Examples

>>> def cmp(a, b):
...     return (a > b) - (a < b)
>>> ge = cmp_to_ge(cmp)
>>> ge(1, 2)
False

Matcher (Experimental)

We also provide a class calcpy.matcher.PandasFrameMatcher for comparing pd.DataFrame’s. It can be passed to the parameter key for set-operation APIs in calcpy.

class calcpy.matcher.PandasFrameMatcher(method='object', axis=0, eq=None, key=None, **kwargs)

Auxiliary class for pd.Series and pd.DataFrame.

Parameters:

• method (str) – can be "object", "series", "index". "object" means comparing the whole pd.NDFrame object. "series" means comparing the whole pd.Series, which is equivalent to a row (when axis=1) or a column (when axis=0). "index" means comparing the index value (when axis=0) or column value (when axis=1) only. "value" means comparing the values of some columns (when axis=0) or rows (when axis=1).

• axis (int or str) – can be 0 (“index”) or 1 (“column”)

• matcher (callable) – a binary function

• **kwargs – keyword arguments as of pd.DataFrame.drop_duplicates(). Only used when method="value".

Examples

>>> from calcpy import unique
>>> df0 = pd.DataFrame({"A": 1, "B": 2, "C": 3}, index=[0])
>>> df1 = pd.DataFrame({"A": 1, "B": 2, "C": 3}, index=[0])
>>> df2 = pd.DataFrame({"A": 1, "B": 2, "C": 3}, index=[0])
>>> len(unique([df0, df1, df2]))
1

>>> from calcpy import intersection
>>> df0 = pd.DataFrame({"A": [1, 2, 3], "B": [3, 2, 3]}, index=["X", "Y", "Z"])
>>> df1 = pd.DataFrame({"C": [4, 5, 6], "D": [8, 5, 2]}, index=["U", "V", "X"])
>>> intersection(df0, df1, key=PandasFrameMatcher(method="index"))
   A  B
X  1  3

>>> df0 = pd.DataFrame({"A": [1, 2, 3], "B": [3, 2, 3]}, index=["X", "Y", "Z"])
>>> df1 = pd.DataFrame({"C": [4, 5, 6], "D": [8, 5, 2]}, index=["U", "V", "X"])
>>> intersection(df0, df1, key=PandasFrameMatcher(method="value"))  # return None

Different ways to instantiate the PandasFrameMatcher class:

• calcpy.matcher.PandasFrameMatcher(): Compare whether pandas objects as a whole. It has the same effect as calcpy.overall_equal().

• calcpy.matcher.PandasFrameMatcher("index"): Compare index values of pandas objects.

• calcpy.matcher.PandasFrameMatcher("values"): Compare values of pandas objects, ignoring the index values.

• calcpy.matcher.PandasFrameMatcher("series"): Compare pd.DataFrame in a pd.Series way. By default, it is left_series.equals(right_series).

For pd.DataFrame, it also provides a keyword parameter axis. It compares each row when it is set to 0 (the default value) or index, and compares each column if axis is set to 1 or column.