require_api_version errors are confusing

[Jelmer Vernooij]

  affects bzr

require_api_version() currently prints confusing error messages when the
API is not up to date, e.g.:

bzr: ERROR: The API for "<module 'bzrlib' from
'/usr/lib/python2.5/site-packages/bzrlib/__init__.pyc'>" is not
compatible with "(1, 10, 0)". It supports versions "(1, 11, 0)" to "(1,
12, 0)".

In this particular case, it's bzr-svn that's calling the function but
that's very hard to tell.
--
Jelmer Vernooij <email address hidden> - http://samba.org/~jelmer/
Jabber: <email address hidden>

[Colin D Bennett (colinb)]

For instance, with bzr 1.12dev (bzr.dev revno:3951), a plugin that requires API version 1.10 produces this backtrace with '-Derror':

cdb@gamma ~/code/bzr/work/bzrlib $ bzr st -Derror
bzr: ERROR: bzrlib.errors.IncompatibleAPI: The API for "<module 'bzrlib' from '/home/cdb/bin/bzr.dev/bzrlib/__init__.pyc'>" is not compatible with "(1, 10, 0)". It supports versions "(1, 11, 0)" to "(1, 12, 0)".

Traceback (most recent call last):
  File "/home/cdb/bin/bzr.dev/bzrlib/commands.py", line 893, in run_bzr_catch_errors
    return run_bzr(argv)
  File "/home/cdb/bin/bzr.dev/bzrlib/commands.py", line 839, in run_bzr
    ret = run(*run_argv)
  File "/home/cdb/.bazaar/plugins/loom/commands.py", line 172, in run_argv_aliases
    self._original_command().run_argv_aliases(argv, alias_argv)
  File "/home/cdb/bin/bzr.dev/bzrlib/commands.py", line 539, in run_argv_aliases
    return self.run(**all_cmd_args)
  File "/home/cdb/bin/bzr.dev/bzrlib/commands.py", line 853, in ignore_pipe
    result = func(*args, **kwargs)
  File "/home/cdb/bin/bzr.dev/bzrlib/builtins.py", line 215, in run
    tree, relfile_list = tree_files(file_list)
  File "/home/cdb/bin/bzr.dev/bzrlib/builtins.py", line 64, in tree_files
    return internal_tree_files(file_list, default_branch, canonicalize)
  File "/home/cdb/bin/bzr.dev/bzrlib/builtins.py", line 105, in internal_tree_files
    return WorkingTree.open_containing(default_branch)[0], file_list
  File "/home/cdb/bin/bzr.dev/bzrlib/workingtree.py", line 331, in open_containing
    control, relpath = bzrdir.BzrDir.open_containing(path)
  File "/home/cdb/bin/bzr.dev/bzrlib/bzrdir.py", line 844, in open_containing
    return BzrDir.open_containing_from_transport(transport)
  File "/home/cdb/bin/bzr.dev/bzrlib/bzrdir.py", line 865, in open_containing_from_transport
    result = BzrDir.open_from_transport(a_transport)
  File "/home/cdb/bin/bzr.dev/bzrlib/bzrdir.py", line 819, in open_from_transport
    redirected)
  File "/home/cdb/bin/bzr.dev/bzrlib/lazy_import.py", line 125, in __call__
    return obj(*args, **kwargs)
  File "/home/cdb/bin/bzr.dev/bzrlib/transport/__init__.py", line 1680, in do_catching_redirections
    return action(transport)
  File "/home/cdb/bin/bzr.dev/bzrlib/bzrdir.py", line 806, in find_format
    transport, _server_formats=_server_formats)
  File "/home/cdb/bin/bzr.dev/bzrlib/bzrdir.py", line 1645, in find_format
    return format.probe_transport(transport)
  File "/home/cdb/.bazaar/plugins/svn/format.py", line 71, in probe_transport
    format = klass()
  File "/home/cdb/.bazaar/plugins/svn/format.py", line 61, in __init__
    lazy_check_versions()
  File "/home/cdb/.bazaar/plugins/svn/__init__.py", line 137, in lazy_check_versions
    bzrlib.api.require_any_api(bzrlib, COMPATIBLE_BZR_VERSIONS)
  File "/home/cdb/bin/bzr.dev/bzrlib/api.py", line 104, in require_any_api
    require_api(object_with_api, wanted_api_list[-1])
  File "/home/cdb/bin/bzr.dev/bzrlib/api.py", line 82, in require_api
    raise IncompatibleAPI(object_with_api, wanted_api, minimum, current)
IncompatibleAPI: The API for "<module 'bzrlib' from '/home/cdb/bin/bzr.dev/bzrlib/__init__.pyc'>" is not compatible with "(1, 10, 0)". It supports versi...

[Colin D Bennett (colinb)]

It seems like in most cases, when a user encounters this error, it will be cause a plugin requires an older or newer 'bzrlib' API than the currently installed version of bzr provides. Therefore, the appropriate error message (from a user's standpoint) would be something like:

bzr: ERROR: bzrlib.errors.IncompatibleAPI: The plugin 'bzr-svn' is not compatible with bzrlib 1.10. It supports versions 1.11 to 1.12.

Is there a way that ``require_any_api()`` can determine the name of the calling plugin from the Python stack? If not, (and perhaps a more obvious way anyhow) we should provide an optional argument to ``require_any_api()`` called 'plugin_name', which plugins can use to pass in their name for a potential error message.

Any thoughts?

[Brian de Alwis (slyguy)]

I think the callers of bzrlib.api.require_any_api() should be catching IncompatibleAPI and reporting a nicer message.

[Jelmer Vernooij (jelmer)]

On Thu, 2009-01-22 at 17:19 +0000, Brian de Alwis wrote:
> I think the callers of bzrlib.api.require_any_api() should be catching
> IncompatibleAPI and reporting a nicer message.
I think that defeats the purpose of require_any_api(). The whole point
of it is to make it easier for plugins to check compatibility with
bzrlib.

Cheers,

Jelmer
--
Jelmer Vernooij <email address hidden> - http://samba.org/~jelmer/
Jabber: <email address hidden>