~launchpad-pqm/launchpad/devel

= The BugTrackerPerson interface =

The IBugTrackerPerson interfaces allows Launchpad to link Persons to

bugtrackers. BugTrackerPersons are created using the

linkPersonToSelf() method of IBugTracker.

    >>> from zope.component import getUtility

    >>> from lp.bugs.interfaces.bugtracker import (

    ...     BugTrackerType)

    >>> from lp.registry.interfaces.person import (

    ...     IPersonSet)

    >>> from lp.bugs.tests.externalbugtracker import (

    ...     new_bugtracker)

    >>> sample_person = getUtility(IPersonSet).getByName('name12')

    >>> bugtracker = new_bugtracker(BugTrackerType.BUGZILLA)

We'll rename the bugtracker to make the tests more readable.

    >>> from canonical.database.sqlbase import commit

    >>> from lp.testing.layers import LaunchpadZopelessLayer

    >>> LaunchpadZopelessLayer.switchDbUser('launchpad')

    >>> bugtracker.name = 'bugzilla-checkwatches'

    >>> commit()

    >>> from lp.services.config import config

    >>> LaunchpadZopelessLayer.switchDbUser(config.checkwatches.dbuser)

    >>> bugtracker_person = bugtracker.linkPersonToSelf(

    ...         'some-name-i-made-up', sample_person)

    >>> print bugtracker_person.name

    some-name-i-made-up

    >>> print bugtracker_person.person.name

    name12

    >>> print bugtracker_person.bugtracker.name

    bugzilla-checkwatches

A name can only be registered with a bugtracker once. Trying to link a

new person to a bugtracker using an existing name will cause an error.

    >>> foo_bar = getUtility(IPersonSet).getByName('name16')

    >>> bugtracker_person = bugtracker.linkPersonToSelf(

    ...         'some-name-i-made-up', foo_bar)

    Traceback (most recent call last):

      ...

    BugTrackerPersonAlreadyExists: Name 'some-name-i-made-up' is already in

    use for bugtracker 'bugzilla-checkwatches'.

The BugTrackerPerson record for a given name on a given bugtracker can

be retrieved by calling BugTracker.getLinkedPersonByName().

    >>> bugtracker_person = bugtracker.getLinkedPersonByName(

    ...     'some-name-i-made-up')

    >>> print bugtracker_person.name

    some-name-i-made-up

    >>> print bugtracker_person.person.name

    name12

== ensurePersonForSelf() ==

IBugTracker has a method, ensurePersonForSelf(), which is

responsible for returning the correct BugTrackerPerson for a given

remote username on on a given bugtracker.

Passing a new remote user's details to ensurePersonForSelf() will

return a new Person record.

    >>> from lp.registry.interfaces.person import (

    ...     PersonCreationRationale)

    >>> print getUtility(IPersonSet).getByEmail('new.person@example.com')

    None

    >>> new_person = bugtracker.ensurePersonForSelf(

    ...     display_name='New Person', email='new.person@example.com',

    ...     rationale=PersonCreationRationale.BUGIMPORT,

    ...     creation_comment='whilst testing ensurePersonForSelf().')

    >>> print new_person.displayname

    New Person

There won't be a BugTrackerPerson record linking 'New Person' to the

bugtracker since we have an email address for 'New Person'. That means

that we can always retrieve them reliably when we encounter them in a

remote bugtracker.

    >>> bugtracker_person = bugtracker.getLinkedPersonByName('New Person')

    >>> print bugtracker_person

    None

Calling ensurePersonForSelf() with the same details will return the

same person.

    >>> other_person = bugtracker.ensurePersonForSelf(

    ...     display_name='New Person',

    ...     email='new.person@example.com',

    ...     rationale=PersonCreationRationale.BUGIMPORT,

    ...     creation_comment='whilst testing ensurePersonForSelf().')

    >>> print other_person.name

    new-person

    >>> print new_person.name

    new-person

ensurePersonForSelf() can also handle remote users whose email

addresses aren't provided.

    >>> noemail_person = bugtracker.ensurePersonForSelf(

    ...     display_name='no-email-person',

    ...     email=None, rationale=PersonCreationRationale.BUGIMPORT,

    ...     creation_comment='whilst testing ensurePersonForSelf().')

    >>> print noemail_person.name

    no-email-person-bugzilla-checkwatches

A BugTrackerPerson record will have been created to map

'no-email-person' on our example bugtracker to

'no-email-person-bugzilla-checkwatches-1' in Launchpad.

    >>> bugtracker_person = bugtracker.getLinkedPersonByName(

    ...     'no-email-person')

    >>> bugtracker_person.person == noemail_person

    True

ensurePersonForSelf() handles situations in which bugtrackers have

been renamed, too, and avoids name collisions when doing so.

We'll create a person, 'noemail,' on our example bugtracker.

    >>> new_person = bugtracker.ensurePersonForSelf(

    ...     display_name='noemail',

    ...     email=None, rationale=PersonCreationRationale.BUGIMPORT,

    ...     creation_comment='whilst testing.')

    >>> print new_person.name

    noemail-bugzilla-checkwatches

    >>> bugtracker_person = bugtracker.getLinkedPersonByName('noemail')

    >>> print bugtracker_person.bugtracker.name

    bugzilla-checkwatches

    >>> print bugtracker_person.person.name

    noemail-bugzilla-checkwatches

    >>> commit()

If we rename the BugTracker and then create another with the same name,

calling ensurePersonForSelf() for 'noemail' on that BugTracker

should produce a new Person rather than re-using the existing one.

    >>> other_bug_tracker = new_bugtracker(BugTrackerType.BUGZILLA)

    >>> LaunchpadZopelessLayer.switchDbUser('launchpad')

    >>> bugtracker.name = 'bugzilla-checkwatches-renamed'

    >>> commit()

    >>> other_bug_tracker.name = 'bugzilla-checkwatches'

    >>> commit()

    >>> LaunchpadZopelessLayer.switchDbUser(config.checkwatches.dbuser)

A new Person has been created for 'noemail' on other_bug_tracker, even

though that bug tracker's name is the same as one from which we've

imported previously.

    >>> from lp.bugs.interfaces.bugtracker import IBugTrackerSet

    >>> bugtracker = getUtility(IBugTrackerSet).get(bugtracker.id)

    >>> other_bugtracker = getUtility(IBugTrackerSet).get(

    ...     other_bug_tracker.id)

    >>> original_bugtracker_person = bugtracker.getLinkedPersonByName(

    ...     'noemail')

    >>> new_person = other_bugtracker.ensurePersonForSelf(

    ...     'noemail', None, PersonCreationRationale.BUGIMPORT,

    ...     'while testing, again')

    >>> print original_bugtracker_person.person.name

    noemail-bugzilla-checkwatches

    >>> print new_person.name

    noemail-bugzilla-checkwatches-1