Rev 2552: Add helpers to get api versions from objects. in sftp://rookery/~/public_html/baz2.0/api_api
Robert Collins
robertc at robertcollins.net
Tue Jun 26 09:27:28 BST 2007
At sftp://rookery/~/public_html/baz2.0/api_api
------------------------------------------------------------
revno: 2552
revision-id: robertc at robertcollins.net-20070626082724-q95taws12ajox2io
parent: robertc at robertcollins.net-20070626065720-w0btzadye6lpq104
committer: Robert Collins <robertc at robertcollins.net>
branch nick: api_api
timestamp: Tue 2007-06-26 18:27:24 +1000
message:
Add helpers to get api versions from objects.
added:
bzrlib/api.py api.py-20070626082640-35lspz7j0ys7a8ld-1
modified:
bzrlib/__init__.py __init__.py-20050309040759-33e65acf91bbcd5d
bzrlib/tests/test_api.py testapi.py-20051027033546-6f9be2d308d18a52
doc/developers/api-versioning.txt apiversioning.txt-20070626065626-iiihgmhgkv91uphz-1
=== added file 'bzrlib/api.py'
--- a/bzrlib/api.py 1970-01-01 00:00:00 +0000
+++ b/bzrlib/api.py 2007-06-26 08:27:24 +0000
@@ -0,0 +1,54 @@
+# Copyright (C) 2007 Canonical Ltd
+#
+# 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
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# 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."""
+
+import bzrlib
+from bzrlib.lazy_import import lazy_import
+lazy_import(globals(), """
+from bzrlib.errors import IncompatibleAPI
+""")
+
+
+def get_current_api_version(object_with_api):
+ """Return the API version tuple for object_with_api.
+
+ :param object_with_api: An object to look for an API version on. If the
+ object has a api_current_version attribute, that is used. Otherwise if
+ 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.
+ """
+ try:
+ return object_with_api.api_current_version
+ except AttributeError:
+ try:
+ return object_with_api.version_info[0:3]
+ except AttributeError:
+ return get_current_api_version(bzrlib)
+
+
+def get_minimum_api_version(object_with_api):
+ """Return the minimum API version supported by object_with_api.
+
+ :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.
+ """
+ try:
+ return object_with_api.api_minimum_version
+ except AttributeError:
+ return get_minimum_api_version(bzrlib)
=== modified file 'bzrlib/__init__.py'
--- a/bzrlib/__init__.py 2007-06-19 00:26:28 +0000
+++ b/bzrlib/__init__.py 2007-06-26 08:27:24 +0000
@@ -37,6 +37,9 @@
version_info = (0, 18, 0, 'dev', 0)
+# API compatibility version: bzrlib is currently API compatible with 0.18.
+api_minimum_version = (0, 18, 0)
+
if version_info[3] == 'final':
version_string = '%d.%d.%d' % version_info[:3]
else:
=== modified file 'bzrlib/tests/test_api.py'
--- a/bzrlib/tests/test_api.py 2006-10-11 23:08:27 +0000
+++ b/bzrlib/tests/test_api.py 2007-06-26 08:27:24 +0000
@@ -21,10 +21,8 @@
relevant test modules.
"""
-import os
-import sys
-
import bzrlib
+import bzrlib.api
from bzrlib.tests import TestCase
class APITests(TestCase):
@@ -35,3 +33,39 @@
self.assert_(isinstance(bzrlib.version_string, str))
self.assert_(isinstance(bzrlib.version_info, tuple))
self.assertEqual(len(bzrlib.version_info), 5)
+
+
+class TrivialObject(object):
+ """This class allows assignment to any attribute."""
+
+
+class TestAPIVersioning(TestCase):
+
+ def test_get_minimum_api_version_reads_api_minimum_version(self):
+ an_object = TrivialObject()
+ an_object.api_minimum_version = (0, 1, 2)
+ self.assertEqual((0, 1, 2),
+ bzrlib.api.get_minimum_api_version(an_object))
+
+ def test_get_minimum_api_version_fallsback_to_bzr_minimum_version(self):
+ an_object = TrivialObject()
+ self.assertEqual(bzrlib.api_minimum_version,
+ bzrlib.api.get_minimum_api_version(an_object))
+
+ def test_get_current_api_version_reads_api_current_version(self):
+ an_object = TrivialObject()
+ an_object.api_current_version = (3, 2, 1)
+ an_object.version_info = (1, 2, 3, "final", 0)
+ self.assertEqual((3, 2, 1),
+ bzrlib.api.get_current_api_version(an_object))
+
+ def test_get_current_api_version_fallsback_to_version_info(self):
+ an_object = TrivialObject()
+ an_object.version_info = (1, 2, 3, "final", 0)
+ self.assertEqual((1, 2, 3),
+ bzrlib.api.get_current_api_version(an_object))
+
+ def test_get_current_api_version_fallsback_to_bzrlib_version_info(self):
+ an_object = TrivialObject()
+ self.assertEqual(bzrlib.version_info[0:3],
+ bzrlib.api.get_current_api_version(an_object))
=== modified file 'doc/developers/api-versioning.txt'
--- a/doc/developers/api-versioning.txt 2007-06-26 06:57:20 +0000
+++ b/doc/developers/api-versioning.txt 2007-06-26 08:27:24 +0000
@@ -47,12 +47,18 @@
express, and easier for a human to look at and understand, and finally
easier to manage. The oldest version with which the API for a python
object is compatible is obtained by looking up the ``api_minimum_version``
-attribute on the python object handed to ``require_api``. The current
-version of the API is obtained by looking for an ``api_current_version``
-attribute, and if that is not found, an ``version_info`` attribute (of
-which the first 3 elements are used). If no current version can be found,
-the bzrlib ``version_info`` attribute is used to generate a current API
-version. API versions are compared lexically to answer the question 'is
+attribute on the python object handed to ``require_api``, and failing that
+the bzrlib ``api_minimum_version`` is returned. The current version of the
+API is obtained by looking for an ``api_current_version`` attribute, and
+if that is not found, an ``version_info`` attribute (of which the first 3
+elements are used). If no current version can be found, the bzrlib
+``version_info`` attribute is used to generate a current API version.
+This lookup sequence allows users with simple setups (and no python style
+``version_info`` tuple) to still export an API version, and for new API's
+to be managed more granularly later on with a smooth transition -
+everything starts off in lockstep with bzrlib's master version.
+
+API versions are compared lexically to answer the question 'is
the requested version X <= the current version, and >= the minimum
version'.
More information about the bazaar-commits
mailing list