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
-------------------
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
wehn 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:
282
341
command changes it name or signature. Ideally only the tests for a
283
342
given command are affected when a given command is changed.
347
We make selective use of doctests__. In general they should provide
348
*examples* within the API documentation which can incidentally be tested. We
349
don't try to test every important case using doctests -- regular Python
350
tests are generally a better solution.
352
Most of these are in ``bzrlib/doc/api``. More additions are welcome.
354
__ http://docs.python.org/lib/module-doctest.html
287
359
Currently, bzr selftest is used to invoke tests.
348
425
for those characters. (Although this is not totally reliable we might still
349
426
accept these and assume they should be put into UTF-8.)
351
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
352
429
one directory component whose name is "sweet/sour". The escaped slash is
353
430
not a directory separator. If we try to convert URLs to regular Unicode
354
431
paths this information will be lost.
359
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 and 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.
362
494
Merge/review process
363
495
====================
added
removed
HACKING
