Find() vs. Exists()

Ok, here you are:

1. find() is the basic search feature. it takes an image and returns the match object if found. With the standard it waits max 3 seconds for the image to come up and then raises a FindFailed exception, that can be catched with try: except:
You can change the standards by using setAutoWaitTimeout() and setThrowException().

2. wait() is a feature, that includes find(), but gives a chance, to set an individual timeout, but it still raises FindFailed, if the timeout is reached.

Using these both features, to build decision trees easily becomes very unclear and confusing, if you want to save the FindFailed exceptions for cases, were you really need it. Normally in your scripts you expect a certain workflow, that together with some timing happens just as you expect. So if you just switch of raising of FindFailed, you have to check every possible situation, to make your scripts robust. So why handle exceptions, when you just think something should be there and only want to make a decision, because if it is not there, it is ok, you only have to do other things.

So I requested among other features based on 0.9 the feature exists(), which is just a wait(), but does not throw an exception (in fact, this is handled internally).

example:
you wait for an image to come up. then you have to decide based on the existence of another image which of two buttons to click.

so you could say:
setThrowException(False)
if not wait(image1, 10): exit(1)
if find(image2): click(button1)
else: click(button2)

everything is made robust, except the click()'s. If neither of the buttons would be found (I know, you expect them to be there), nothing would happen and the script would go on doing weird things.
If the buttons are the objects you are sure they should be found, so let us secure their search with FindFailed. Since it should not happen, we accept that the script stops in this case.

so with exists():
if not exists(image1, 10): exit(1)
if exists(image2): click(button1)
else: click(button2)

So without any additional effort, it is robust now: if something goes wrong with the buttons, the script will stop. (Just try to do this without an exists())

So exists() is just a not-FindFailing wait, that can easily be used in decisions without dealing with exceptions and saving exception FindFailed for the cases where something weird happens, that you did not foresee or did not want to.