This branch adds an initializeRemoteBugDB() method to the BugzillaAPI
ExternalBugTracker, in accordance with IExternalBugTracker. I've
refactored a couple of methods out of BugzillaLPPlugin, which descends
from BugzillaAPI, and into the BugzillaAPI class because they are useful
utilities.

I've also refactored the associated tests into the bugzilla-api doctest.

Note that this branch is based on a branch that hasn't yet landed (but
which is r=cprov). Please use the diff below rather than the one
generated by the merge proposal.

Launchpad lint
--------------

Checking for conflicts. and issues in doctests and templates.
Running jslint, xmllint, pyflakes, and pylint.
Using normal rules.

Linting changed files:
  lib/lp/bugs/doc/externalbugtracker-bugzilla-api.txt
  lib/lp/bugs/doc/externalbugtracker-bugzilla-lp-plugin.txt
  lib/lp/bugs/externalbugtracker/bugzilla.py
  lib/lp/bugs/tests/bugzilla-xmlrpc-transport.txt
  lib/lp/bugs/tests/externalbugtracker.py


Diff of changes
---------------

=== modified file 'lib/lp/bugs/doc/externalbugtracker-bugzilla-api.txt'
--- lib/lp/bugs/doc/externalbugtracker-bugzilla-api.txt	2009-08-20 15:43:37 +0000
+++ lib/lp/bugs/doc/externalbugtracker-bugzilla-api.txt	2009-08-21 09:51:57 +0000
@@ -111,3 +111,111 @@
     >>> bugzilla.getCurrentDBTime()
     CALLED Bugzilla.time()
     datetime.datetime(2009, 8, 19, 22, 2, 2, tzinfo=<UTC>)
+
+
+Initializing the bug database
+-----------------------------
+
+BugzillaAPI implements IExternalBugTracker.initializeRemoteBugDB(),
+which takes a list of bug IDs to fetch from the remote server and stores
+those bugs locally for future use.
+
+    >>> bugzilla.initializeRemoteBugDB([1, 2])
+    CALLED Bug.get({'ids': [1, 2], 'permissive': True})
+
+The bug data is stored as a list of dicts:
+
+    >>> def print_bugs(bugs):
+    ...     for bug in sorted(bugs):
+    ...         print "Bug %s:" % bug
+    ...         for key in sorted(bugzilla._bugs[bug]):
+    ...             print "    %s: %s" % (key, bugzilla._bugs[bug][key])
+    ...         print "\n"
+
+    >>> print_bugs(bugzilla._bugs)
+    Bug 1:
+        alias: 
+        assigned_to: <email address hidden>
+        component: GPPSystems
+        creation_time: 20080610T16:19:53
+        id: 1
+        internals:...
+        is_open: True
+        last_change_time: 20080610T16:19:53
+        priority: P1
+        product: Marvin
+        resolution: FIXED
+        severity: normal
+        status: RESOLVED
+        summary: That bloody robot still exists.
+    <BLANKLINE>
+    Bug 2:
+        alias: bug-two
+        assigned_to: <email address hidden>
+        component: Crew
+        creation_time: 20080611T09:23:12
+        id: 2
+        internals:...
+        is_open: True
+        last_change_time: 20080611T09:24:29
+        priority: P1
+        product: HeartOfGold
+        resolution: 
+        severity: high
+        status: NEW
+        summary: Collect unknown persons in docking bay 2.
+    <BLANKLINE>
+    <BLANKLINE>
+
+
+Storing bugs
+------------
+
+initializeRemoteBugDB() uses the _storeBugs() method to store bug data.
+_storeBugs() will only store a bug once, even if it is requested both by
+alias and ID. We'll reset the test BugzillaAPI's _bugs and _bug_aliases
+dicts to demonstrate this.
+
+    >>> bugzilla._bugs = {}
+    >>> bugzilla._bug_aliases = {}
+    >>> bugzilla.initializeRemoteBugDB([2, 'bug-two'])
+    CALLED Bug.get({'ids': [2, 'bug-two'], 'permissive': True})
+
+    >>> for bug in sorted(bugzilla._bugs):
+    ...     print "Bug %r:" % bug
+    ...     for key in sorted(bugzilla._bugs[bug]):
+    ...         print "    %s: %s" % (key, bugzilla._bugs[bug][key])
+    ...     print "\n"
+    Bug 2:
+        alias: bug-two
+        assigned_to: <email address hidden>
+        component: Crew
+        creation_time: 20080611T09:23:12
+        id: 2
+        internals:...
+        is_open: True
+        last_change_time: 20080611T09:24:29
+        priority: P1
+        product: HeartOfGold
+        resolution: 
+        severity: high
+        status: NEW
+        summary: Collect unknown persons in docking bay 2.
+    <BLANKLINE>
+    <BLANKLINE>
+
+Aliases are stored in a separate dict, which contains a mapping between
+the alias and the bug's actual ID.
+
+    >>> for alias, bug_id in bugzilla._bug_aliases.items():
+    ...     print "%s: %s" % (alias, bug_id)
+    bug-two: 2
+
+The method _getActualBugId() returns the correct bug ID for a passed bug
+ID or alias.
+
+    >>> bugzilla._getActualBugId('bug-two')
+    2
+
+    >>> bugzilla._getActualBugId(2)
+    2

