~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to HACKING

  • Committer: Martin Pool
  • Date: 2006-10-15 11:57:58 UTC
  • mto: This revision was merged to the branch mainline in revision 2119.
  • Revision ID: mbp@sourcefrog.net-20061015115758-041391cf08503621
Clean up BzrNewError, other exception classes and users.

This cleans up the probably-mistaken BzrNewError behaviour of using error
class docstrings as their format string.  Instead errors can define a _fmt
attribute with the same meaning.  The docstring is now reserved for its
regular purpose of documentation for programmers.  This behaviour is added to
BzrError.  BzrNewError is left in place for compatibility but no builtin
errors use it anymore and it gives a deprecation warning on construction.

BzrError now accepts either a single preformatted string, or a set of named
parameters to be substituted in to a format string for that class.  This 
behaviour is cleaned up and a couple of callers that depended on the
Python2.4-style exception args tuple are fixed.

Display of unprintable errors is slightly more robust.

errors.IncompatibleFormat was defined twice (shadowing the first
definition), so one use was disambiguated to IncompatibleBundleFormat.

UnsupportedEOLMarker called the wrong superclass constructor.

test_time_creates_benchmark_in_result was too dependent on benchmark
timing and has been loosened.

Some error representations changed slightly because of this (e.g. in use
of punctuation.)

Show diffs side-by-side

added added

removed removed

Lines of Context:
371
371
Errors and exceptions
372
372
=====================
373
373
 
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.
 
375
 
 
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
 
380
error.
 
381
 
 
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
 
386
KeyboardInterrupt.
 
387
 
 
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.
 
396
 
 
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.
 
399
 
 
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.
 
404
 
 
405
New exception classes should be defined when callers might want to catch
 
406
that exception specifically, or when it needs a substantially different
 
407
format string.
 
408
 
 
409
Exception strings should start with a capital letter and should not have a
 
410
final fullstop.
 
411
 
378
412
 
379
413
 
380
414
Jargon