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
-------------------
260
260
option, then you should be writing a UI test. If you are both adding UI
261
261
functionality and library functionality, you will want to write tests for
262
262
both the UI and the core behaviours. We call UI tests 'blackbox' tests
263
and they are found in bzrlib/tests/blackbox/*.py.
263
and they are found in ``bzrlib/tests/blackbox/*.py``.
265
265
When writing blackbox tests please honour the following conventions:
365
366
for those characters. (Although this is not totally reliable we might still
366
367
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
369
A similar edge case is that the url ``http://foo/sweet%2Fsour`` contains
369
370
one directory component whose name is "sweet/sour". The escaped slash is
370
371
not a directory separator. If we try to convert URLs to regular Unicode
371
372
paths this information will be lost.
376
377
the form of URL components.
380
Unicode and Encoding Support
381
============================
383
This section discusses various techniques that Bazaar uses to handle
384
characters that are outside the ASCII set.
389
When a ``Command`` object is created, it is given a member variable
390
accessible by ``self.outf``. This is a file-like object, which is bound to
391
``sys.stdout``, and should be used to write information to the screen,
392
rather than directly writing to ``sys.stdout`` or calling ``print``.
393
This file has the ability to translate Unicode objects into the correct
394
representation, based on the console encoding. Also, the class attribute
395
``encoding_type`` will effect how unprintable characters will be
396
handled. This parameter can take one of 3 values:
399
Unprintable characters will be represented with a suitable replacement
400
marker (typically '?'), and no exception will be raised. This is for
401
any command which generates text for the user to review, rather than
402
for automated processing.
403
For example: ``bzr log`` should not fail if one of the entries has text
404
that cannot be displayed.
407
Attempting to print and unprintable character will cause a UnicodeError.
408
This is for commands that are intended more as scripting support, rather
409
than plain user review.
410
For exampl: ``bzr ls`` is designed to be used with shell scripting. One
411
use would be ``bzr ls --null --unknows | xargs -0 rm``. If ``bzr``
412
printed a filename with a '?', the wrong file could be deleted. (At the
413
very least, the correct file would not be deleted). An error is used to
414
indicate that the requested action could not be performed.
417
Do not attempt to automatically convert Unicode strings. This is used
418
for commands that must handle conversion themselves.
419
For example: ``bzr diff`` needs to translate Unicode paths, but should
420
not change the exact text of the contents of the files.
423
``bzrlib.urlutils.unescape_for_display``
424
----------------------------------------
426
Because Transports work in URLs (as defined earlier), printing the raw URL
427
to the user is usually less than optimal. Characters outside the standard
428
set are printed as escapes, rather than the real character, and local
429
paths would be printed as ``file://`` urls. The function
430
``unescape_for_display`` attempts to unescape a URL, such that anything
431
that cannot be printed in the current encoding stays an escaped URL, but
432
valid characters are generated where possible.
379
435
Merge/review process
380
436
====================
added
removed
HACKING
