ConditionToken

ConditionToken has a superpower: it can check arbitrary conditions. In addition to this, it can do all the same things as SimpleToken. The condition is a function that returns an answer to the question "should the token be cancelled" (True/False); it is passed to the token as the first required argument during initialization:

from cantok import ConditionToken

counter = 0
token = ConditionToken(lambda: counter >= 5)

while token:
  counter += 1

print(counter)  #> 5

By default, if the passed function raises an exception, the exception will be silently suppressed. However, you can make the raised exceptions explicit by setting the suppress_exceptions parameter to False:

def function(): raise ValueError

token = ConditionToken(function, suppress_exceptions=False)

token.cancelled # ValueError will be raised.

When using exception suppression mode, the cancelled attribute will be False by default in case of an exception. If you want to change this, pass default=True.

def function(): raise ValueError

print(ConditionToken(function).cancelled)  #> False
print(ConditionToken(function, default=False).cancelled)  #> False
print(ConditionToken(function, default=True).cancelled)  #> True

If the condition is complex enough and requires additional preparation before it can be checked, you can pass a function that runs before the condition is checked. To do this, pass any function without arguments as the before argument:

from cantok import ConditionToken

token = ConditionToken(lambda: print(2), before=lambda: print(1))

token.check()
#> 1
#> 2

By analogy with before, you can pass a function as the after argument that will be executed after checking the condition:

token = ConditionToken(lambda: print(1), after=lambda: print(2))

token.check()
#> 1
#> 2

ConditionToken has another feature. If the condition has returned True at least once and cancelled the token, then the condition is no longer polled and the token is permanently considered cancelled. You can change this by manipulating the caching parameter when creating a token. By setting it to False, you will make sure that the condition is polled every time.

counter = 0

def increment_counter_and_get_the_value():
    global counter
    counter += 1
    return counter == 2


token = ConditionToken(increment_counter_and_get_the_value, caching=False)

print(token.cancelled)
#> False
print(token.cancelled)
#> True
print(token.cancelled)
#> False

However, we do not recommend doing this. In the vast majority of cases, you do not want your token to be able to undo its cancellation. If the token has been cancelled once, it must remain cancelled. Manipulate the caching parameter only if you are sure that you understand what you are doing.