fairdm.contrib.contributors.services.crediting

The one place the contributors of a project, dataset, sample or measurement are changed.

Module Contents

Classes

Crediting

Add, change and remove the contributors of one record.

Data

UNCHANGED

Passed as the organization of Crediting.update to leave it as it is.

API

UNCHANGED

‘object(…)’

Passed as the organization of Crediting.update to leave it as it is.

class Crediting(record)

Add, change and remove the contributors of one record.

Each refusal is a ValidationError with a code, so a page can attach it to a field and a test can assert on it.

Args: record: A project, dataset, sample or measurement, of any registered type. A sample or measurement held as its base class is changed as its real type, which is where its contributors and their levels are read.

Initialization

locked()

Hold the record’s row for the length of a change, in one transaction.

Two changes to one record wait for each other, so each reads the contributors the other left. A private record is found too. A database that cannot lock rows runs the change in the transaction alone.

Yields: Nothing. Read the record’s contributors only inside the block.

would_leave_no_manager(contribution, level=None)

Say whether removing a contribution, or lowering its level, leaves nobody to manage.

Only going from at least one person who counts as able to manage the record to none is a refusal. A record that has no manager already may lose or raise anyone.

Args: contribution: The contribution on this record to remove or lower. level: The level it would be given. None asks about removing it.

Returns: True when the contribution is the only thing that makes the record manageable.

last_manager_refusal(contribution)

Build the refusal for a change that would leave the record with nobody to manage.

Args: contribution: The contribution of the person who must stay.

Returns: A ValidationError with code last_manager.

offered_roles()

Return the contribution roles the record’s type offers.

Returns: The concepts of the contributor roles collection for this type, in the collection’s order.

add(contributor, *, organization=None)

List a contributor on the record, last of its kind. A person starts at the view level.

Args: contributor: The person or organization to list. organization: The organization a person is credited from on this record, listed on the record too if it is not already. None credits them from none. Ignored for an organization.

Returns: The new contribution.

Raises: ValidationError: With code superuser when they are a superuser, who cannot be credited, anonymous when they are the placeholder account that stands for every visitor, or duplicate when the contributor is already listed.

list_organization(organization)

List an organization on the record, unless it already is.

Args: organization: The organization to list.

update(contribution, *, roles, level=None, organization=UNCHANGED)

Replace the roles a contributor holds on the record, and for a person the level and organization.

Args: contribution: The contribution to change. roles: Concepts of the contributor roles vocabulary, none or more. level: The level to give a person, a ContributionLevel. None leaves it as it is. Ignored for an organization. organization: The organization a person is credited from, listed on the record too if it is not already. None credits them from none, and UNCHANGED leaves it as it is. Ignored for an organization.

Raises: ValidationError: With code role_not_offered when a role is not in the group the record’s type offers, and below_inherited when the level is below what the person holds from a record above, and last_manager when it would leave the record with nobody who counts as able to manage it. When several apply the error holds them all, in its error_list. Nothing is saved.

remove(contribution)

Remove a contributor from the record, and with them the level they held on it.

Args: contribution: The contribution to remove.

Raises: ValidationError: With code credited_from when it is an organization that people on the record are credited from, its params["people"] listing them, and last_manager when it is the only person who counts as able to manage the record. Nothing is removed.

move(contribution, direction)

Move a contributor one place earlier or later among the contributors of its kind.

People are placed among people and organizations among organizations, so the other list is left alone. The first moving earlier and the last moving later change nothing. Where old data gives two contributors the same place, their places are told apart by their creation order first.

Args: contribution: The contribution to move, on this record. direction: "up" for earlier or "down" for later.

Raises: ValidationError: With code direction when it is neither, and not_listed when the contribution is not on this record. Nothing is moved.

make_creator(user, *, roles=())

List the person who created the record at the manage level.

A superuser cannot be credited, so for one this does nothing and the create still succeeds.

Args: user: The person who created the record. roles: Addresses of contributor role concepts to give them. They are not checked against the record type’s collection.

Returns: The creator’s contribution, or None for a superuser.

credited_from()

Say who on the record is credited from each organization.

Returns: A dictionary from an organization’s id to the people credited from it on this record, in their order.