lp.registry.interfaces.webservice.IPersonSet : API documentation

title =

Title

@collection_default_content()
def getTopContributors(limit=50):

Return the top contributors in Launchpad, up to the given limit.

def isNameBlacklisted(name, user=None):

Is the given name blacklisted by Launchpad Administrators?

Parameters	name	The name to be checked.
	user	The `IPerson` that wants to use the name. If the user is an admin for the nameblacklist expression, they can use the name.

def createPersonAndEmail(email, rationale, comment=None, name=None, displayname=None, hide_email_addresses=False, registrant=None):

Create and return an IPerson and IEmailAddress.

The newly created EmailAddress will have a status of NEW and will be linked to the newly created Person.

An Account is also created, but this will change in the future!

If the given name is None, we generate a unique nickname from the email address given.

Parameters	email	The email address, as text.
	rationale	An item of `PersonCreationRationale` to be used as the person's creation_rationale.
	comment	A comment explaining why the person record was created (usually used by scripts which create them automatically). Must be of the following form: "when %(action_details)s" (e.g. "when the foo package was imported into Ubuntu Breezy").
	name	The person's name.
	displayname	The person's displayname.
	registrant	The user who created this person, if any.
	hide_email_addresses	Whether or not Launchpad should hide the person's email addresses from other users.
Raises	InvalidName	When the given name is not valid.
	InvalidEmailAddress	When the given email is not valid.
	NameAlreadyTaken	When the given name is already in use.
	EmailAddressAlreadyTaken	When the given email is already in use.
	NicknameGenerationError	When no name is provided and we can't generate a nickname from the given email address.

def createPersonWithoutEmail(name, rationale, comment=None, displayname=None, registrant=None):

Create and return an IPerson without using an email address.

Parameters	name	The person's name.
	comment	A comment explaining why the person record was created (usually used by scripts which create them automatically). Must be of the following form: "when %(action_details)s" (e.g. "when the foo package was imported into Ubuntu Breezy").
	displayname	The person's displayname.
	registrant	The user who created this person, if any.
Raises	InvalidName	When the passed name isn't valid.
	NameAlreadyTaken	When the passed name has already been used.

def createPlaceholderPerson(openid_identifier, name):

Create and return an SSO username placeholder IPerson.

The returned Person will have no email address, just a username and an OpenID identifier.

Parameters	openid_identifier	The SSO account's OpenID suffix.
	name	The person's name.
Raises	InvalidName	When the passed name isn't valid.
	NameAlreadyTaken	When the passed name has already been used.

def ensurePerson(email, displayname, rationale, comment=None, registrant=None):

Make sure that there is a person in the database with the given email address. If necessary, create the person, using the displayname given.

The comment must be of the following form: "when %(action_details)s" (e.g. "when the foo package was imported into Ubuntu Breezy").

If the email address is already registered and bound to an IAccount, the created IPerson will have 'hide_email_addresses' flag set to True.

XXX sabdfl 2005-06-14: this should be extended to be similar or identical to the other person creation argument lists, so we can call it and create a full person if needed. Email would remain the deciding factor, we would not try and guess if someone existed based on the displayname or other arguments.

@operation_parameters(TextLine(True))
@operation_returns_entry(IPerson)
@export_read_operation()
@operation_for_version('devel')
def getByOpenIDIdentifier(identifier):

Get the person for a given OpenID identifier.

Parameters	openid_identifier	full OpenID identifier URL for the user.
Returns	the corresponding `IPerson` or None if the identifier is unknown

def getOrCreateByOpenIDIdentifier(openid_identifier, email, full_name, creation_rationale, comment):

Get or create a person for a given OpenID identifier.

