371
371
Errors and exceptions
372
372
=====================
374
Errors are handled through Python exceptions. They can represent user
375
errors, environmental errors or program bugs. Sometimes we can't be sure
376
at the time it's raised which case applies. See bzrlib/errors.py for
377
details on the error-handling practices.
374
Errors are handled through Python exceptions.
376
We broadly classify errors as either being either the user's fault or our
377
fault. If we think it's our fault, we show a backtrace, an invitation to
378
report the bug, and possibly other details. This is the default for
379
errors that aren't specifically recognized as being caused by a user
382
User errors are things such as referring to a file or location that
383
doesn't exist. The user could potentially fix them themselves, so they
384
get a short but helpful message. User errors either have the
385
``is_user_error`` property set, or are of particular classes such as
388
Many errors originate as "environmental errors" which are raised by Python
389
or builtin libraries -- for example IOError. These are treated as being
390
our fault, unless they're caught in a particular tight scope where we know
391
that they indicate a user errors. For example if the repository format
392
is not found, the user probably gave the wrong path or URL. But if one of
393
the files inside the repository is not found, then it's our fault --
394
either there's a bug in bzr, or something complicated has gone wrong in
395
the environment that means one internal file was deleted.
397
Many errors are defined in ``bzrlib/errors.py`` but it's OK for new errors
398
to be added near the place where they are used.
400
Exceptions are formatted for the user by conversion to a string
401
(eventually calling their ``__str__`` method.) As a convenience the
402
``._fmt`` member can be used as a template which will be mapped to the
403
error's instance dict.
405
New exception classes should be defined when callers might want to catch
406
that exception specifically, or when it needs a substantially different
409
Exception strings should start with a capital letter and should not have a