40
40
Recommended values are
42
1- Conflicts in merge-like operations, or changes are present in
42
1. Conflicts in merge-like operations, or changes are present in
43
43
diff-like operations.
44
2- Unrepresentable diff changes (i.e. binary files that we cannot show
44
2. Unrepresentable diff changes (i.e. binary files that we cannot show
46
3- An error or exception has occurred.
46
3. An error or exception has occurred.
48
48
Evolving interfaces
49
49
-------------------
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
To make startup time faster, we use the ``bzrlib.lazy_import`` module to
216
delay importing modules until they are actually used. ``lazy_import`` uses
217
the same syntax as regular python imports. So to import a few modules in a
220
from bzrlib.lazy_import import lazy_import
221
lazy_import(globals(), """
232
import bzrlib.transport
236
At this point, all of these exist as a ``ImportReplacer`` object, ready to
237
be imported once a member is accessed.
240
Modules versus Members
241
~~~~~~~~~~~~~~~~~~~~~~
243
While it is possible for ``lazy_import()`` to import members of a module
244
when using the ``from module import member`` syntax, it is recommended to
245
only use that syntax to load sub modules ``from module import submodule``.
246
This is because variables and classes can frequently be used without
247
needing a sub-member for example::
249
lazy_import(globals(), """
250
from module import MyClass
254
return isinstance(x, MyClass)
256
This will incorrectly fail, because ``MyClass`` is a ``ImportReplacer``
257
object, rather than the real class.
260
Passing to other variables
261
~~~~~~~~~~~~~~~~~~~~~~~~~~
263
It also is incorrect to assign ``ImportReplacer`` objects to other variables.
264
Because the replacer only knows about the original name, it is unable to
265
replace other variables. The ``ImportReplacer`` class will raise an
266
``IllegalUseOfScopeReplacer`` exception if it can figure out that this
267
happened. But it requires accessing a member more than once from the new
268
variable, so some bugs are not detected right away.
260
319
option, then you should be writing a UI test. If you are both adding UI
261
320
functionality and library functionality, you will want to write tests for
262
321
both the UI and the core behaviours. We call UI tests 'blackbox' tests
263
and they are found in bzrlib/tests/blackbox/*.py.
322
and they are found in ``bzrlib/tests/blackbox/*.py``.
265
324
When writing blackbox tests please honour the following conventions:
279
338
the command. We do this so that the library api has continual pressure
280
339
on it to be as functional as the command line in a simple manner, and
281
340
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
341
command changes its name or signature. Ideally only the tests for a
283
342
given command are affected when a given command is changed.
365
425
for those characters. (Although this is not totally reliable we might still
366
426
accept these and assume they should be put into UTF-8.)
368
A similar edge case is that the url ``http://foo/sweet%2Fsour" contains
428
A similar edge case is that the url ``http://foo/sweet%2Fsour`` contains
369
429
one directory component whose name is "sweet/sour". The escaped slash is
370
430
not a directory separator. If we try to convert URLs to regular Unicode
371
431
paths this information will be lost.
376
436
the form of URL components.
439
Unicode and Encoding Support
440
============================
442
This section discusses various techniques that Bazaar uses to handle
443
characters that are outside the ASCII set.
448
When a ``Command`` object is created, it is given a member variable
449
accessible by ``self.outf``. This is a file-like object, which is bound to
450
``sys.stdout``, and should be used to write information to the screen,
451
rather than directly writing to ``sys.stdout`` or calling ``print``.
452
This file has the ability to translate Unicode objects into the correct
453
representation, based on the console encoding. Also, the class attribute
454
``encoding_type`` will effect how unprintable characters will be
455
handled. This parameter can take one of 3 values:
458
Unprintable characters will be represented with a suitable replacement
459
marker (typically '?'), and no exception will be raised. This is for
460
any command which generates text for the user to review, rather than
461
for automated processing.
462
For example: ``bzr log`` should not fail if one of the entries has text
463
that cannot be displayed.
466
Attempting to print an unprintable character will cause a UnicodeError.
467
This is for commands that are intended more as scripting support, rather
468
than plain user review.
469
For exampl: ``bzr ls`` is designed to be used with shell scripting. One
470
use would be ``bzr ls --null --unknows | xargs -0 rm``. If ``bzr``
471
printed a filename with a '?', the wrong file could be deleted. (At the
472
very least, the correct file would not be deleted). An error is used to
473
indicate that the requested action could not be performed.
476
Do not attempt to automatically convert Unicode strings. This is used
477
for commands that must handle conversion themselves.
478
For example: ``bzr diff`` needs to translate Unicode paths, but should
479
not change the exact text of the contents of the files.
482
``bzrlib.urlutils.unescape_for_display``
483
----------------------------------------
485
Because Transports work in URLs (as defined earlier), printing the raw URL
486
to the user is usually less than optimal. Characters outside the standard
487
set are printed as escapes, rather than the real character, and local
488
paths would be printed as ``file://`` urls. The function
489
``unescape_for_display`` attempts to unescape a URL, such that anything
490
that cannot be printed in the current encoding stays an escaped URL, but
491
valid characters are generated where possible.
379
494
Merge/review process
380
495
====================
added
removed
HACKING
