~launchpad-pqm/launchpad/devel

Team Membership/Participation

=============================

When a person joins a team, we store the relationship in the TeamMembership

table. In this table we store the membership status, the join date and the

expiry date. TeamMembership stores only direct members. However, when a

member of a team is in fact another team (in the case of Team Y is a member

of Team X), the membership is transitive (members of Team Y are also a

member of team X). For this reason the TeamParticipation table exists: it

represents all the people who are /effective members/ of the team.

First of all, create some teams:

    >>> import pytz

    >>> from datetime import datetime, timedelta

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

    ...     TeamMembershipRenewalPolicy,

    ...     TeamSubscriptionPolicy,

    ...     )

    >>> from lp.registry.interfaces.teammembership import TeamMembershipStatus

XXX: This doctest needs a lot of cleanups!

-- Guilherme Salgado, 2006-12-15

    >>> from zope.component import getUtility

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

    >>> personset = getUtility(IPersonSet)

    >>> jblack = personset.getByName('jblack')

    >>> nopriv = personset.getByName('no-priv')

    >>> jdub = personset.getByName('jdub')

    >>> reviewer = nopriv

    >>> t1 = personset.newTeam(

    ...     jblack, 't1', 't1',

    ...     subscriptionpolicy=TeamSubscriptionPolicy.OPEN)

    >>> t2 = personset.newTeam(

    ...     nopriv, 't2', 't2',

    ...     subscriptionpolicy=TeamSubscriptionPolicy.OPEN)

    >>> t3 = personset.newTeam(

    ...     jdub, 't3', 't3',

    ...     subscriptionpolicy=TeamSubscriptionPolicy.MODERATED)

    >>> t4 = personset.newTeam(

    ...     nopriv, 't4', 't4',

    ...     subscriptionpolicy=TeamSubscriptionPolicy.OPEN)

    >>> t5 = personset.newTeam(

    ...     nopriv, 't5', 't5',

    ...     subscriptionpolicy=TeamSubscriptionPolicy.OPEN)

    >>> t6 = personset.newTeam(

    ...     jdub, 't6', 't6',

    ...     subscriptionpolicy=TeamSubscriptionPolicy.MODERATED)

    # Make sure the teams have predictable (and different) creation dates as

    # some of our tests depend on that.

    >>> from zope.security.proxy import removeSecurityProxy

    >>> oldest = t1.datecreated

    >>> removeSecurityProxy(t2).datecreated = oldest + timedelta(hours=1)

    >>> removeSecurityProxy(t3).datecreated = oldest + timedelta(hours=2)

    >>> removeSecurityProxy(t4).datecreated = oldest + timedelta(hours=3)

    >>> removeSecurityProxy(t5).datecreated = oldest + timedelta(hours=4)

    >>> from lp.services.database.sqlbase import flush_database_updates

    >>> flush_database_updates()

Adding new members

------------------

One way of adding new members to a team is by having the user himself join the

team he wants.

    >>> salgado = personset.getByName('salgado')

    >>> login_person(salgado)

    >>> salgado.join(t3)

    >>> salgado.join(t4)

Note that since t3 is a MODERATED team, Salgado is not really added as a

member of that team --somebody has to approve his membership first:

    >>> [m.displayname for m in t4.allmembers]

    [u'Guilherme Salgado', u'No Privileges Person']

    >>> [m.displayname for m in t3.allmembers]

    [u'Jeff Waugh']

    >>> login_person(t3.teamowner)

    >>> t3.setMembershipData(salgado, TeamMembershipStatus.APPROVED, reviewer)

    >>> flush_database_updates()

    >>> [m.displayname for m in t3.allmembers]

    [u'Guilherme Salgado', u'Jeff Waugh']

The join() method is not allowed for teams whose subscription policy is

RESTRICTED. And it'll be a no-op in case the user has already joined the

given team.

    >>> launchpad = personset.getByName('launchpad')

    >>> launchpad.subscriptionpolicy == TeamSubscriptionPolicy.RESTRICTED

    True

    >>> login_person(salgado)

    >>> salgado.join(launchpad)

    Traceback (most recent call last):

    ...

    JoinNotAllowed: This is a restricted team

    >>> salgado.join(t3)

    >>> salgado in t3.activemembers

    True

    >>> salgado.join(t4)

    >>> salgado in t4.activemembers

    True

Team admins can make any of their teams join other teams as well.

Just like for people, if the team is MODERATED, the membership will

be PENDING, whereas for OPEN teams the membership will be automatically

approved.  Note, though, that in the case of teams we need to pass a

