Candidate objects and candidacy (nomination) validation API

Candidate specifications and nomination validators.

Contains definitions of candidate types and interfaces (Candidate, ElectionParty, Coalition), constituencies (Constituency), special vote variants (NoneOfTheAbove, ReopenNominations) and candidate/nomination validators (BasicNominator, PersonNominator, PartyNominator).

Apart from the candidate objects specified here, Votelib also accepts strings with candidate names in all concerned places. The subclasses of this class are thus only needed for systems considering candidate properties such as coalition size-dependent electoral thresholds. For a particular example of this, the votelib.evaluate.threshold.PropertyBracketer chooses different rules based on a value of an arbitrary property of the candidate. You can use any object that has the specified property defined; the classes defined here can be assigned arbitrary additional properties, so they, too, can be used.

Candidate objects and interfaces

votelib.candidate.Candidate

alias of Union[str, votelib.candidate.CandidateObject]

class votelib.candidate.IndividualElectionOption

An abstract class for individuals standing for an election.

candidacy_for: Optional[votelib.candidate.ElectionParty] = NotImplemented

The party for which this choice is candidating for the election.

This is important for counting party-based election results where the votes are cast and counted for candidates.

If the candidate is endorsed by multiple parties, use a Coalition object.

membership: Optional[votelib.candidate.PoliticalParty] = NotImplemented

The party the candidate is member of.

This is important for counting party-based election results where the votes are cast and counted for candidates.

class votelib.candidate.Person(name, number=None, membership=None, candidacy_for=None, properties=None, withdrawn=False)

A physical person standing for the election.

Parameters

  • name (str) – Name of the person, in any customary text format.

  • number (Optional[int]) – Candidacy number assigned to the person for the purpose of the election; usually drawn by lot.

  • membership (Optional[PoliticalParty]) – A political party the person is member of, if any.

  • candidacy_for (Optional[ElectionParty]) – A political party for which the person is standing in the election. If there is no such party, the person is considered an independent candidate.

  • withdrawn (bool) – Whether the candidate withdrew from the election (and is thus ineligible to get elected).

class votelib.candidate.ElectionParty

A subject that is regarded as a political party for the election.

is_coalition = NotImplemented

Whether the party is a coalition.

This makes a difference for some systems; the most common case is a heightened vote threshold in proportional elections.

class votelib.candidate.PoliticalParty(name, number=None, affiliations=None, lead=None, properties=None, withdrawn=False)

A political party or movement that is eligible to stand in elections.

Parameters

  • name (str) – Name of the party, in any customary text format.

  • number (Optional[int]) – Candidacy number assigned to the party for the purpose of the election; usually drawn by lot.

  • affiliation – Other (e.g. national or supranational) parties this party is affiliated with, if any.

  • lead (Optional[Person]) – A person that leads the party into the elections.

class votelib.candidate.Coalition(parties, name=None, number=None, affiliations=None, lead=None, withdrawn=False)

A coalition of two or more election-eligible parties.

Parameters

  • parties (List[PoliticalParty]) – Parties involved in the coalition.

  • name (Optional[str]) – Name of the coalition, in any customary text format. If not given, it is derived from the names of the member parties.

  • number (Optional[int]) – Candidacy number assigned to the coalition for the purpose of the election; usually drawn by lot.

  • affiliations (Optional[List[PoliticalParty]]) – Other (e.g. national or supranational) parties this coalition is affiliated with, if any.

  • lead (Optional[Person]) – A person that leads the coalition into the elections.

get_n_coalition_members()

Return the number of member parties in the coalition.

This is important in some elections which specify different thresholds for coalitions with a given number of members.

Return type

int

Blank votes and other special vote options

class votelib.candidate.BlankVoteOption(name)

A base class for blank (non-partisan) vote choices.

This includes votes that are not counted to any candidate. In some rare cases, these votes have a special effect (such as triggering a new election if there is a sufficient number of them), but most of the time they can be safely disregarded.

class votelib.candidate.NoneOfTheAbove(name)

None of the above (NOTA) vote option (often called white ballots).

In some contexts, a sufficient number of these votes can trigger a special effect such as a new election.

Parameters

name (str) – Actual name of the NOTA option in the given context.

class votelib.candidate.ReopenNominations(name)

Reopen Nominations vote option.

