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.)
87
* Don't use the ``with`` statement.
89
* Don't ``from . import``.
91
* Don't use ``try/except/finally``, which is not supported in Python2.4,
92
use separate nested ``try/except`` and ``try/finally`` blocks.
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
83
compatibility using the ``-3`` option of Python2.6.)
95
86
hasattr and getattr
101
92
if getattr(thing, 'name', None) is None
98
``**kwargs`` in the prototype of a function should be used sparingly.
99
It can be good on higher-order functions that decorate other functions,
100
such as ``addCleanup`` or ``assertRaises``, or on functions that take only
101
(or almost only) kwargs, where any kwargs can be passed.
103
Otherwise, be careful: if the parameters to a function are a bit complex
104
and might vary over time (e.g. the ``commit`` API) then we prefer to pass an
105
object rather than a bag of positional and/or keyword args. If you have
106
an arbitrary set of keys and values that are different with each use (e.g.
107
string interpolation inputs) then again that should not be mixed in with
108
the regular positional/keyword args, it seems like a different category of
112
Imitating standard objects
113
==========================
115
Don't provide methods that imitate built-in classes (eg ``__in__``,
116
``__call__``, ``__int__``, ``__getitem__``) unless the class you're
117
implementing really does act like the builtin class, in semantics and
120
For example, old code lets you say ``file_id in inv`` but we no longer
121
consider this good style. Instead, say more explicitly
122
``inv.has_id(file_id)``.
124
``__repr__``, ``__cmp__``, ``__str__`` are usually fine.
157
180
why in a comment.
159
182
1. Never rely on a ``__del__`` method running. If there is code that
160
must run, do it from a ``finally`` block instead.
183
must run, instead have a ``finally`` block or an ``addCleanup`` call an
184
explicit ``close`` method.
162
186
2. Never ``import`` from inside a ``__del__`` method, or you may crash the
165
3. In some places we raise a warning from the destructor if the object
166
has not been cleaned up or closed. This is considered OK: the warning
167
may not catch every case but it's still useful sometimes.
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.
197
In short, just don't use ``__del__``.
333
362
Because repr methods are often called when something has already gone
334
363
wrong, they should be written somewhat more defensively than most code.
364
They shouldn't have side effects like doing network or disk
335
366
The object may be half-initialized or in some other way in an illegal
336
367
state. The repr method shouldn't raise an exception, or it may hide the
337
368
(probably more useful) underlying exception.
353
384
``Exception`` (which excludes system errors in Python2.5 and later) would
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.
454
492
* Don't say "open source" when you mean "free software".
498
If you need to import a module (or attribute of a module) named in a
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.
457
509
vim: ft=rst tw=74 ai
added
removed
doc/developers/code-style.txt