=== modified file 'lib/lp/bugs/doc/externalbugtracker-bugzilla-lp-plugin.txt'
--- lib/lp/bugs/doc/externalbugtracker-bugzilla-lp-plugin.txt	2009-08-19 09:22:08 +0000
+++ lib/lp/bugs/doc/externalbugtracker-bugzilla-lp-plugin.txt	2009-08-21 09:51:57 +0000
@@ -1,4 +1,5 @@
-= Bugzilla bugtrackers with the Launchpad plugin =
+Bugzilla bugtrackers with the Launchpad plugin
+==============================================
 
 These tests cover the BugzillaLPPlugin ExternalBugTracker, which handles
 Bugzilla instances that have the Launchpad plugin installed.
@@ -25,7 +26,8 @@
     True
 
 
-== Authentication ==
+Authentication
+--------------
 
 XML-RPC methods that modify data on the remote server require
 authentication. To authenticate, we create a LoginToken of type
@@ -154,7 +156,8 @@
     Protocol error: 500 "Internal server error"
 
 
-== Getting the current time ==
+Getting the current time
+------------------------
 
 The BugzillaLPPlugin ExternalBugTracker, like all other
 ExternalBugTrackers, has a getCurrentDBTime() method, which returns the
@@ -173,7 +176,8 @@
     datetime.datetime(2008, 5, 16, 15, 53, 20, tzinfo=<UTC>)
 
 
-== Initializing the remote bug database ==
+Initializing the remote bug database
+------------------------------------
 
 The BugzillaLPPlugin implements the standard initializeRemoteBugDB()
 method, taking a list of the bug ids that need to be updated. It uses
@@ -228,56 +232,13 @@
     <BLANKLINE>
     <BLANKLINE>
 
-initializeRemoteBugDB() will only store a bug once, even if it is
-requested both by alias and ID. We'll reset the test BugzillaLPPlugin's
-_bugs and _bug_aliases dicts to demonstrate this.
-
-    >>> bugzilla._bugs = {}
-    >>> bugzilla._bug_aliases = {}
-    >>> bugzilla.initializeRemoteBugDB([2, 'bug-two'])
-    CALLED Launchpad.get_bugs({'ids': [2, 'bug-two'], 'permissive': True})
-
-    >>> for bug in sorted(bugzilla._bugs):
-    ...     print "Bug %r:" % bug
-    ...     for key in sorted(bugzilla._bugs[bug]):
-    ...         print "    %s: %s" % (key, bugzilla._bugs[bug][key])
-    ...     print "\n"
-    Bug 2:
-        alias: bug-two
-        assigned_to: <email address hidden>
-        component: Crew
-        creation_time: 20080611T09:23:12
-        id: 2
-        internals:...
-        is_open: True
-        last_change_time: 20080611T09:24:29
-        priority: P1
-        product: HeartOfGold
-        resolution: 
-        severity: high
-        status: NEW
-        summary: Collect unknown persons in docking bay 2.
-    <BLANKLINE>
-    <BLANKLINE>
-
-Aliases are stored in a separate dict, which contains a mapping between
-the alias and the bug's actual ID.
-
-    >>> for alias, bug_id in bugzilla._bug_aliases.items():
-    ...     print "%s: %s" % (alias, bug_id)
-    bug-two: 2
-
-The method _getActualBugId() returns the correct bug ID for a passed bug
-ID or alias.
-
-    >>> bugzilla._getActualBugId('bug-two')
-    2
-
-    >>> bugzilla._getActualBugId(2)
-    2
-
-
-== Getting a list of changed bugs ==
+BugzillaLPPlugin.initializeRemoteBugDB() uses its _storeBugs() method to
+store bugs. See externalbugtracker-bugzilla-api.txt for details of
+_storeBugs().
+
+
+Getting a list of changed bugs
+------------------------------
 
 IExternalBugTracker defines a method, getModifiedRemoteBugs(), which
 accepts a list of bug IDs and a datetime as a parameter and returns the
