650
650
the form of URL components.
659
We have a commitment to 6 months API stability - any supported symbol in a
660
release of bzr MUST NOT be altered in any way that would result in
661
breaking existing code that uses it. That means that method names,
662
parameter ordering, parameter names, variable and attribute names etc must
663
not be changed without leaving a 'deprecated forwarder' behind. This even
664
applies to modules and classes.
666
If you wish to change the behaviour of a supported API in an incompatible
667
way, you need to change its name as well. For instance, if I add an optional keyword
668
parameter to branch.commit - that's fine. On the other hand, if I add a
669
keyword parameter to branch.commit which is a *required* transaction
670
object, I should rename the API - i.e. to 'branch.commit_transaction'.
672
When renaming such supported API's, be sure to leave a deprecated_method (or
673
_function or ...) behind which forwards to the new API. See the
674
bzrlib.symbol_versioning module for decorators that take care of the
675
details for you - such as updating the docstring, and issuing a warning
676
when the old api is used.
678
For unsupported API's, it does not hurt to follow this discipline, but it's
679
not required. Minimally though, please try to rename things so that
680
callers will at least get an AttributeError rather than weird results.
683
Deprecation decorators
684
----------------------
686
``bzrlib.symbol_versioning`` provides decorators that can be attached to
687
methods, functions, and other interfaces to indicate that they should no
690
To deprecate a static method you must call ``deprecated_function``
691
(**not** method), after the staticmethod call::
694
@deprecated_function(zero_ninetyone)
695
def create_repository(base, shared=False, format=None):
697
When you deprecate an API, you should not just delete its tests, because
698
then we might introduce bugs in them. If the API is still present at all,
699
it should still work. The basic approach is to use
700
``TestCase.applyDeprecated`` which in one step checks that the API gives
701
the expected deprecation message, and also returns the real result from
702
the method, so that tests can keep running.
704
653
Coding Style Guidelines
705
=======================
654
#######################
707
656
hasattr and getattr
710
659
``hasattr`` should not be used because it swallows exceptions including
711
660
``KeyboardInterrupt``. Instead, say something like ::
965
908
being phased out.
911
Object string representations
912
=============================
914
Python prints objects using their ``__repr__`` method when they are
915
written to logs, exception tracebacks, or the debugger. We want
916
objects to have useful representations to help in determining what went
919
If you add a new class you should generally add a ``__repr__`` method
920
unless there is an adequate method in a parent class. There should be a
923
Representations should typically look like Python constructor syntax, but
924
they don't need to include every value in the object and they don't need
925
to be able to actually execute. They're to be read by humans, not
926
machines. Don't hardcode the classname in the format, so that we get the
927
correct value if the method is inherited by a subclass. If you're
928
printing attributes of the object, including strings, you should normally
929
use ``%r`` syntax (to call their repr in turn).
931
Try to avoid the representation becoming more than one or two lines long.
932
(But balance this against including useful information, and simplicity of
935
Because repr methods are often called when something has already gone
936
wrong, they should be written more defensively than most code. The object
937
may be half-initialized or in some other way in an illegal state. The
938
repr method shouldn't raise an exception, or it may hide the (probably
939
more useful) underlying exception.
945
return '%s(%r)' % (self.__class__.__name__,
948
return 'FooObject(**unprintable**)'
957
We have a commitment to 6 months API stability - any supported symbol in a
958
release of bzr MUST NOT be altered in any way that would result in
959
breaking existing code that uses it. That means that method names,
960
parameter ordering, parameter names, variable and attribute names etc must
961
not be changed without leaving a 'deprecated forwarder' behind. This even
962
applies to modules and classes.
964
If you wish to change the behaviour of a supported API in an incompatible
965
way, you need to change its name as well. For instance, if I add an optional keyword
966
parameter to branch.commit - that's fine. On the other hand, if I add a
967
keyword parameter to branch.commit which is a *required* transaction
968
object, I should rename the API - i.e. to 'branch.commit_transaction'.
970
When renaming such supported API's, be sure to leave a deprecated_method (or
971
_function or ...) behind which forwards to the new API. See the
972
bzrlib.symbol_versioning module for decorators that take care of the
973
details for you - such as updating the docstring, and issuing a warning
974
when the old api is used.
976
For unsupported API's, it does not hurt to follow this discipline, but it's
977
not required. Minimally though, please try to rename things so that
978
callers will at least get an AttributeError rather than weird results.
981
Deprecation decorators
982
----------------------
984
``bzrlib.symbol_versioning`` provides decorators that can be attached to
985
methods, functions, and other interfaces to indicate that they should no
986
longer be used. For example::
988
@deprecated_method(deprecated_in((0, 1, 4)))
990
return self._new_foo()
992
To deprecate a static method you must call ``deprecated_function``
993
(**not** method), after the staticmethod call::
996
@deprecated_function(deprecated_in((0, 1, 4)))
997
def create_repository(base, shared=False, format=None):
999
When you deprecate an API, you should not just delete its tests, because
1000
then we might introduce bugs in them. If the API is still present at all,
1001
it should still work. The basic approach is to use
1002
``TestCase.applyDeprecated`` which in one step checks that the API gives
1003
the expected deprecation message, and also returns the real result from
1004
the method, so that tests can keep running.
1006
Deprecation warnings will be suppressed for final releases, but not for
1007
development versions or release candidates, or when running ``bzr
1008
selftest``. This gives developers information about whether their code is
1009
using deprecated functions, but avoids confusing users about things they
added
removed
doc/developers/HACKING.txt
