56
56
applies to modules and classes.
58
58
If you wish to change the behaviour of a supported API in an incompatible
59
way, you need to change its name as well. For instance, if I add a optional keyword
59
way, you need to change its name as well. For instance, if I add an optional keyword
60
60
parameter to branch.commit - that's fine. On the other hand, if I add a
61
61
keyword parameter to branch.commit which is a *required* transaction
62
62
object, I should rename the API - i.e. to 'branch.commit_transaction'.
67
67
details for you - such as updating the docstring, and issuing a warning
68
68
when the old api is used.
70
For unsupported API's, it does not hurt to follow this discipline, but its
70
For unsupported API's, it does not hurt to follow this discipline, but it's
71
71
not required. Minimally though, please try to rename things so that
72
72
callers will at least get an AttributeError rather than weird results.
78
78
There are some common requirements in the library: some parameters need to be
79
79
unicode safe, some need byte strings, and so on. At the moment we have
80
80
only codified one specific pattern: Parameters that need to be unicode
81
should be check via 'bzrlib.osutils.safe_unicode'. This will coerce the
81
should be checked via 'bzrlib.osutils.safe_unicode'. This will coerce the
82
82
input into unicode in a consistent fashion, allowing trivial strings to be
83
83
used for programmer convenience, but not performing unpredictably in the
84
84
presence of different locales.
209
209
> factory, then yes, foo_factory is what I would use.
215
Several places in Bazaar use (or will use) a registry, which is a
216
mapping from names to objects or classes. The registry allows for
217
loading in registered code only when it's needed, and keeping
218
associated information such as a help string or description.
224
To make startup time faster, we use the ``bzrlib.lazy_import`` module to
225
delay importing modules until they are actually used. ``lazy_import`` uses
226
the same syntax as regular python imports. So to import a few modules in a
229
from bzrlib.lazy_import import lazy_import
230
lazy_import(globals(), """
239
revision as _mod_revision,
241
import bzrlib.transport
245
At this point, all of these exist as a ``ImportReplacer`` object, ready to
246
be imported once a member is accessed. Also, when importing a module into
247
the local namespace, which is likely to clash with variable names, it is
248
recommended to prefix it as ``_mod_<module>``. This makes it clean that
249
the variable is a module, and these object should be hidden anyway, since
250
they shouldn't be imported into other namespaces.
253
Modules versus Members
254
~~~~~~~~~~~~~~~~~~~~~~
256
While it is possible for ``lazy_import()`` to import members of a module
257
when using the ``from module import member`` syntax, it is recommended to
258
only use that syntax to load sub modules ``from module import submodule``.
259
This is because variables and classes can frequently be used without
260
needing a sub-member for example::
262
lazy_import(globals(), """
263
from module import MyClass
267
return isinstance(x, MyClass)
269
This will incorrectly fail, because ``MyClass`` is a ``ImportReplacer``
270
object, rather than the real class.
273
Passing to other variables
274
~~~~~~~~~~~~~~~~~~~~~~~~~~
276
It also is incorrect to assign ``ImportReplacer`` objects to other variables.
277
Because the replacer only knows about the original name, it is unable to
278
replace other variables. The ``ImportReplacer`` class will raise an
279
``IllegalUseOfScopeReplacer`` exception if it can figure out that this
280
happened. But it requires accessing a member more than once from the new
281
variable, so some bugs are not detected right away.
279
352
the command. We do this so that the library api has continual pressure
280
353
on it to be as functional as the command line in a simple manner, and
281
354
to isolate knock-on effects throughout the blackbox test suite when a
282
command changes it name or signature. Ideally only the tests for a
355
command changes its name or signature. Ideally only the tests for a
283
356
given command are affected when a given command is changed.
358
4. If you have a test which does actually require running bzr in a
359
subprocess you can use ``run_bzr_subprocess``. By default the spawned
360
process will not load plugins unless ``--allow-plugins`` is supplied.
added
removed
HACKING