@@ -337,7 +298,8 @@
     CALLED Launchpad.get_bugs({'ids': [3], 'permissive': True})
 
 
-== Getting remote statuses ==
+Getting remote statuses
+-----------------------
 
 BugzillaLPPlugin.getRemoteStatus() will return the remote status of a
 given bug as a string. If the bug has a resolution, that will be
@@ -369,7 +331,8 @@
     >>> del bugzilla._bugs[999]
 
 
-== Getting the remote product ==
+Getting the remote product
+--------------------------
 
 getRemoteProduct() returns the product a remote bug is associated with
 in Bugzilla. 
@@ -393,7 +356,8 @@
     BugNotFound: 12345
 
 
-== Retrieving remote comments ==
+Retrieving remote comments
+--------------------------
 
 BugzillaLPPlugin implments the ISupportsCommentImport interface, which
 means that we can use it to import comments from the remote Bugzilla
@@ -435,7 +399,8 @@
     >>> LaunchpadZopelessLayer.switchDbUser(config.checkwatches.dbuser)
 
 
-=== getCommentIds() ===
+getCommentIds()
+---------------
 
 ISupportsCommentImport.getCommentIds() is the method used to get all the
 comment IDs for a given bug on a remote bugtracker.
@@ -456,7 +421,8 @@
     BugNotFound: 42
 
 
-=== fetchComments() ===
+fetchComments()
+---------------
 
 ISupportsCommentImport.fetchComments() is the method used to fetch a
 given set of comments from the remote bugtracker. It takes a bug watch
@@ -488,7 +454,8 @@
         time: 20080616T13:22:29
 
 
-=== getPosterForComment() ===
+getPosterForComment()
+---------------------
 
 ISupportsCommentImport.getPosterForComment() returns a tuple of
 (displayname, email) for the author of a remote comment.
@@ -507,7 +474,8 @@
     None trillian
 
 
-=== getMessageForComment() ===
+getMessageForComment()
+----------------------
 
 ISupportsCommentImport.getMessageForComment() returns a Launchpad
 IMessage instance for a given comment. It takes a bug watch, a comment
@@ -533,7 +501,8 @@
     2008-06-16 13:08:08+00:00
 
 
-== Pushing comments to remote systems ==
+Pushing comments to remote systems
+----------------------------------
 
 BugzillaLPPlugin implements the ISupportsCommentPushing interface, which
 defines the necessary methods for pushing comments to remote servers.
@@ -583,7 +552,8 @@
     <BLANKLINE>
 
 
-== Linking remote bugs to Launchpad bugs ==
+Linking remote bugs to Launchpad bugs
+-------------------------------------
 
 BugzillaLPPlugin implements the ISupportsBackLinking interface, which
 provides methods to set and retrieve the Launchpad bug that links to a
@@ -644,7 +614,8 @@
     10
 
 
-== Working with a specified set of Bugzilla products ==
+Working with a specified set of Bugzilla products
+-------------------------------------------------
 
 BugzillaLPPlugin can be instructed to only get the data for a set of
 bug IDs if those bugs belong to one of a given set of products.
@@ -691,7 +662,8 @@
     0
 
 
-== Getting the products for a set of remote bugs ==
+Getting the products for a set of remote bugs
+---------------------------------------------
 
 BugzillaLPPlugin provides a helper method, getProductsForRemoteBugs(),
 which takes a list of bug IDs or aliases and returns the products to