requester to the join() method.

    >>> ubuntu_team = personset.getByName('ubuntu-team')

    >>> login_person(ubuntu_team.teamowner)

    >>> ubuntu_team.join(t3, ubuntu_team.teamowner)

    >>> t3.subscriptionpolicy

    <DBItem TeamSubscriptionPolicy.MODERATED...

    >>> ubuntu_team in t3.proposedmembers

    True

    >>> t2.subscriptionpolicy

    <DBItem TeamSubscriptionPolicy.OPEN...

    >>> ubuntu_team.join(t2, ubuntu_team.teamowner)

    >>> ubuntu_team in t2.activemembers

    True

    # Clean things up to not upset the other tests.

    >>> login_person(t2.teamowner)

    >>> t2.setMembershipData(

    ...     ubuntu_team, TeamMembershipStatus.DEACTIVATED, t2.teamowner)

    >>> ubuntu_team in t2.activemembers

    False

    >>> [m.displayname for m in t2.allmembers]

    [u'No Privileges Person']

    >>> login(ANONYMOUS)

Another API for adding members is ITeam.addMember(), which ensures the given

person has a membership entry for that team, regardless of whether the person

was already an active/inactive member or has never been a member before.

Only the team owner or a launchpad admin can call the addMember method.

Other users must use the join method if they are going to add themselves

to a team.

    >>> mark = personset.getByName('mark')

    >>> t3.addMember(salgado, reviewer=mark,

    ...     status=TeamMembershipStatus.ADMIN)

    Traceback (most recent call last):

    ...

    Unauthorized:...

    # Log in as the team owner.

    >>> login_person(t3.teamowner)

