Rev 2831: (mbp) document and test deprecated static methods in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

[Canonical.com Patch Queue Manager]

At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 2831
revision-id: pqm at pqm.ubuntu.com-20070918045733-es6jch43pxvogvhj
parent: pqm at pqm.ubuntu.com-20070918034007-n72x452efuovdelm
parent: mbp at sourcefrog.net-20070918042120-wg39u5k1itshbsks
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Tue 2007-09-18 05:57:33 +0100
message:
  (mbp) document and test deprecated static methods
modified:
  bzrlib/symbol_versioning.py    symbol_versioning.py-20060105104851-9ecf8af605d15a80
  bzrlib/tests/test_symbol_versioning.py test_symbol_versioning.py-20060105104851-51d7722c2018d42b
  doc/developers/HACKING.txt     HACKING-20050805200004-2a5dc975d870f78c
    ------------------------------------------------------------
    revno: 2825.3.4
    merged: mbp at sourcefrog.net-20070918042120-wg39u5k1itshbsks
    parent: mbp at sourcefrog.net-20070918041604-olnnd90npihbyi2b
    committer: Martin Pool <mbp at sourcefrog.net>
    branch nick: trivial
    timestamp: Tue 2007-09-18 14:21:20 +1000
    message:
      Better explanation of deprecation
    ------------------------------------------------------------
    revno: 2825.3.3
    merged: mbp at sourcefrog.net-20070918041604-olnnd90npihbyi2b
    parent: mbp at sourcefrog.net-20070918041105-mk931ryjv20o3dvu
    committer: Martin Pool <mbp at sourcefrog.net>
    branch nick: trivial
    timestamp: Tue 2007-09-18 14:16:04 +1000
    message:
      Add basic test for calling deprecated static methods
    ------------------------------------------------------------
    revno: 2825.3.2
    merged: mbp at sourcefrog.net-20070918041105-mk931ryjv20o3dvu
    parent: mbp at sourcefrog.net-20070917034746-buzi0gf7uptisz4y
    committer: Martin Pool <mbp at sourcefrog.net>
    branch nick: trivial
    timestamp: Tue 2007-09-18 14:11:05 +1000
    message:
      doc
    ------------------------------------------------------------
    revno: 2825.3.1
    merged: mbp at sourcefrog.net-20070917034746-buzi0gf7uptisz4y
    parent: pqm at pqm.ubuntu.com-20070917005035-cshdkpzbj63id1uw
    committer: Martin Pool <mbp at sourcefrog.net>
    branch nick: trivial
    timestamp: Mon 2007-09-17 13:47:46 +1000
    message:
      Developer docs about deprecation
=== modified file 'bzrlib/symbol_versioning.py'
--- a/bzrlib/symbol_versioning.py	2007-08-17 05:16:14 +0000
+++ b/bzrlib/symbol_versioning.py	2007-09-18 04:11:05 +0000
@@ -114,6 +114,12 @@
 
 def deprecated_method(deprecation_version):
     """Decorate a method so that use of it will trigger a warning.
+
+    To deprecate a static or class method, use 
+
+        @staticmethod
+        @deprecated_function
+        def ...
     
     To deprecate an entire class, decorate __init__.
     """

=== modified file 'bzrlib/tests/test_symbol_versioning.py'
--- a/bzrlib/tests/test_symbol_versioning.py	2007-01-11 08:08:21 +0000
+++ b/bzrlib/tests/test_symbol_versioning.py	2007-09-18 04:21:20 +0000
@@ -1,5 +1,6 @@
 # Copyright (C) 2006, 2007 Canonical Ltd
 #   Authors: Robert Collins <robert.collins at canonical.com>
+#   and others
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -56,6 +57,31 @@
         """
         return 1
 
+    @staticmethod
+    @symbol_versioning.deprecated_function(symbol_versioning.zero_seven)
+    def deprecated_static():
+        """Deprecated static."""
+        return 1
+
+    def test_deprecated_static(self):
+        # XXX: The results are not quite right because the class name is not
+        # shown - however it is enough to give people a good indication of
+        # where the problem is.
+        expected_warning = (
+            "bzrlib.tests.test_symbol_versioning."
+            "deprecated_static "
+            "was deprecated in version 0.7.", DeprecationWarning, 2)
+        expected_docstring = (
+            'Deprecated static.\n'
+            '\n'
+            'This function was deprecated in version 0.7.\n'
+            )
+        self.check_deprecated_callable(
+            expected_warning, expected_docstring,
+            "deprecated_static",
+            "bzrlib.tests.test_symbol_versioning",
+            self.deprecated_static)
+
     def test_deprecated_method(self):
         expected_warning = (
             "bzrlib.tests.test_symbol_versioning."

=== modified file 'doc/developers/HACKING.txt'
--- a/doc/developers/HACKING.txt	2007-09-10 10:05:51 +0000
+++ b/doc/developers/HACKING.txt	2007-09-18 04:21:20 +0000
@@ -621,6 +621,27 @@
 callers will at least get an AttributeError rather than weird results.
 
 
+Deprecation decorators
+----------------------
+
+``bzrlib.symbol_versioning`` provides decorators that can be attached to
+methods, functions, and other interfaces to indicate that they should no
+longer be used.
+
+To deprecate a static method you must call ``deprecated_function``
+(**not** method), after the staticmethod call::
+
+    @staticmethod
+    @deprecated_function(zero_ninetyone)
+    def create_repository(base, shared=False, format=None):
+
+When you deprecate an API, you should not just delete its tests, because
+then we might introduce bugs in them.  If the API is still present at all,
+it should still work.  The basic approach is to use
+``TestCase.applyDeprecated`` which in one step checks that the API gives
+the expected deprecation message, and also returns the real result from
+the method, so that tests can keep running.
+
 Coding Style Guidelines
 =======================