=== modified file 'lib/lp/bugs/externalbugtracker/bugzilla.py'
--- lib/lp/bugs/externalbugtracker/bugzilla.py	2009-08-20 15:43:37 +0000
+++ lib/lp/bugs/externalbugtracker/bugzilla.py	2009-08-21 09:51:57 +0000
@@ -430,6 +430,18 @@
                 self.baseurl,
                 "Fault %s: %s" % (fault.faultCode, fault.faultString))
 
+    def _storeBugs(self, remote_bugs):
+        """Store remote bugs in the local `bugs` dict."""
+        for remote_bug in remote_bugs:
+            self._bugs[remote_bug['id']] = remote_bug
+
+            # The bug_aliases dict is a mapping between aliases and bug
+            # IDs. We use the aliases dict to look up the correct ID for
+            # a bug. This allows us to reference a bug by either ID or
+            # alias.
+            if remote_bug['alias'] != '':
+                self._bug_aliases[remote_bug['alias']] = remote_bug['id']
+
     def getCurrentDBTime(self):
         """See `IExternalBugTracker`."""
         time_dict = self.xmlrpc_proxy.Bugzilla.time()
@@ -458,6 +470,58 @@
 
         return server_utc_datetime.replace(tzinfo=pytz.timezone('UTC'))
 
+    def _getActualBugId(self, bug_id):
+        """Return the actual bug id for an alias or id."""
+        # See if bug_id is actually an alias.
+        actual_bug_id = self._bug_aliases.get(bug_id)
+
+        # bug_id isn't an alias, so try turning it into an int and
+        # looking the bug up by ID.
+        if actual_bug_id is not None:
+            return actual_bug_id
+        else:
+            try:
+                actual_bug_id = int(bug_id)
+            except ValueError:
+                # If bug_id can't be int()'d then it's likely an alias
+                # that doesn't exist, so raise BugNotFound.
+                raise BugNotFound(bug_id)
+
+            # Check that the bug does actually exist. That way we're
+            # treating integer bug IDs and aliases in the same way.
+            if actual_bug_id not in self._bugs:
+                raise BugNotFound(bug_id)
+
+            return actual_bug_id
+
+    def _getBugIdsToRetrieve(self, bug_ids):
+        """For a set of bug IDs, return those for which we have no data."""
+        bug_ids_to_retrieve = []
+        for bug_id in bug_ids:
+            try:
+                actual_bug_id = self._getActualBugId(bug_id)
+            except BugNotFound:
+                bug_ids_to_retrieve.append(bug_id)
+
+        return bug_ids_to_retrieve
+
+    def initializeRemoteBugDB(self, bug_ids):
+        """See `IExternalBugTracker`."""
+        # First, discard all those bug IDs about which we already have
+        # data.
+        bug_ids_to_retrieve = self._getBugIdsToRetrieve(bug_ids)
+
+        # Pull the bug data from the remote server. permissive=True here
+        # prevents Bugzilla from erroring if we ask for a bug it doesn't
+        # have.
+        response_dict = self.xmlrpc_proxy.Bug.get({
+            'ids': bug_ids_to_retrieve,
+            'permissive': True,
+            })
+        remote_bugs = response_dict['bugs']
+
+        self._storeBugs(remote_bugs)
+
 
 class BugzillaLPPlugin(BugzillaAPI):
     """An `ExternalBugTracker` to handle Bugzillas using the LP Plugin."""
@@ -500,18 +564,6 @@
             raise BugTrackerAuthenticationError(
                 self.baseurl, message)
 
-    def _storeBugs(self, remote_bugs):
-        """Store remote bugs in the local `bugs` dict."""
-        for remote_bug in remote_bugs:
-            self._bugs[remote_bug['id']] = remote_bug
-
-            # The bug_aliases dict is a mapping between aliases and bug
-            # IDs. We use the aliases dict to look up the correct ID for
-            # a bug. This allows us to reference a bug by either ID or
-            # alias.
-            if remote_bug['alias'] != '':
-                self._bug_aliases[remote_bug['alias']] = remote_bug['id']
-
     def getModifiedRemoteBugs(self, bug_ids, last_checked):
         """See `IExternalBugTracker`."""
         # We marshal last_checked into an xmlrpclib.DateTime since