If the member was added (i.e. he wasn't already a member of the team),

addMember returns a tuple with True plus the new membership status.

    >>> t3.addMember(

    ...     salgado, reviewer=mark, status=TeamMembershipStatus.ADMIN)

    (True, <DBItem TeamMembershipStatus.ADMIN...)

    >>> from lp.registry.interfaces.teammembership import ITeamMembershipSet

    >>> membershipset = getUtility(ITeamMembershipSet)

    >>> flush_database_updates()

    >>> membership = membershipset.getByPersonAndTeam(salgado, t3)

    >>> membership.last_changed_by == mark

    True

    >>> membership.status == TeamMembershipStatus.ADMIN

    True

    >>> salgado in t3.activemembers

    True

addMember returns (True, PROPOSED) also when the member is added as a

proposed member.

    >>> marilize = personset.getByName('marilize')

    >>> t3.addMember(

    ...     marilize, reviewer=mark, status=TeamMembershipStatus.PROPOSED)

    (True, <DBItem TeamMembershipStatus.PROPOSED...)

    >>> flush_database_updates()

    >>> marilize in t3.activemembers

    False

If addMember is called with a person that is already a member, it

returns a tuple with False and the current status of the membership.

    >>> t3.addMember(

    ...     salgado, reviewer=mark, status=TeamMembershipStatus.ADMIN)

    (False, <DBItem TeamMembershipStatus.ADMIN...)

    >>> t3.addMember(

    ...     marilize, reviewer=mark, status=TeamMembershipStatus.PROPOSED)

    (False, <DBItem TeamMembershipStatus.PROPOSED...)

As expected, the membership object implements ITeamMembership.

    >>> from lp.services.webapp.testing import verifyObject

    >>> from lp.registry.interfaces.teammembership import ITeamMembership

    >>> verifyObject(ITeamMembership, membership)

    True

Note that, by default, the ITeam.addMember() API works slightly different

when the added member is a team. In that case the team will actually be

invited to be a member and one of the team's admins will have to accept the

invitation before the team is made a member.

    >>> login_person(t1.teamowner)

    # If the reviewer were also an admin of the team being added,

    # the status would go to APPROVED instead of INVITED.

    >>> t2.teamowner != t1.teamowner

    True

    >>> t1.addMember(t2, reviewer=t1.teamowner)

    (True, <DBItem TeamMembershipStatus.INVITED...)

    >>> membership = membershipset.getByPersonAndTeam(t2, t1)

    >>> membership.status == TeamMembershipStatus.INVITED

    True

    >>> [m.displayname for m in t1.allmembers]

    [u'James Blackwell']

Once one of the t2 admins approve the membership, t2 is shown as a member

of t1 and the owner of t2 is an indirect member.

    >>> login_person(t2.teamowner)

    >>> t2.acceptInvitationToBeMemberOf(t1, comment='something')

    >>> [m.displayname for m in t1.activemembers]

    [u'James Blackwell', u't2']

    >>> [m.displayname for m in t1.allmembers]

    [u'James Blackwell', u'No Privileges Person', u't2']

A team admin can also decline an invitation made to his team.

    >>> t2.addMember(t3, reviewer=mark)

    (True, <DBItem TeamMembershipStatus.INVITED...)

    >>> login_person(t3.teamowner)

    >>> t3.declineInvitationToBeMemberOf(t2, comment='something')

    >>> membership = membershipset.getByPersonAndTeam(t3, t2)

    >>> membership.status == TeamMembershipStatus.INVITATION_DECLINED

    True

In some cases it's necessary to bypass the invitation workflow and directly

add teams as members of other teams. We can do that by passing an extra

force_team_add=True to addMember(). We'll use that to add t3 as a member of

t2, thus making all t3 members be considered members of t2 as well.

    >>> login_person(t2.teamowner)

    # If the reviewer is also an admin of the team being added,

    # force_team_add is unnecessary, and we can't prove that that

    # argument works.

    >>> t3.teamowner != t2.teamowner

    True

    >>> t2.addMember(t3, reviewer=t2.teamowner, force_team_add=True)

    (True, <DBItem TeamMembershipStatus.APPROVED...)

    >>> [m.displayname for m in t2.allmembers]

    [u'Guilherme Salgado', u'Jeff Waugh', u'No Privileges Person', u't3']

And members of t1 as well, since t2 is a member of t1.

    >>> [m.displayname for m in t1.allmembers]

    [u'Guilherme Salgado', u'James Blackwell', u'Jeff Waugh',

    u'No Privileges Person', u't2', u't3']

Passing in force_team_add=True is not necessary if the reviewer is the

admin of the team being added.

    >>> login_person(t3.teamowner)

    >>> t6.addMember(t3, reviewer=t3.teamowner)

    (True, <DBItem TeamMembershipStatus.APPROVED...)

    >>> [m.displayname for m in t6.allmembers]

    [u'Guilherme Salgado', u'Jeff Waugh', u't3']

Can we add t2 as a member of t3? No, we prevent this kind of loop, and users

can't do this because our vocabularies won't allow members that would cause

loops.

    >>> foobar = personset.getByEmail('foo.bar@canonical.com')

    >>> login_person(foobar)

    >>> t3.addMember(t2, reviewer)

    Traceback (most recent call last):

    ...

    AssertionError: Team 't3' is a member of 't2'. As a consequence, 't2'

    can't be added as a member of 't3'

Adding t2 as a member of t5 will add all t2 members as t5 members too.

    >>> t5.addMember(t2, reviewer, force_team_add=True)

    (True, <DBItem TeamMembershipStatus.APPROVED...)

    >>> [m.displayname for m in t5.allmembers]

    [u'Guilherme Salgado', u'Jeff Waugh', u'No Privileges Person',

    u't2', u't3']

Adding t5 and t1 as members of t4 will add all t5 and t1 members as t4

members too.

    >>> t4.addMember(t5, reviewer, force_team_add=True)

    (True, <DBItem TeamMembershipStatus.APPROVED...)

    >>> t4.addMember(t1, reviewer, force_team_add=True)

    (True, <DBItem TeamMembershipStatus.APPROVED...)

    >>> [m.displayname for m in t4.allmembers]

    [u'Guilherme Salgado', u'James Blackwell', u'Jeff Waugh',

    u'No Privileges Person', u't1', u't2', u't3', u't5']

    >>> flush_database_updates()

After adding all this mess, this is what we have:

(This table doesn't include the team owner (Foo Bar), but since he's the

owner he's also a direct member of all teams)

=============================================================

||  Team      ||  Direct Members   ||  Indirect Members    ||

=============================================================

||   T1       ||  T2               ||  T3, Salgado         ||

||   T2       ||  T3               ||  Salgado             ||

||   T3       ||  Salgado          ||                      ||

||   T4       ||  T5, T1, Salgado  ||  T2, T3              ||

||   T5       ||  T2               ||  T3, Salgado         ||

We can use IPerson.findPathToTeam() to check some of the relationships drawn

above, either from a person to a given team ...

    >>> [team.name for team in salgado.findPathToTeam(t1)]

    [u't3', u't2', u't1']

    >>> [team.name for team in salgado.findPathToTeam(t5)]

    [u't3', u't2', u't5']

    >>> [team.name for team in salgado.findPathToTeam(t3)]

    [u't3']

... or from a team to another one:

    >>> [team.name for team in t3.findPathToTeam(t4)]

    [u't2', u't1', u't4']

t2 can't use its leave() method to leave t5 because it's a team and teams

take no actions. One of t5 administrators have to go and remove t2 from t5

if t2 shouldn't be a member of t5 anymore.

    >>> login_person(t5.teamowner)

    >>> t5.setMembershipData(t2, TeamMembershipStatus.DEACTIVATED, reviewer)

Removing t2 from t5 will have implications in all teams that have t5 as a

(direct or indirect) member.

t5 had only one member and two other indirect members. Now that t2 is not its

member anymore, it doesn't have any members apart from its owner.

    >>> [m.displayname for m in t5.allmembers]

    [u'No Privileges Person']

Removing t2 from t5 won't remove it from t4, because t2 is also a member of

t1, which is a member of t4.

    >>> [m.displayname for m in t4.allmembers]

    [u'Guilherme Salgado', u'James Blackwell', u'Jeff Waugh',

    u'No Privileges Person', u't1', u't2', u't3', u't5']

Nothing changes in t1, because t5 wasn't one of its members.

    >>> [m.displayname for m in t1.allmembers]

    [u'Guilherme Salgado', u'James Blackwell', u'Jeff Waugh',

    u'No Privileges Person', u't2', u't3']

If 'Guilherme Salgado' decides to leave t3, he'll also be removed from t1

and t2, but not from t4, because he's a direct member of t4.

    >>> login_person(salgado)

    >>> salgado.leave(t3)

    >>> salgado in t1.allmembers

    False

    >>> salgado in t2.allmembers

    False

    >>> salgado in t4.allmembers

    True

This is what we have now, after removing t2 from t5 and Salgado from t3.

(This table doesn't include the team owner (Foo Bar), but since he's the

owner he's also a direct member of all teams)

=============================================================

||  Team      ||  Members          ||  Indirect Members    ||

=============================================================

||   T1       ||  T2               ||  T3                  ||

||   T2       ||  T3               ||                      ||

||   T3       ||                   ||                      ||

||   T4       ||  T5, T1, Salgado  ||  T2, T3              ||

||   T5       ||                   ||                      ||

Now, if I add a new member to t3, will it be added to t2, t1 and t4 as well?

Let's see...

    >>> cprov = getUtility(IPersonSet).getByName('cprov')

    >>> t3.addMember(cprov, reviewer)

    (True, <DBItem TeamMembershipStatus.APPROVED...)

    >>> [m.displayname for m in t3.allmembers]

    [...u'Celso Providelo'...

    >>> [m.displayname for m in t2.allmembers]

    [...u'Celso Providelo'...

    >>> [m.displayname for m in t1.allmembers]

    [...u'Celso Providelo'...

    >>> [m.displayname for m in t4.allmembers]

    [...u'Celso Providelo'...

It's important to note that even if the owner leaves the team, which

removes his membership, he will still be the team's owner and retain his

rights over it. This ensures we'll never have teams which can't be

managed. This does not imply that the owner will be a member of the team.

    >>> login_person(t5.teamowner)

    >>> t5.teamowner.leave(t5)

    >>> flush_database_updates()

    >>> [m.displayname for m in t5.allmembers]

    []

    >>> t5.teamowner.inTeam(t5)

    False

The team owner can make themselves a member again even if the team is

restricted:

    >>> t5.teamowner.join(t5, requester=t5.teamowner)

    >>> flush_database_updates()

    >>> t5.teamowner in t5.allmembers

    True

    >>> t5.teamowner.inTeam(t5)

    True

And escalate their privileges back to administrator:

    >>> membership = membershipset.getByPersonAndTeam(t5.teamowner, t5)

    >>> membership.setStatus(TeamMembershipStatus.ADMIN, t5.teamowner)

    True

Changing membership data

------------------------

The only bits of a TeamMembership that can be changed are its status, expiry

date, reviewer[comment] and the date the user joined. From these ones, the

most interesting ones are the status and expiry date, which can only be set

through a specific API (setStatus() and setExpirationDate()) protected with

the launchpad.Edit permission. Also, since we don't want team admins to change

the expiry date of their own memberships, the setExpirationDate() method does

an extra check to ensure that doesn't happen.

    # Foo Bar is a launchpad admin, but even so he can't change a membership's

    # status/expiry-date by hand.

    >>> login_person(foobar)

    >>> membership = foobar.team_memberships[0]

    >>> membership.status = None

    Traceback (most recent call last):

    ...

    ForbiddenAttribute: ...

    >>> membership.dateexpires = None

    Traceback (most recent call last):

    ...

    ForbiddenAttribute: ...

Foo Bar asked to join Warty Security Team on 2006-01-26 and he's been doing

good work, so we'll approve his membership.

    >>> warty_team = getUtility(IPersonSet).getByName('name20')

    >>> membership = membershipset.getByPersonAndTeam(foobar, warty_team)

    >>> print membership.status.title

    Proposed

    >>> print membership.date_created.strftime("%Y-%m-%d")

    2006-01-26

    >>> print membership.datejoined

    None

When we approve his membership, the datejoined will contain the date that it

was approved. It returns True to indicate that the status was changed.

    >>> membership.setStatus(TeamMembershipStatus.APPROVED, foobar)

    True

    >>> print membership.status.title

    Approved

    >>> utc_now = datetime.now(pytz.timezone('UTC'))

    >>> membership.datejoined.date() == utc_now.date()

    True

If setStatus is called again with the same status, it returns False,

to indicate that the status didn't change.

    >>> membership.setStatus(TeamMembershipStatus.APPROVED, foobar)

    False

Other status updates won't change datejoined, regardless of the status.

That's because datejoined stores the date in which the membership was first

made active.

    >>> buildd_admins = getUtility(IPersonSet).getByName(

    ...     'launchpad-buildd-admins')

    >>> foobar_on_buildd = membershipset.getByPersonAndTeam(

    ...     foobar, buildd_admins)

    >>> print foobar_on_buildd.status.title

    Administrator

    >>> foobar_on_buildd.datejoined <= utc_now

    True

    >>> foobar_on_buildd.setStatus(

    ...     TeamMembershipStatus.DEACTIVATED, foobar)

    True

    >>> print foobar_on_buildd.status.title

    Deactivated

    >>> foobar_on_buildd.datejoined <= utc_now

    True

    >>> foobar_on_buildd.setStatus(

    ...     TeamMembershipStatus.APPROVED, foobar)

    True

    >>> print foobar_on_buildd.status.title

    Approved

    >>> foobar_on_buildd.datejoined <= utc_now

    True

When changing the expiry date we need to provide a date in the future and,

as mentioned above, the change can't be done by a team admin to his own

membership.

We're still logged in as Foo Bar, which is a launchpad admin and thus

can change any membership's expiry date (even his own), as long as

the new expiry date is not in the past.

    >>> foobar == foobar_on_buildd.team.teamowner

    True

    >>> foobar_on_buildd.canChangeExpirationDate(foobar)

    True

    >>> one_day_ago = datetime.now(pytz.timezone('UTC')) - timedelta(days=1)

    >>> tomorrow = datetime.now(pytz.timezone('UTC')) + timedelta(days=1)

    >>> foobar_on_buildd.setExpirationDate(one_day_ago, foobar)

    Traceback (most recent call last):

    ...

    AssertionError: ...

    >>> foobar_on_buildd.setExpirationDate(tomorrow, foobar)

Team owners and admins can also renew any memberships of the team they

own or administer.

    >>> landscape = getUtility(IPersonSet).getByName(

    ...     'landscape-developers')

    >>> sampleperson = getUtility(IPersonSet).getByName(

    ...     'name12')

    >>> sampleperson_on_landscape = membershipset.getByPersonAndTeam(

    ...     sampleperson, landscape)

    >>> landscape.teamowner.name

    u'name12'

    >>> sampleperson_on_landscape.canChangeExpirationDate(sampleperson)

    True

    >>> sampleperson_on_landscape.setExpirationDate(tomorrow, sampleperson)

    >>> cprov_on_buildd = membershipset.getByPersonAndTeam(

    ...     cprov, buildd_admins)

    >>> buildd_admins.teamowner.name

    u'name16'

    >>> print cprov_on_buildd.status.title

    Administrator

    >>> foobar_on_buildd.canChangeExpirationDate(cprov)

    True

    >>> foobar_on_buildd.setExpirationDate(tomorrow, cprov)

Flagging expired memberships

----------------------------

The expired memberships are flagged by a cronscript that runs daily. This

script simply flags all active memberships which reached their expiry date as

expired.

To find out which memberships are already expired, we use

TeamMembershipSet.getMembershipsToExpire(). As you can see, we don't have any

membership to expire right now.

    >>> [(membership.person.name, membership.team.name)

    ...  for membership in membershipset.getMembershipsToExpire()]

    []

Let's change the expiry date of an active membership, so we have something

that should be expired. Since we can't set an expiry date in the past for a

membership using setExpirationDate(), we'll have to cheat and access the

dateexpires attribute directly.

    >>> foobar_on_admins = membershipset.getByPersonAndTeam(

    ...     personset.getByName('name16'), personset.getByName('admins'))

    >>> foobar_on_admins.dateexpires is None

    True

    >>> foobar_on_admins.status.title

    'Administrator'

    >>> login('foo.bar@canonical.com')

    >>> removeSecurityProxy(foobar_on_admins).dateexpires = one_day_ago

    >>> flush_database_updates()

    >>> [(membership.person.name, membership.team.name)

    ...  for membership in membershipset.getMembershipsToExpire()]

    [(u'name16', u'admins')]

And here we change the expiry date of a membership that's already

deactivated, so it should not be flagged as expired.

    >>> sp_on_ubuntu_translators = membershipset.getByPersonAndTeam(

    ...     personset.getByName('name12'),

    ...     personset.getByName('ubuntu-translators'))

    >>> sp_on_ubuntu_translators.dateexpires is None

    True

    >>> sp_on_ubuntu_translators.status.title

    'Deactivated'

    >>> removeSecurityProxy(

    ...     sp_on_ubuntu_translators).dateexpires = one_day_ago

    >>> flush_database_updates()

    >>> [(membership.person.name, membership.team.name)

    ...  for membership in membershipset.getMembershipsToExpire()]

    [(u'name16', u'admins')]

The getMembershipsToExpire() method also accepts an optional 'when' argument.

When that argument is provided, we get the memberships that are supposed to

expire on that date or before.

    >>> mark_on_ubuntu_team = membershipset.getByPersonAndTeam(

    ...     personset.getByName('mark'),

    ...     personset.getByName('ubuntu-team'))

    >>> mark_on_ubuntu_team.dateexpires is not None

    True

    >>> mark_on_ubuntu_team.status.title

    'Administrator'

    >>> when = mark_on_ubuntu_team.dateexpires + timedelta(days=1)

    >>> [(membership.person.name, membership.team.name)

    ...  for membership in membershipset.getMembershipsToExpire(when=when)]

    [(u'mark', u'ubuntu-team'), (u'name16', u'admins'),

     (u'ubuntu-team', u'guadamen'), (u'name16', u'launchpad-buildd-admins'),

     (u'name12', u'landscape-developers')]

The getMembershipsToExpire() method also accepts an optional

'exclude_autorewals' argument.  When that argument is provided,

memberships in teams that are configured to renew the membership

automatically will be excluded. In that case, there is no reason to send

a warning email several days before the expiration. The user will just

be notified that the membership has already been automatically renewed

on the expiration day.

    >>> autorenewal_team = factory.makeTeam(name="autorenewal-team")

    >>> autorenewal_team.renewal_policy = (

    ...     TeamMembershipRenewalPolicy.AUTOMATIC)

    >>> autorenewal_team.defaultrenewalperiod = 73

    >>> otto = factory.makePerson(name='otto')

    >>> ignore = autorenewal_team.addMember(otto, salgado)

    >>> otto_membership = otto.team_memberships[0]

    >>> otto_membership.setExpirationDate(utc_now, salgado)

    >>> original_otto_date_expires = otto_membership.dateexpires

    >>> do_not_warn = factory.makePerson(name='do-not-warn')

    >>> ignore = autorenewal_team.addMember(do_not_warn, salgado)

    >>> do_not_warn.team_memberships[0].setExpirationDate(

    ...     tomorrow, salgado)

    # Not excluding teams with automatic renewals.

    >>> [(membership.person.name, membership.team.name)

    ...     for membership in membershipset.getMembershipsToExpire()

    ...     if membership.team.name == 'autorenewal-team']

    [(u'otto', u'autorenewal-team')]

    # Excluding teams with automatic renewals.

    >>> [(membership.person.name, membership.team.name)

    ...     for membership in membershipset.getMembershipsToExpire(

    ...         exclude_autorenewals=True)

    ...     if membership.team.name == 'autorenewal-team']

    []

Now we commit the changes and run the cronscript.

XXX: flush_database_updates() shouldn't be needed. This seems to be

Bug 3989 -- StuarBishop 20060713

    >>> flush_database_updates()

    >>> transaction.commit()

    >>> import subprocess

    >>> process = subprocess.Popen(

    ...     'cronscripts/flag-expired-memberships.py -v', shell=True,

    ...     stdin=subprocess.PIPE, stdout=subprocess.PIPE,

    ...     stderr=subprocess.PIPE)

    >>> (out, err) = process.communicate()

    >>> print out

A warning email should not have been sent to otto because it was renewed

inside the cronscript, and it should not be sent to do_not_warn, because

teams with automatic renewal don't need warnings.

    >>> print '\n'.join(

    ...     line for line in err.split('\n') if 'INFO' not in line)

    DEBUG   ...

    DEBUG   Sent warning email to name16 in launchpad-buildd-admins team.

    DEBUG   Sent warning email to name12 in landscape-developers team.

    DEBUG   Removing lock file: ...launchpad-flag-expired-memberships.lock

    >>> process.returncode

    0

    >>> transaction.abort()

Here we can see that the membership that was active is now flagged as expired

while the one that was inactive hasn't changed.

    >>> foobar_on_admins = membershipset.getByPersonAndTeam(

    ...     personset.getByName('name16'), personset.getByName('admins'))

    >>> foobar_on_admins.status.title

    'Expired'

    >>> foobar_on_admins.last_changed_by.name

    u'janitor'

    >>> sp_on_ubuntu_translators = membershipset.getByPersonAndTeam(

    ...     personset.getByName('name12'),

    ...     personset.getByName('ubuntu-translators'))

    >>> sp_on_ubuntu_translators.status.title

    'Deactivated'

    >>> otto_on_autorenewal_team = membershipset.getByPersonAndTeam(

    ...     otto, autorenewal_team)

    >>> otto_on_autorenewal_team.status.title

    'Approved'

    >>> otto_on_autorenewal_team.dateexpires - original_otto_date_expires

    datetime.timedelta(73)

Renewing team memberships

-------------------------

A team membership can be renewed before it has been expired by either

changing its dateexpires (which can be done only by admins of the

membership's team) or by using IPerson.renewTeamMembership, which is

accessible only to the membership's member a few days before it expires.

Also, for a member to renew his own membership, it's necessary that the

team's renewal policy is set to ONDEMAND and that the membership is

still active.

    >>> karl = personset.getByName('karl')

    >>> mirror_admins = personset.getByName('ubuntu-mirror-admins')

    >>> karl_on_mirroradmins = membershipset.getByPersonAndTeam(

    ...     karl, mirror_admins)

    >>> tomorrow = datetime.now(pytz.timezone('UTC')) + timedelta(days=1)

    >>> print karl_on_mirroradmins.status.title

    Approved

    >>> print karl_on_mirroradmins.dateexpires

    None

The member himself can't change the expiration date of his membership.

    >>> login_person(karl)

    >>> karl_on_mirroradmins.setExpirationDate(tomorrow, karl)

    Traceback (most recent call last):

    ...

    Unauthorized: ...

Only a team admin can.

    >>> login_person(mirror_admins.teamowner)

    >>> karl_on_mirroradmins.setExpirationDate(

    ...     tomorrow, mirror_admins.teamowner)

    >>> karl_on_mirroradmins.dateexpires == tomorrow

    True

If the team's renewal policy is ONDEMAND, the membership can be renewed

by the member himself. (That is only true because this membership is

active and set to expire tomorrow).

    >>> print karl_on_mirroradmins.team.renewal_policy.name

    NONE

    >>> karl_on_mirroradmins.canBeRenewedByMember()

    False

    >>> ondemand = TeamMembershipRenewalPolicy.ONDEMAND

    >>> karl_on_mirroradmins.team.renewal_policy = ondemand

    # When a user renews his own membership, we use the team's default

    # renewal period, so we must specify that for the mirror admins

    # team.

    >>> mirror_admins.defaultrenewalperiod = 365

    >>> flush_database_updates()

    >>> karl_on_mirroradmins.canBeRenewedByMember()

    True

    >>> login_person(karl)

    >>> karl.renewTeamMembership(mirror_admins)

Now the membership can't be renewed by the member as it's not going to

expire soon.

    >>> karl_on_mirroradmins.dateexpires == tomorrow + timedelta(days=365)

    True

    >>> karl_on_mirroradmins.canBeRenewedByMember()

    False

    >>> print karl_on_mirroradmins.status.title

    Approved

Querying team memberships

-------------------------

You can check a person's direct memberships by using team_memberships:

    >>> [(membership.team.name, membership.status.title)

    ...  for membership in salgado.team_memberships]

    [(u'hwdb-team', 'Approved'), (u'landscape-developers', 'Approved'),

     (u'admins', 'Administrator'), (u't4', 'Approved')]

And you can check which direct memberships a team has by using

member_memberships:

    >>> [(membership.person.name, membership.status.title)

    ...  for membership in t3.member_memberships]

    [(u'cprov', 'Approved'), (u'jdub', 'Administrator')]

A team has a number of other methods that return the people which are members

of it, all based on Person.getMembersByStatus:

    >>> [person.unique_displayname for person in t3.approvedmembers]

    [u'Celso Providelo (cprov)']

(which is the same as saying

    >>> [person.unique_displayname

    ...  for person in t3.getMembersByStatus(TeamMembershipStatus.APPROVED)]

    [u'Celso Providelo (cprov)']

except shorter)

We can also change the sort order of the results of getMembersByStatus.

    >>> login_person(cprov)

    >>> cprov.leave(t3)

    >>> flush_database_updates()

    >>> deactivated = TeamMembershipStatus.DEACTIVATED

    >>> [person.unique_displayname

    ...  for person in t3.getMembersByStatus(deactivated)]

    [u'Celso Providelo (cprov)', u'Guilherme Salgado (salgado)']

    >>> orderBy = '-TeamMembership.date_joined'

    >>> [person.unique_displayname

    ...  for person in t3.getMembersByStatus(deactivated, orderBy=orderBy)]

    [u'Celso Providelo (cprov)', u'Guilherme Salgado (salgado)']

Finding team administrators

---------------------------

Another convenient method is getDirectAdministrators(), which returns the

admin members plus the owner in case he is not one of the admin members.

    >>> [admin.unique_displayname for admin in t3.adminmembers]

    [u'Jeff Waugh (jdub)']

    >>> list(t3.getDirectAdministrators()) == list(t3.adminmembers)

    True

    >>> from lp.testing import person_logged_in

    >>> owner = factory.makePerson()

    >>> adminless_team = factory.makeTeam(owner=owner)

    >>> with person_logged_in(owner):

    ...     owner.leave(adminless_team)

    >>> adminless_team.adminmembers.count() == 0

    True

    >>> list(adminless_team.getDirectAdministrators()) == [owner]

    True

Note that the team administrators can contain teams, so if you want to

check if a user is an admin of the team, you should use inTeam() to

check if the user is a member of these administrators. For example,

cprov isn't a direct administrator of the guadamen team, but he is

an indirect administrator by being a member of the Ubuntu team (which

is a direct administrator of the guadamen team):

    >>> guadamen_team = personset.getByName('guadamen')

    >>> [person.name for person in guadamen_team.getDirectAdministrators()]

    [u'name16', u'ubuntu-team']

    >>> from lp.services.webapp.authorization import check_permission

    >>> ubuntu_team = personset.getByName('ubuntu-team')

    >>> cprov.inTeam(ubuntu_team)

    True

    >>> foobar in guadamen_team.getDirectAdministrators()

    True

    >>> cprov in guadamen_team.getDirectAdministrators()

    False

    >>> login('celso.providelo@canonical.com')

    >>> check_permission('launchpad.Edit', guadamen_team)

    True

There is also the getAdministratedTeams() method that returns all the

teams for which the person/team has admin rights.

    >>> cprov_team = factory.makeTeam(owner=cprov, name="cprov-team")

    >>> [team.name for team in cprov.getAdministratedTeams()]

    [u'canonical-partner-dev', u'cprov-team', u'guadamen',

     u'launchpad-buildd-admins']

If a team is merged it will not show up in the set of administered teams.

    >>> login('foo.bar@canonical.com')

    >>> membershipset.deactivateActiveMemberships(

    ...     cprov_team, "Merging", foobar)

    >>> personset.merge(cprov_team, guadamen_team, cprov_team.teamowner)

    >>> [team.name for team in cprov.getAdministratedTeams()]

    [u'canonical-partner-dev', u'guadamen', u'launchpad-buildd-admins']

Querying a person for team participation

----------------------------------------

Team membership is direct; team participation is indirect, people being

participants of teams by virtue of being members of other teams which are in

turn members of these teams.

We can ask a person what teams they participate in. The

teams_participated_in attribute works recursively, listing all teams the

person is an active member of as well as teams those teams are an active

member of.

    >>> login('celso.providelo@canonical.com')

    >>> print '\n'.join(sorted(

    ...     team.name for team in salgado.teams_participated_in))

    admins

    hwdb-team

    landscape-developers

    mailing-list-experts

    t4

Adding admins as a member of t1 will make Salgado a member of t1 as well.

    >>> admins = getUtility(IPersonSet).getByName('admins')

    >>> login_person(t1.teamowner)

    >>> t1.addMember(admins, reviewer=t1.teamowner, force_team_add=True)

    (True, <DBItem TeamMembershipStatus.APPROVED...)

    >>> flush_database_updates()

    >>> print '\n'.join(sorted(

    ...     team.name for team in salgado.teams_participated_in))

    admins

    hwdb-team

    landscape-developers

    mailing-list-experts

    t1

    t4

On the other hand, making t3 a member of admins won't change anything

for Salgado.

    >>> login_person(foobar)

    >>> admins.addMember(t3, reviewer=admins.teamowner, force_team_add=True)

    (True, <DBItem TeamMembershipStatus.APPROVED...)

    >>> flush_database_updates()

    >>> print '\n'.join(sorted(

    ...     team.name for team in salgado.teams_participated_in))

    admins

    hwdb-team

    landscape-developers

    mailing-list-experts

    t1

    t4