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.-
property
candidates
¶ The candidates that were available at the moment when the voter cast her ballot. As a consequence, candidates must be hashable objects.
- Type
-
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 argumentcandidates
. 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 argumentcandidates = {'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 argumentcandidates
. 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 inself.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 ballota > b > c
. Later, candidate a is removed and candidate d is added. Then the “restricted” ballot to{'b, 'c', 'd'}
isb > c
. For more details, see for exampleBallotOrder.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