← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

  • Committer: Andrew Bennetts
  • Date: 2010-10-08 08:15:14 UTC
  • mto: This revision was merged to the branch mainline in revision 5498.
  • Revision ID: andrew.bennetts@canonical.com-20101008081514-dviqzrdfwyzsqbz2
Split NEWS into per-release doc/en/release-notes/bzr-*.txt

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/code-style.txt
77
77
Python versions
78
78
===============
79
79
 
80
 
Bazaar supports Python from 2.6 through 2.7, and in the future we want to
81
 
support Python 3.  Avoid using language features added in
82
 
2.7, or features deprecated in Python 3.0.  (You can check v3
 
80
Bazaar supports Python from 2.4 through 2.6, and in the future we want to
 
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
83
compatibility using the ``-3`` option of Python2.6.)
84
84
 
 
85
Specifically:
 
86
 
 
87
* Don't use the ``with`` statement.
 
88
 
 
89
* Don't ``from . import``.
 
90
 
 
91
* Don't use ``try/except/finally``, which is not supported in Python2.4,
 
92
  use separate nested ``try/except`` and ``try/finally`` blocks.
 
93
 
85
94
 
86
95
hasattr and getattr
87
96
===================
180
189
   why in a comment.
181
190
 
182
191
1. Never rely on a ``__del__`` method running.  If there is code that
183
 
   must run, instead have a ``finally`` block or an ``addCleanup`` call an
184
 
   explicit ``close`` method.
 
192
   must run, do it from a ``finally`` block instead.
185
193
 
186
194
2. Never ``import`` from inside a ``__del__`` method, or you may crash the
187
195
   interpreter!!
188
196
 
189
 
3. Prior to bzr 2.4, we sometimes used to raise warnings from del methods
190
 
   that the object was not cleaned up or closed.  We no longer do this:
191
 
   failure to close the object doesn't cause a test failure; the warning
192
 
   appears an arbitrary long time after the problem occurred (the object
193
 
   being leaked); merely having a del method inhibits Python gc; the
194
 
   warnings appear to users and upset them; they can also break tests that
195
 
   are checking what appears on stderr.
196
 
   
197
 
In short, just don't use ``__del__``.
 
197
3. In some places we raise a warning from the destructor if the object
 
198
   has not been cleaned up or closed.  This is considered OK: the warning
 
199
   may not catch every case but it's still useful sometimes.
 
200
 
198
201
 
199
202
Cleanup methods
200
203
===============
361
364
 
362
365
Because repr methods are often called when something has already gone
363
366
wrong, they should be written somewhat more defensively than most code.
364
 
They shouldn't have side effects like doing network or disk
365
 
IO.
366
367
The object may be half-initialized or in some other way in an illegal
367
368
state.  The repr method shouldn't raise an exception, or it may hide the
368
369
(probably more useful) underlying exception.
384
385
``Exception`` (which excludes system errors in Python2.5 and later) would
385
386
be better.
386
387
 
387
 
The ``__str__`` method on exceptions should be small and have no side
388
 
effects, following the rules given for `Object string representations`_.
389
 
In particular it should not do any network IO, or complicated
390
 
introspection of other objects.  All the state needed to present the
391
 
exception to the user should be gathered before the error is raised.
392
 
In other words, exceptions should basically be value objects.
393
 
 
394
388
 
395
389
Test coverage
396
390
=============
491
485
 
492
486
 * Don't say "open source" when you mean "free software".
493
487
 
494
 
 
495
 
Dynamic imports
496
 
===============
497
 
 
498
 
If you need to import a module (or attribute of a module) named in a
499
 
variable:
500
 
 
501
 
 * If importing a module, not an attribute, and the module is a top-level
502
 
   module (i.e. has no dots in the name), then it's ok to use the builtin
503
 
   ``__import__``, e.g. ``__import__(module_name)``.
504
 
 * In all other cases, prefer ``bzrlib.pyutils.get_named_object`` to the
505
 
   built-in ``__import__``.  ``__import__`` has some subtleties and
506
 
   unintuitive behaviours that make it hard to use correctly.
507
 
 
508
488
..
509
489
   vim: ft=rst tw=74 ai