Rev 2553: Add require_api API. in sftp://rookery/~/public_html/baz2.0/api_api

Robert Collins robertc at robertcollins.net
Tue Jun 26 09:52:23 BST 2007


At sftp://rookery/~/public_html/baz2.0/api_api

------------------------------------------------------------
revno: 2553
revision-id: robertc at robertcollins.net-20070626085220-iovhwfjflk8vffbh
parent: robertc at robertcollins.net-20070626082724-q95taws12ajox2io
committer: Robert Collins <robertc at robertcollins.net>
branch nick: api_api
timestamp: Tue 2007-06-26 18:52:20 +1000
message:
  Add require_api API.
modified:
  bzrlib/api.py                  api.py-20070626082640-35lspz7j0ys7a8ld-1
  bzrlib/errors.py               errors.py-20050309040759-20512168c4e14fbd
  bzrlib/tests/test_api.py       testapi.py-20051027033546-6f9be2d308d18a52
  bzrlib/tests/test_errors.py    test_errors.py-20060210110251-41aba2deddf936a8
=== modified file 'bzrlib/api.py'
--- a/bzrlib/api.py	2007-06-26 08:27:24 +0000
+++ b/bzrlib/api.py	2007-06-26 08:52:20 +0000
@@ -14,7 +14,12 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
-"""Library API versioning support."""
+"""Library API versioning support.
+
+Added in bzrlib 0.18 this allows export of compatibility information about
+bzrlib. Please see doc/developers/api-versioning.txt for design details and
+examples.
+"""
 
 import bzrlib
 from bzrlib.lazy_import import lazy_import
@@ -31,6 +36,8 @@
         there is a version_info attribute, its first three elements are used.
         Finally if there was no version_info attribute, the current api version
         of bzrlib itself is used.
+
+    Added in bzrlib 0.18.
     """
     try:
         return object_with_api.api_current_version
@@ -47,8 +54,29 @@
     :param object_with_api: An object to look for an API version on. If the
         object has a api_minimum_version attribute, that is used. Otherwise the
         minimum api version of bzrlib itself is used.
+
+    Added in bzrlib 0.18.
     """
     try:
         return object_with_api.api_minimum_version
     except AttributeError:
         return get_minimum_api_version(bzrlib)
+
+
+def require_api(object_with_api, wanted_api):
+    """Check if object_with_api supports the api version wanted_api.
+
+    :param object_with_api: An object which exports an API minimum and current
+        version. See get_minimum_api_version and get_current_api_version for
+        details.
+    :param wanted_api: The API version for which support is required.
+    :return None:
+    :raises IncompatibleAPI: When the wanted_api is not supported by
+        object_with_api.
+
+    Added in bzrlib 0.18.
+    """
+    current = get_current_api_version(object_with_api)
+    minimum = get_minimum_api_version(object_with_api)
+    if wanted_api < minimum or wanted_api > current:
+        raise IncompatibleAPI(object_with_api, wanted_api, minimum, current)

=== modified file 'bzrlib/errors.py'
--- a/bzrlib/errors.py	2007-06-25 13:17:32 +0000
+++ b/bzrlib/errors.py	2007-06-26 08:52:20 +0000
@@ -186,6 +186,18 @@
         self.class_name = class_name
 
 
+class IncompatibleAPI(BzrError):
+
+    _fmt = 'The API for "%(api)s" is not compatible with "%(wanted)s". '\
+        'It supports versions "%(minimum)s" to "%(current)s".'
+
+    def __init__(self, api, wanted, minimum, current):
+        self.api = api
+        self.wanted = wanted
+        self.minimum = minimum
+        self.current = current
+
+
 class InvalidEntryName(BzrError):
     
     _fmt = "Invalid entry name: %(name)s"

=== modified file 'bzrlib/tests/test_api.py'
--- a/bzrlib/tests/test_api.py	2007-06-26 08:27:24 +0000
+++ b/bzrlib/tests/test_api.py	2007-06-26 08:52:20 +0000
@@ -23,6 +23,7 @@
 
 import bzrlib
 import bzrlib.api
+from bzrlib.errors import IncompatibleAPI
 from bzrlib.tests import TestCase
 
 class APITests(TestCase):
@@ -69,3 +70,49 @@
         an_object = TrivialObject()
         self.assertEqual(bzrlib.version_info[0:3],
             bzrlib.api.get_current_api_version(an_object))
+
+    def test_require_api_wanted_is_minimum_is_ok(self):
+        an_object = TrivialObject()
+        an_object.api_minimum_version = (1, 2, 3)
+        an_object.api_current_version = (4, 5, 6)
+        bzrlib.api.require_api(an_object, (1, 2, 3))
+
+    def test_require_api_wanted_is_current_is_ok(self):
+        an_object = TrivialObject()
+        an_object.api_minimum_version = (1, 2, 3)
+        an_object.api_current_version = (4, 5, 6)
+        bzrlib.api.require_api(an_object, (4, 5, 6))
+
+    def test_require_api_wanted_is_above_minimum_is_ok(self):
+        an_object = TrivialObject()
+        an_object.api_minimum_version = (1, 2, 3)
+        an_object.api_current_version = (4, 5, 6)
+        bzrlib.api.require_api(an_object, (1, 2, 4))
+
+    def test_require_api_wanted_is_below_current_is_ok(self):
+        an_object = TrivialObject()
+        an_object.api_minimum_version = (1, 2, 3)
+        an_object.api_current_version = (4, 5, 6)
+        bzrlib.api.require_api(an_object, (4, 5, 5))
+
+    def test_require_api_wanted_is_below_minimum_raises(self):
+        an_object = TrivialObject()
+        an_object.api_minimum_version = (1, 2, 3)
+        an_object.api_current_version = (4, 5, 6)
+        err = self.assertRaises(IncompatibleAPI,
+            bzrlib.api.require_api, an_object, (1, 2, 2))
+        self.assertEqual(err.api, an_object)
+        self.assertEqual(err.wanted, (1, 2, 2))
+        self.assertEqual(err.minimum, (1, 2, 3))
+        self.assertEqual(err.current, (4, 5, 6))
+
+    def test_require_api_wanted_is_above_current_raises(self):
+        an_object = TrivialObject()
+        an_object.api_minimum_version = (1, 2, 3)
+        an_object.api_current_version = (4, 5, 6)
+        err = self.assertRaises(IncompatibleAPI,
+            bzrlib.api.require_api, an_object, (4, 5, 7))
+        self.assertEqual(err.api, an_object)
+        self.assertEqual(err.wanted, (4, 5, 7))
+        self.assertEqual(err.minimum, (1, 2, 3))
+        self.assertEqual(err.current, (4, 5, 6))

=== modified file 'bzrlib/tests/test_errors.py'
--- a/bzrlib/tests/test_errors.py	2007-04-26 09:07:38 +0000
+++ b/bzrlib/tests/test_errors.py	2007-06-26 08:52:20 +0000
@@ -46,6 +46,13 @@
         self.assertEqualDiff('The prefix foo is in the help search path twice.',
             str(error))
 
+    def test_incompatibleAPI(self):
+        error = errors.IncompatibleAPI("module", (1, 2, 3), (4, 5, 6), (7, 8, 9))
+        self.assertEqualDiff(
+            'The API for "module" is not compatible with "(1, 2, 3)". '
+            'It supports versions "(4, 5, 6)" to "(7, 8, 9)".',
+            str(error))
+
     def test_inventory_modified(self):
         error = errors.InventoryModified("a tree to be repred")
         self.assertEqualDiff("The current inventory for the tree 'a tree to "



More information about the bazaar-commits mailing list