← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to HACKING

  • Committer: John Arbash Meinel
  • Date: 2006-10-16 01:25:46 UTC
  • mfrom: (2071 +trunk)
  • mto: This revision was merged to the branch mainline in revision 2080.
  • Revision ID: john@arbash-meinel.com-20061016012546-d01a0740671b4d73
[merge] bzr.dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
HACKING
56
56
applies to modules and classes.
57
57
 
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.
69
69
 
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.
73
73
 
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.
227
227
  from bzrlib import (
228
228
     errors,
229
229
     transport,
230
 
     foo as bar,
 
230
     revision as _mod_revision,
231
231
     )
232
232
  import bzrlib.transport
233
233
  import bzrlib.xml5
234
234
  """)
235
235
 
236
236
At this point, all of these exist as a ``ImportReplacer`` object, ready to
237
 
be imported once a member is accessed.
 
237
be imported once a member is accessed. Also, when importing a module into
 
238
the local namespace, which is likely to clash with variable names, it is
 
239
recommended to prefix it as ``_mod_<module>``. This makes it clean that
 
240
the variable is a module, and these object should be hidden anyway, since
 
241
they shouldn't be imported into other namespaces.
238
242
 
239
243
 
240
244
Modules versus Members
241
245
~~~~~~~~~~~~~~~~~~~~~~
242
246
 
243
247
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
 
248
when using the ``from module import member`` syntax, it is recommended to
245
249
only use that syntax to load sub modules ``from module import submodule``.
246
250
This is because variables and classes can frequently be used without
247
251
needing a sub-member for example::
338
342
    the command. We do this so that the library api has continual pressure
339
343
    on it to be as functional as the command line in a simple manner, and
340
344
    to isolate knock-on effects throughout the blackbox test suite when a
341
 
    command changes it name or signature. Ideally only the tests for a
 
345
    command changes its name or signature. Ideally only the tests for a
342
346
    given command are affected when a given command is changed.
343
347
 
344
348
Doctests
463
467
    that cannot be displayed.
464
468
  
465
469
  strict
466
 
    Attempting to print and unprintable character will cause a UnicodeError.
 
470
    Attempting to print an unprintable character will cause a UnicodeError.
467
471
    This is for commands that are intended more as scripting support, rather
468
472
    than plain user review.
469
473
    For exampl: ``bzr ls`` is designed to be used with shell scripting. One