← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/code-style.txt

merge trunk

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/code-style.txt
78
78
===============
79
79
 
80
80
Bazaar supports Python from 2.4 through 2.6, and in the future we want to
81
 
support Python 3.0.  Avoid using language features added in 2.5 or 2.6, or
82
 
features deprecated in Python 3.0.  (You can check v3 compatibility using
83
 
the ``-3`` option of Python2.6.)
 
81
support Python 2.7 and 3.0.  Avoid using language features added in 2.5,
 
82
2.6 or 2.7, or features deprecated in Python 3.0.  (You can check v3
 
83
compatibility using the ``-3`` option of Python2.6.)
84
84
 
85
85
Specifically:
86
86
 
364
364
 
365
365
Because repr methods are often called when something has already gone
366
366
wrong, they should be written somewhat more defensively than most code.
 
367
They shouldn't have side effects like doing network or disk
 
368
IO.
367
369
The object may be half-initialized or in some other way in an illegal
368
370
state.  The repr method shouldn't raise an exception, or it may hide the
369
371
(probably more useful) underlying exception.
385
387
``Exception`` (which excludes system errors in Python2.5 and later) would
386
388
be better.
387
389
 
 
390
The ``__str__`` method on exceptions should be small and have no side
 
391
effects, following the rules given for `Object string representations`_.
 
392
In particular it should not do any network IO, or complicated
 
393
introspection of other objects.  All the state needed to present the
 
394
exception to the user should be gathered before the error is raised.
 
395
In other words, exceptions should basically be value objects.
 
396
 
388
397
 
389
398
Test coverage
390
399
=============
485
494
 
486
495
 * Don't say "open source" when you mean "free software".
487
496
 
 
497
 
 
498
Dynamic imports
 
499
===============
 
500
 
 
501
If you need to import a module (or attribute of a module) named in a
 
502
variable:
 
503
 
 
504
 * If importing a module, not an attribute, and the module is a top-level
 
505
   module (i.e. has no dots in the name), then it's ok to use the builtin
 
506
   ``__import__``, e.g. ``__import__(module_name)``.
 
507
 * In all other cases, prefer ``bzrlib.pyutils.get_named_object`` to the
 
508
   built-in ``__import__``.  ``__import__`` has some subtleties and
 
509
   unintuitive behaviours that make it hard to use correctly.
 
510
 
488
511
..
489
512
   vim: ft=rst tw=74 ai