Skip to content

Function Object#

Extend functions with operator overloads for function calling.

Conceptually, function objects are objects that implement the function call operator.

Rationale#

Python codes contain extensive use of parentheses, which can be cumbersome in interactive environments. This module simply provides a way to reduce the pain of wrapping huge expressions in parentheses. You can use application operators provided by FunctionObject to apply the function on the following expression. Use the fob function to turn a function or a sequence of functions into FunctionObjects.

Usage#

TL;DR

Use and only use function objects in interactive environments.

For example, f(..) is equivalent to f | (...) or f @ (...). Writing f(...) as f@(...) seems redundant, but these @ usages can be purged easily with simple search and replace. FunctionObject's operators are carefully chosen, as they:

  1. are relatively rare in Python
  2. have different precedence and associativity

This is especially useful when you wrap some debugging or logging code around a function call. For example, with the following usage with icecream, you can replace ic @ with empty string to remove all debugging code, without worrying of breaking the get_pic() call:

from icecream import ic as _ic

ic = fob(_ic)
result = ic @ (
    get_pic(iris)
        .filter(...)
        .sort_values(...)
        .apply(...)
        .head(10)
)

| and @ have different operator precedence, the | has almost the lowest precedence of all Python operators, while the @ has almost the highest precedence. This allows you combine expressions more flexibly without worrying about parentheses.

& operator can be used to apply the function to its left-hand side, if the left-hand side does not overload the & operator. This is similar to &, |> or roughly %>%. With & you can write your code naturally from left to right.

from icecream import ic as _ic
ic = fob(_ic)

result = (
    get_pic(iris)
        .filter(...)
        # ...
) & ic

** operator has the highest precedence of all, and it has a unique associtivity from right to left. It can be used in wrapping multiple calls together without parentheses, like f(g(x)) can be written as f ** g ** x. It roughly simulates $.

% operator is used for calling multi-argument functions. Check its documentation for more details.

Tip

Function objects come with runtime costs. Although negligible most of the time, the cost could accumulate on critical paths.

FunctionObjects also have less static typing support. Do not use them in type-checked code.

Warning

Wrapping callables other than functions with FunctionObject may lose attributes and methods of the original callable.

Warning

For performance considerations, apfel APIs are not wrapped in FunctionObjects.

FunctionObject #

__matmul__(rhs) #

def @[T, R](self, rhs: T) -> R

Function application operator @ for FunctionObjects.

f @ x is equivalent to f(x). This operator behaves the same as |, but with a different precedence.

Example 
@fob
def f(x):
    return x * 2

f @ 1 + 2
# 4

__mod__(rhs) #

def %[R](self, rhs) -> R

Function application operator % for FunctionObjects of multi-argument functions.

  • If the right hand side is a Sequence, spreads the sequence as positional arguments. For example, x % (a, b, c) is equivalent to x(a, b, c).
  • If the right hand side is a Mapping, spreads the mapping as keyword arguments. For example, x % { "a": 1, "b": 2, "c": 3 } is equivalent to x(a=1, b=2, c=3).
  • Specifically, you can use ... as the map key to pass keyword arguments with keyword arguments at the same time, x % { ...: (1, 2), "c": 3 } is equivalent to x(1, 2, c=3).
  • Otherwise, it calls on the right-hand side. This catches the case where you forget the trailing comma in the right-hand side tuple.
Example 
@fob
def f(a, b, c):
    return a + b + c

f % (1, 2, 3)                  # 6
f % { "a": 1, "b": 2, "c": 3 } # 6
f % { ...: (1, 2), "c": 3 }    # 6
Warning

This operator does not support the case where ... (the Ellipsis, not "...") is used as a keyword argument. However, this case is relatively rare, as ... cannot be declared as argument name.

__or__(rhs) #

def |[T, R](self, rhs: T) -> R

Function application operator | for FunctionObjects.

f | x is equivalent to f(x). This operator behaves the same as @, but with a different precedence.

Example 
@fob
def f(x):
    return x * 2

f | 1 + 2
# 6

__pow__(rhs) #

def **[T, R](self, rhs: T) -> R

Function application operator ** for FunctionObjects.

f ** g ** x is equivalent to f(g(x)). This operator has the highest precedence of all overloadable operators, and it binds from right to left. It intends to simulate $ operator, except the precedence.

Example 
@fob
def f(x):
    return x + 1

@fob
def g(x):
    return x * 2

f ** g ** 1
# 3

__rand__(lhs) #

def &[T, R](self, lhs: T) -> R
Reverse function application operator & for FunctionObjects. This operator overloading targets the right-hand side.

x & f is equivalent to f(x), if & operator (left, __and__) is not overloaded by x's type.

Warning

np.array and array-like types are common overloaders of &, therefore this operator cannot be used with them.

Example 
@fob
def f(x):
    return x + 1

1 + 2 & f
# 6

fob(f, *fs) #

def fob[F: Callable](f: F) -> F
def fob[*Fs](*fs: *Fs) -> tuple[*Fs]

Turn callables into FunctionObject yet keeps their original type hints.

Example 
@fob
def f(a: int) -> int:
    return f + 1

f | 1
# 2

print, display, str = fob(print, display, str)
Note

As a callable, FunctionObject has less static typing support. @fob erases type hints of FunctionObject while keeping the runtime type. If you want to retain the type hints, directly use FunctionObject's constructor, or use reveal_fob on an object with runtime type FunctionObject.

reveal_fob(f) #

def reveal_fob(func: Any) -> FunctionObject raise TypeError

Cast a FunctionObject to FunctionObject type.

Exception

This function performs runtime check and raises TypeError if the input is not a FunctionObject.