Ballot

class whalrus.Ballot[source]

A ballot.

The philosophy of this class is to stick as much as possible to the message that the voter emitted, in the context where she emitted it. For example, consider a range voting setting with candidates a, b, c and a scale of grades from 0 to 100. If the voter emits a ballot where a has grade 60 and b has grade 30, then the Ballot object simply records all this: what candidates were present, what was the scale of authorized grades, and what the voter indicated in her ballot. But, for example:

  • It makes no assumption whether the voter prefers a to c. Maybe she did not mention c because she didn’t like it, maybe because she didn’t know it.
  • It makes no assumption about what would be the voter’s ballot with a scale from 0 to 10. Maybe it would be {'a': 6, 'b': 3}, maybe not.

Ballot converters (cf. ConverterBallot) will be used each time we need an information that is beyond what the ballot clearly indicated.

candidates

The candidates that were available at the moment when the voter cast her ballot. As a consequence, candidates must be hashable objects.

Type:NiceSet
first(candidates: set = None, **kwargs) → object[source]

The first (= most liked) candidate. Implementation is optional.

In most subclasses, this method needs some options (kwargs) to solve ambiguities in this conversion. In some other subclasses, this method may even stay unimplemented.

Parameters:
  • candidates (set of candidates) – It can be any set of candidates, not necessarily a subset of self.candidates). Default: self.candidates.
  • kwargs – Some options (depending on the subclass).
Returns:

The first (= most liked) candidate, chosen in the intersection of self.candidates and the argument candidates. Can return None for an “abstention”.
Return type:

candidate

Examples

Typical example: the ballot was cast in a context where candidates a, b, c, d were declared. Hence self.candidates == {'a', 'b', 'c', 'd'}. Later, candidate a is removed from the election. Then we can use this method with the optional argument candidates = {'b', 'c', 'd'} to know who is the most liked candidate of the voter in this new context.

last(candidates: set = None, **kwargs) → object[source]

The last (= most disliked) candidate. Implementation is optional.

Cf. first() for more information.

Parameters:
  • candidates (set of candidates) – It can be any set of candidates, not necessarily a subset of self.candidates). Default: self.candidates.
  • kwargs – Some options (depending on the subclass).
Returns:

The last (= most disliked) candidate, chosen in the intersection of self.candidates and the argument candidates. Can return None for an “abstention”.
Return type:

candidate
restrict(candidates=None, **kwargs) → whalrus.ballots.ballot.Ballot[source]

Restrict the ballot to less candidates.

Implementation is optional.

Additional candidates (that are in the argument candidates but not in self.candidates) are generally not taken into account in the restricted ballot. For example, in a election with candidates a, b, c, assume that the voter emits an ordered ballot a > b > c. Later, candidate a is removed and candidate d is added. Then the “restricted” ballot to {'b, 'c', 'd'} is b > c. For more details, see for example BallotOrder.restrict().

Parameters:
  • candidates (set of candidates) – It can be any set of candidates, not necessarily a subset of self.candidates). Default: self.candidates.
  • kwargs – Some options (depending on the subclass).
Returns:

The same ballot, “restricted” to the candidates given.
Return type:

Ballot