Guidance on exceptions given by the Python docs

"You should try to use as few except clauses in your code as you can"

It's easy to litter your code with exceptions:

def solve_linear(mat1, mat2):
    det1 = determinant(mat1)
    det2 = determinant(mat2)
    try:
        return det1 / det2
    except ZeroDivisionError:
        raise NoSolution

Here, it's probably fine to let the ZeroDivisionError propagate. You don't need to catch it.

"the ones you do use will usually be inside calls which should always succeed"

For example, look at this code which reads a file, or returns a cached value. It normally succeeds, in spite of the KeyError exception:

def read_file(path):
    try:
        return cache[path]
    except KeyError:
        fp = open(path, 'rb')
        data = fp.read()
        fp.close()
        cache[path] = data
        return data

"or a catch-all in a main function."

If your program is interactive, you'll probably want to catch almost everything at the top level. Here's the top loop of an interactive command-line program:

def main():
    while True:
        try:
            text = raw_input('enter command: ')
            cmd = parse_command(text)
        except EOFError:
            return
        except KeyboardInterrupt:
            return
        except ValueError:
            print 'Syntax error'
            continue

        try:
            run_cmd(cmd)
        except SystemExit:
            raise
        except Exception:
            traceback.print_exc()

I think the point is that exceptions should be used only for 'exceptional' circumstances. That is the meaning behind the use "in calls which will usually succeed". An example of this might be some computation that under some really weird circumstances ends having to do a division by zero. Then you can enclose that in a try / except statement to deal with that possibility.

The catch-all in a main function would be applicable to the same scenario. Say your calculations end up with a division by zero somewhere deep in the call stack. From this point you can't continue, so there's no point in having a try/except statement right at the point of failure. It would make more sense to just have one at a higher level where you can reasonably recover from the error.

The example they give in the documentation is an example of this. When calling 'get_status' you would expect the file to be there. If it doesn't then you have the except statement to deal with that (although, as mentioned, in that particular case the 'with' statement is much better).

The Python philosophy is typically to "ask forgiveness, not permission." But the idea isn't to use a try-except clause to catch ALL possible errors. Ideally, each try-except will only catch the error(s) that are relevant.

BAD (doesn't specify a specific exception type):

a = [1, 2, 3]
i = 3
try:
    print a[i]
except:
    print "Not found!"

GOOD (only handles the exception we expect to get):

a = [1, 2, 3]
i = 3
try:
    print a[i]
except IndexError:
    print "Not found!"

The reason this is important is so we don't obscure other possible code errors. What if, in this example, i was 1.8? The first example would print Not Found!, obscuring the real issue, but the second example would return TypeError: list indices must be integers, not float letting us know that there's a logical flaw in our code.