This is used when users login. We get the account with the given
OpenID identifier (creating one if it doesn't already exist) and
act according to the account's state:
  - If the account is suspended, we stop and raise an error.
  - If the account is deactivated, we reactivate it and proceed;
  - If the account is active, we just proceed.

If there is no existing Launchpad person for the account, we
create it.

:param openid_identifier: OpenID identifier suffix for the user.
    This is *not* the full URL, just the unique suffix portion.
:param email_address: the email address of the user.
:param full_name: the full name of the user.
:param creation_rationale: When an account or person needs to
    be created, this indicates why it was created.
:param comment: If the account is reactivated or person created,
    this comment indicates why.
:return: a tuple of `IPerson` and a boolean indicating whether the
    database was updated.
:raises AccountSuspendedError: if the account associated with the
    identifier has been suspended.

@call_with(REQUEST_USER)
@operation_parameters(TextLine(_('OpenID identifier suffix'), True), TextLine(_('Email address'), True), TextLine(_('Display name'), True))
@operation_returns_entry(IPerson)
@export_write_operation()
@operation_for_version('devel')
def getOrCreateSoftwareCenterCustomer(user, openid_identifier, email_address, display_name):

Restricted person creation API for Software Center Agent.

This method can only be called by Software Center Agent. It gets a person by OpenID identifier or creates a new Launchpad person from the OpenID identifier, email address and display name.

Parameters	user	the `IPerson` performing the operation. Only the software-center-agent celebrity is allowed.
	openid_identifier	OpenID identifier suffix for the user. This is not the full URL, just the unique suffix portion.
	email_address	the email address of the user.
	full_name	the full name of the user.

@call_with(REQUEST_USER)
@operation_parameters(TextLine(_('OpenID identifier suffix'), True))
@export_read_operation()
@operation_for_version('devel')
def getUsernameForSSO(user, openid_identifier):

Restricted person creation API for SSO.

This method can only be called by the Ubuntu SSO service. It finds the username for an account by OpenID identifier.

Parameters	user	the `IPerson` performing the operation. Only the ubuntu-sso celebrity is allowed.
	openid_identifier	OpenID identifier suffix for the user. This is not the full URL, just the unique suffix portion.

@call_with(REQUEST_USER)
@operation_parameters(TextLine(_('OpenID identifier suffix'), True), copy_field(IPerson['name']), Bool(_("Don't save changes")))
@export_write_operation()
@operation_for_version('devel')
def setUsernameFromSSO(user, openid_identifier, name, dry_run=False):

Restricted person creation API for SSO.

This method can only be called by the Ubuntu SSO service. It reserves a username for an account by OpenID identifier, as long as the user has no Launchpad account.

Parameters	user	the `IPerson` performing the operation. Only the ubuntu-sso celebrity is allowed.
	openid_identifier	OpenID identifier suffix for the user. This is not the full URL, just the unique suffix portion.
	name	the desired username.
Raises	`InvalidName` if the username doesn't meet character constraints.
	`NameAlreadyTaken` if the username is already in use.
	`NotPlaceholderAccount` if the OpenID identifier has a non-placeholder Launchpad account.

@call_with(REQUEST_USER)
@operation_parameters(TextLine(_('OpenID identifier suffix'), True))
@export_read_operation()
@operation_for_version('devel')
def getSSHKeysForSSO(user, openid_identifier):

Restricted SSH key creation API for SSO.

This method can only be called by the Ubuntu SSO service. It finds and returns all the SSH keys belonging to the account identified by the openid_identifier parameter.

Parameters	user	the `IPerson` performing the operation. Only the ubuntu-sso celebrity is allowed.
	openid_identifier	OpenID identifier suffix for the user. This is not the full URL, just the unique suffix portion.

@call_with(REQUEST_USER)
@operation_parameters(TextLine(_('OpenID identifier suffix'), True), TextLine(_('SSH key text'), True), Bool(_("Don't save changes")))
@export_write_operation()
@operation_for_version('devel')
def addSSHKeyFromSSO(user, openid_identifier, key_text, dry_run=False):

Restricted SSH key creation API for SSO.

This method can only be called by the Ubuntu SSO service. It adds a new SSH key to the account identified by 'openid_identifier' based on the 'key_text' parameter.

Parameters	user	the `IPerson` performing the operation. Only the ubuntu-sso celebrity is allowed.
	openid_identifier	OpenID identifier suffix for the user. This is not the full URL, just the unique suffix portion.
	key_text	The full text of the SSH Key.
Raises	NoSuchAccount	If the openid_identifier specified does not match any account.
	SSHKeyAdditionError	If the ssh key_text is invalid.

@call_with(REQUEST_USER)
@operation_parameters(TextLine(_('OpenID identifier suffix'), True), Text(_('SSH key text'), True), Bool(_("Don't save changes")))
@export_write_operation()
@operation_for_version('devel')
def deleteSSHKeyFromSSO(user, openid_identifier, key_text, dry_run=False):

Restricted SSH key deletion API for SSO.

This method can only be called by the Ubuntu SSO service. It deletes an SSH key from the account identified by 'openid_identifier' based on the 'key_text' parameter.

Parameters	user	the `IPerson` performing the operation. Only the ubuntu-sso celebrity is allowed.
	openid_identifier	OpenID identifier suffix for the user. This is not the full URL, just the unique suffix portion.
	key_text	The full text of the SSH Key.
Raises	NoSuchAccount	If the openid_identifier specified does not match any account.
	KeyAdditionError	If the key text is invalid.

@call_with(REQUEST_USER)
@rename_parameters_as('team_description', 'default_membership_period', 'default_renewal_period')
@operation_parameters(Choice(_('Membership policy'), TeamMembershipPolicy, False, TeamMembershipPolicy.MODERATED))
@export_factory_operation(ITeam, 'name''display_name''teamdescription''defaultmembershipperiod''defaultrenewalperiod''subscription_policy')
@operation_for_version('beta')
def newTeam(teamowner, name, display_name, teamdescription=None, membership_policy=TeamMembershipPolicy.MODERATED, defaultmembershipperiod=None, defaultrenewalperiod=None, subscription_policy=None):

Create and return a new Team with given arguments.

def get(personid):

Return the person with the given id or None if it's not found.

@operation_parameters(TextLine(True, email_validator))
@operation_returns_entry(IPerson)
@export_read_operation()
@operation_for_version('beta')
def getByEmail(email):

Return the person with the given email address.

Return None if there is no person with the given email address.

def getByEmails(emails, include_hidden=True):

Search for people with the given email addresses.

Parameters	emails	A list of email addresses.
	include_hidden	Include people who have opted to hide their email. Defaults to True.
Returns	A `ResultSet` of `IEmailAddress`, `IPerson`.

def getByName(name, ignore_merged=True):

Return the person with the given name, ignoring merged persons if ignore_merged is True.

Return None if there is no person with the given name.

def getByAccount(account):

Return the IPerson with the given account, or None.

def updateStatistics():

Update statistics caches and commit.

def peopleCount():

Return the number of non-merged persons in the database as of the last statistics update.

def teamsCount():

Return the number of teams in the database as of the last statistics update.

@operation_parameters(TextLine(_('Search text'), u''))
@operation_returns_collection_of(IPerson)
@export_read_operation()
@operation_for_version('beta')
def find(text=''):

Return all non-merged Persons and Teams whose name, displayname or email address match <text>.

The results will be ordered using the default ordering specified in Person._defaultOrder.

While we don't have Full Text Indexes in the emailaddress table, we'll be trying to match the text only against the beginning of an email address.

@operation_parameters(TextLine(_('Search text'), u''), Datetime(_('Created after'), False), Datetime(_('Created before'), False))
@operation_returns_collection_of(IPerson)
@export_read_operation()
@operation_for_version('beta')
def findPerson(text='', exclude_inactive_accounts=True, must_have_email=False, created_after=None, created_before=None):

Return all non-merged Persons with at least one email address whose name, displayname or email address match <text>.

If text is an empty string, all persons with at least one email address will be returned.

The results will be ordered using the default ordering specified in Person._defaultOrder.

If exclude_inactive_accounts is True, any accounts whose account_status is any of INACTIVE_ACCOUNT_STATUSES will not be in the returned set.

If must_have_email is True, only people with one or more email addresses are returned.

While we don't have Full Text Indexes in the emailaddress table, we'll be trying to match the text only against the beginning of an email address.

If created_before or created_after are not None, they are used to restrict the search to the dates provided.

@call_with(True)
@operation_parameters(TextLine(_('Search text'), u''))
@operation_returns_collection_of(IPerson)
@export_read_operation()
@operation_for_version('beta')
def findTeam(text='', preload_for_api=False):

Return all Teams whose name, displayname or email address match <text>.

The results will be ordered using the default ordering specified in Person._defaultOrder.

While we don't have Full Text Indexes in the emailaddress table, we'll be trying to match the text only against the beginning of an email address.

def mergeAsync(from_person, to_person, requester, reviewer=None, delete=False):

Merge a person/team into another asynchronously.

This schedules a call to merge() to happen outside of the current context/request. The intention is that it is called soon after this method is called but there is no guarantee of that, nor is that call guaranteed to succeed. If either user is in a pending person merge job, None is returned.

Parameters	from_person	An IPerson or ITeam that is a duplicate.
	to_person	An IPerson or ITeam that is a master.
	requester	The IPerson who requested the merge. Should not be an ITeam.
	reviewer	An IPerson who approved the ITeam merger.
	delete	The merge is really a deletion.
Returns	A `PersonMergeJob` or None.

def getValidPersons(persons):

Get all the Persons that are valid.

This method is more effective than looking at Person.is_valid_person_or_team, since it avoids issuing one DB query per person. It queries the ValidPersonOrTeamCache table, issuing one query for all the person records. This makes the method useful for filling the ORM cache, so that checks to .is_valid_person won't issue any DB queries.

XXX: This method exists mainly to fill the ORM cache for: ValidPersonOrTeamCache. It would be better to add a column to the Person table. If we do that, this method can go away. Bug 221901. -- Bjorn Tillenius, 2008-04-25

def getPeopleWithBranches(product=None):

Return the people who have branches.

Parameters product If supplied, only people who have branches in the specified product are returned.

def updatePersonalStandings():

Update the personal standings of some people.

Personal standing controls whether a person can post to a mailing list they are not a member of without moderation. A person starts out with Unknown standing. Once they have at least one message approved for three different lists, this method will bump their standing to Good. If a person's standing is already Good, or Poor or Excellent, no change to standing is made.

def cacheBrandingForPeople(people):

Prefetch Librarian aliases and content for personal images.

def getPrecachedPersonsFromIDs(person_ids, need_api=False, need_karma=False, need_ubuntu_coc=False, need_location=False, need_archive=False, need_preferred_email=False, need_validity=False):

Lookup person objects from ids with optional precaching.

Parameters	person_ids	List of person ids.
	need_api	All attributes needed by the JSON representation will be cached.
	need_karma	The karma attribute will be cached.
	need_ubuntu_coc	The is_ubuntu_coc_signer attribute will be cached.
	need_location	The location attribute will be cached.
	need_archive	The archive attribute will be cached.
	need_preferred_email	The preferred email attribute will be cached.
	need_validity	The is_valid attribute will be cached.

Attribute	title	Title
Method	getTopContributors	Return the top contributors in Launchpad, up to the given limit.
Method	isNameBlacklisted	Is the given name blacklisted by Launchpad Administrators?
Method	createPersonAndEmail	Create and return an `IPerson` and `IEmailAddress`.
Method	createPersonWithoutEmail	Create and return an `IPerson` without using an email address.
Method	createPlaceholderPerson	Create and return an SSO username placeholder `IPerson`.
Method	ensurePerson	Make sure that there is a person in the database with the given
Method	getByOpenIDIdentifier	Get the person for a given OpenID identifier.
Method	getOrCreateByOpenIDIdentifier	Get or create a person for a given OpenID identifier.
Method	getOrCreateSoftwareCenterCustomer	Restricted person creation API for Software Center Agent.
Method	getUsernameForSSO	Restricted person creation API for SSO.
Method	setUsernameFromSSO	Restricted person creation API for SSO.
Method	getSSHKeysForSSO	Restricted SSH key creation API for SSO.
Method	addSSHKeyFromSSO	Restricted SSH key creation API for SSO.
Method	deleteSSHKeyFromSSO	Restricted SSH key deletion API for SSO.
Method	newTeam	Create and return a new Team with given arguments.
Method	get	Return the person with the given id or None if it's not found.
Method	getByEmail	Return the person with the given email address.
Method	getByEmails	Search for people with the given email addresses.
Method	getByName	Return the person with the given name, ignoring merged persons if
Method	getByAccount	Return the `IPerson` with the given account, or None.
Method	updateStatistics	Update statistics caches and commit.
Method	peopleCount	Return the number of non-merged persons in the database as
Method	teamsCount	Return the number of teams in the database as of the last
Method	find	Return all non-merged Persons and Teams whose name, displayname or
Method	findPerson	Return all non-merged Persons with at least one email address whose
Method	findTeam	Return all Teams whose name, displayname or email address
Method	mergeAsync	Merge a person/team into another asynchronously.
Method	getValidPersons	Get all the Persons that are valid.
Method	getPeopleWithBranches	Return the people who have branches.
Method	updatePersonalStandings	Update the personal standings of some people.
Method	cacheBrandingForPeople	Prefetch Librarian aliases and content for personal images.
Method	getPrecachedPersonsFromIDs	Lookup person objects from ids with optional precaching.

l.r.i.w.IPersonSet(Interface) : interface documentation