In some elections, this option is present; if it prevails, it can trigger a new round of nominations and a new election.

Parameters

name (str) – Actual name of the Reopen Nominations option in the given context.

Mapping candidates to parties

class votelib.candidate.IndividualToPartyMapper(affiliation='candidacy_for', independents='aggregate')

Define mapping from individuals to parties.

A candidate object such as a Person might define multiple party relationships or define that the candidate is standing for the election as an independent. This object can be added as a component to some converters or evaluators to map individuals to parties correctly according to the rules of the particular election system.

Parameters

  • affiliation (str) –

    How to allocate the candidate to the party:

    • ’candidacy_for’ (default) uses the party the candidate stood for (was endorsed by) in the election,

    • ’membership’ uses the party the candidate is a member of.

  • independents (str) –

    How to handle individual candidates not candidating for a party:

    • ’aggregate’ (default) aggregates them under the None key to a total count,

    • ’keep’ keeps them separately,

    • ’ignore’ omits them from the result,

    • ’error’ raises an error.

Constituency objects

class votelib.candidate.Constituency

A constituency for elections with multiple sets of candidates.

Constituencies are used where the electorate is separated into more than one group. The most common variant is spatial - electoral or voting districts (also called wards or precincts). This object should be used only for cases where such spatial division is used to evaluate the result, not merely used to collect and count the ballots.

Non-spatial variants include curias (used in 19th century Austria-Hungary for different social classes), ethnical divisions (Maori electorates in New Zealand) or qualificational divisions (University constituencies in Ireland).

In the current version of Votelib, special constituency objects are not needed (any hashable objects such as strings can be used for all functionality implemented so far and will continue to be supported by the existing features in the future) so this is essentially just a type marker, but further development might necessitate creating some subclasses of this, and more specific interfaces.

Nomination (candidate) validators

class votelib.candidate.BasicNominator(allow_blank=True)

Validate that the election candidates are valid objects.

Does not do any logical checks; only validates that the candidate instance passes the criteria of the Candidate class (such as checking against most types of collections).

Parameters

allow_blank (bool) – Whether to allow blank votes (NOTA, ReopenNominations).

validate(candidate)

Check whether a candidate is valid.

Parameters

candidate (Union[str, CandidateObject]) – Candidate to be checked.

Raises

CandidateError – If a candidate is invalid.

Return type

None

class votelib.candidate.PersonNominator(allow_independents=True, allow_blank=True)

Validate that election candidates are physical persons and not parties.

Parameters

  • allow_independents (bool) – Whether persons candidating without a support of a political party can stand in the election.

  • allow_blank (bool) – Whether to allow blank votes (NOTA, ReopenNominations).

validate(candidate)

Check whether a candidate is valid.

Parameters

candidate (Union[str, CandidateObject]) – Candidate to be checked.

Raises

CandidateError – If a candidate is invalid.

Return type

None

class votelib.candidate.PartyNominator(allow_coalitions=True, allow_blank=True)

Check that election candidates are electoral parties, not persons.

This includes political parties in the broadest sense of the term, as well as their coalitions formed for the purpose of the election.

Only instances of ElectionParty and its subclasses are accepted, as are classes that pass the interface check of the class, if there is one. Blank votes are accepted by default and can be disallowed, like coalitions.

Parameters

  • allow_coalitions (bool) – Whether to allow coalitions.

  • allow_blank (bool) – Whether to allow blank votes (NOTA, ReopenNominations).

validate(candidate)

Check whether a candidate is a valid election party.

Parameters

candidate (Union[str, CandidateObject]) – Candidate to be checked.

Raises

CandidateError – If a candidate is not a valid election party candidate.

Return type

None

An abstract class defining the nominator interface is also present.

class votelib.candidate.Nominator

An abstract class for nominators (candidacy validators).

abstract validate(candidate)

Check if the candidate satisfies criteria given by the system.

Raises

NotImplementedError –

Return type

None

Nomination (candidate) validation errors

class votelib.candidate.CandidateError(candidate, expected=None)

A candidate is invalid in the given context.

E.g. parties in place of individual candidates, or candidates ineligible to stand for given seats.

Parameters

  • candidate (Any) – Candidate that was found to be invalid.

  • expected (Optional[Any]) – Definition of a candidate that was expected.