@@ -566,12 +618,7 @@
         """See `IExternalBugTracker`."""
         # First, discard all those bug IDs about which we already have
         # data.
-        bug_ids_to_retrieve = []
-        for bug_id in bug_ids:
-            try:
-                actual_bug_id = self._getActualBugId(bug_id)
-            except BugNotFound:
-                bug_ids_to_retrieve.append(bug_id)
+        bug_ids_to_retrieve = self._getBugIdsToRetrieve(bug_ids)
 
         # Next, grab the bugs we still need from the remote server.
         # We pass permissive=True to ensure that Bugzilla won't error if
@@ -601,30 +648,6 @@
         server_utc_time = datetime(*server_timetuple[:6])
         return server_utc_time.replace(tzinfo=pytz.timezone('UTC'))
 
-    def _getActualBugId(self, bug_id):
-        """Return the actual bug id for an alias or id."""
-        # See if bug_id is actually an alias.
-        actual_bug_id = self._bug_aliases.get(bug_id)
-
-        # bug_id isn't an alias, so try turning it into an int and
-        # looking the bug up by ID.
-        if actual_bug_id is not None:
-            return actual_bug_id
-        else:
-            try:
-                actual_bug_id = int(bug_id)
-            except ValueError:
-                # If bug_id can't be int()'d then it's likely an alias
-                # that doesn't exist, so raise BugNotFound.
-                raise BugNotFound(bug_id)
-
-            # Check that the bug does actually exist. That way we're
-            # treating integer bug IDs and aliases in the same way.
-            if actual_bug_id not in self._bugs:
-                raise BugNotFound(bug_id)
-
-            return actual_bug_id
-
     def getRemoteStatus(self, bug_id):
         """See `IExternalBugTracker`."""
         actual_bug_id = self._getActualBugId(bug_id)

=== modified file 'lib/lp/bugs/tests/bugzilla-xmlrpc-transport.txt'
--- lib/lp/bugs/tests/bugzilla-xmlrpc-transport.txt	2009-08-19 23:17:09 +0000
+++ lib/lp/bugs/tests/bugzilla-xmlrpc-transport.txt	2009-08-21 09:51:57 +0000
@@ -609,3 +609,35 @@
     tz_short_name: CET
     web_time: 20080501T01:01:01
     web_time_utc: 20080501T00:01:01
+
+
+Getting bugs from the server
+----------------------------
+
+The Bugzilla API method Bug.get() allows us to get one or more bugs from
+the remote server. It takes a list of bug IDs to return and returns a
+list of dicts containing those bugs' data.
+
+    >>> return_value = server.Bug.get(
+    ...     {'ids': [1], 'permissive': True})
+    >>> [bug_dict] = return_value['bugs']
+    >>> for key in sorted(bug_dict):
+    ...     print "%s: %s" % (key, bug_dict[key])
+    alias: 
+    assigned_to: <email address hidden>
+    component: GPPSystems
+    creation_time: 20080610T16:19:53
+    id: 1
+    internals:...
+    is_open: True
+    last_change_time: 20080610T16:19:53
+    priority: P1
+    product: Marvin
+    resolution: FIXED
+    severity: normal
+    status: RESOLVED
+    summary: That bloody robot still exists.
+
+Note that further tests for this functionality can be found in the
+"Launchpad.get_bugs()" section, above. This is because these two methods
+are synonymous.

=== modified file 'lib/lp/bugs/tests/externalbugtracker.py'
--- lib/lp/bugs/tests/externalbugtracker.py	2009-08-20 15:43:37 +0000
+++ lib/lp/bugs/tests/externalbugtracker.py	2009-08-21 09:51:57 +0000
@@ -759,6 +759,7 @@
 
     # Map namespaces onto method names.
     methods = {
+        'Bug': ['get'],
         'Bugzilla': [
             'time',
             'version',
@@ -817,6 +818,11 @@
             'web_time_utc': time_dict['utc_time'],
             }
 
+    def get(self, arguments):
+        """Return a list of bug dicts for a given set of bug ids."""
+        # This method is actually just a synonym for get_bugs().
+        return self.get_bugs(arguments)
+
 
 class TestMantis(Mantis):
     """Mantis ExternalSystem for use in tests.