Ballot module

Module describing different ballot formats that can be used. A ballot is the entity that contains the information submitted by a voter in an election. It can take many forms, from simple approval ballots in which a voter just indicates the projects they approve of, to more complex cardinal ballot in which a score is assigned to the projects.

This module introduces the abstract class AbstractBallot, that all ballot classes inherit from. Two general categories of ballots are also introduced. First, the standard ballots, that all inherit from the class Ballot. These ballots correspond to the following classes:

• ApprovalBallot

• CardinalBallot

• CumulativeBallot

• OrdinalBallot

The second category of ballot this module defines are the so-called frozen ballots. These are ballots that behave exactly as the corresponding regular ballots, but that are not mutable, and thus are hashable. These classes are important for us as they allow ballots to be key of dictionaries (see the MultiProfile class). These ballots correspond to the following classes:

• FrozenApprovalBallot

• FrozenCardinalBallot

• FrozenCumulativeBallot

• FrozenOrdinalBallot

For typing purposes, we introduce abstract classes for each type of ballots:

• AbstractApprovalBallot

• AbstractCardinalBallot

• AbstractCumulativeBallot

• AbstractOrdinalBallot

class AbstractBallot(name: str = '', meta: dict | None = None)

Bases: ABC, Collection[Project]

Abstract class representing the ballots, i.e., the information submitted by the voters. Essentially used for type-hint purposes.

Parameters:

• name (str, optional) – The identifier of the ballot. Defaults to “”.

• meta (dict, optional) – Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc. Defaults to dict().

name

The identifier of the ballot.

Type:

str

meta

Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc…

Type:

dict

class Ballot(name: str = '', meta: dict | None = None)

Bases: AbstractBallot

Abstract class representing the ballots, i.e., the information submitted by the voters.

Parameters:

• name (str, optional) – The identifier of the ballot. Defaults to “”.

• meta (dict, optional) – Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc. Defaults to dict().

name

The identifier of the ballot.

Type:

str

meta

Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc…

Type:

dict

abstract frozen() → FrozenBallot

Returns the ballot in its frozen form, that is, as a Frozen (hashable) ballot.

Returns:

The ballot in its frozen form.

Return type:

FrozenBallot

class FrozenBallot(name: str = '', meta: dict | None = None)

Bases: AbstractBallot, ABC

Abstract class representing frozen ballots, i.e., ballots that are hashable (and thus non-mutable). In general the Ballot class should be preferred over this one but hashable ballots can be useful (typically for MultiProfile).

Parameters:

• name (str, optional) – The identifier of the ballot. Defaults to “”.

• meta (dict, optional) – Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc. Defaults to dict().

name

The identifier of the ballot.

Type:

str

meta

Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc…

Type:

dict

class AbstractApprovalBallot(name: str = '', meta: dict | None = None)

Bases: AbstractBallot, ABC

Abstract class for approval ballots. Essentially used for typing purposes.

class ApprovalBallot(init: Collection[Project] = (), name: str | None = None, meta: dict | None = None)

Bases: set[Project], Ballot, AbstractApprovalBallot

An approval ballot, that is, a ballot in which the voter has indicated the projects that they approve of. It is a subclass of the Python class set and can be used as one.

Parameters:

• init (Iterable[Project], optional) – Collection of Project used to initialise the set. In case an AbstractBallot object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given). Defaults to ().

• name (str, optional) – The identifier of the ballot. Defaults to “”.

• meta (dict, optional) – Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc. Defaults to dict().

name

The identifier of the ballot.

Type:

str

meta

Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc.

Type:

dict

copy(*args)

Return a shallow copy of a set.

difference(*args)

Return the difference of two or more sets as a new set.

(i.e. all elements that are in this set but not the others.)

difference_update(*args)

Remove all elements of another set from this set.

frozen() → FrozenApprovalBallot

Returns the frozen approval ballot (that is hashable) corresponding to the ballot.

Returns:

The frozen approval ballot.

Return type:

FrozenApprovalBallot

intersection(*args)

Return the intersection of two sets as a new set.

(i.e. all elements that are in both sets.)

intersection_update(*args)

Update a set with the intersection of itself and another.

symmetric_difference(*args)

Return the symmetric difference of two sets as a new set.

(i.e. all elements that are in exactly one of the sets.)

symmetric_difference_update(*args)

Update a set with the symmetric difference of itself and another.

union(*args)

Return the union of sets as a new set.

(i.e. all elements that are in either set.)

get_random_approval_ballot(projects: Collection[Project], name: str = 'RandomAppBallot') → ApprovalBallot

Generates a random approval ballot in which each project is approved with probability 0.5.

Parameters:

• projects (Iterable[Project]) – A collection of projects.

• name (str, optional) – The identifier of the ballot. Defaults to “RandomAppBallot”.

Returns:

The randomly-generated approval ballot.

Return type:

ApprovalBallot

class FrozenApprovalBallot(approved: Collection[Project] = (), name: str = '', meta: dict | None = None)

Bases: tuple[Project], FrozenBallot, AbstractApprovalBallot

Frozen approval ballot, that is, a ballot in which the voter expressed their preferences by simply selecting some projects they approve of. It derives from the Python class tuple and can be used as one.

Parameters:

• init (Iterable[Project], optional) – Collection of Project used to initialise the tuple. In case an AbstractBallot object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given). Defaults to ().

• name (str, optional) – The identifier of the ballot. Defaults to “”.

• meta (dict, optional) – Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc. Defaults to dict().

name

The identifier of the ballot.

Type:

str

meta

Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc.

Type:

dict

class AbstractCardinalBallot(name: str = '', meta: dict | None = None)

Bases: AbstractBallot, ABC, Mapping[Project, int | float | mpq]

Abstract class for cardinal ballots. Essentially used for typing purposes.

class CardinalBallot(init: dict[Project, int | float | mpq] | None = None, name: str | None = None, meta: dict | None = None)

Bases: dict[Project, int | float | mpq], Ballot, AbstractCardinalBallot

A cardinal ballot, that is, a ballot in which the voter assigned scores to projects. This class inherits from the Python class dict and can be used as one.

Parameters:

• init (dict[Project], optional) – Dictionary of Project used to initialise the ballot. In case an AbstractBallot object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given). Defaults to ().

• name (str, optional) – The identifier of the ballot. Defaults to “”.

• meta (dict, optional) – Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc. Defaults to dict().

name

The identifier of the ballot.

Type:

str

meta

Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc.

Type:

dict

complete(projects: Collection[Project], default_score: int | float | mpq) → None

Completes the ballot by assigning the default_score to all projects from projects that have not been assigned a score yet.

Parameters:

• projects (Iterable[Project]) – The set of all the projects to consider. This is typically the instance.

• default_score (Numeric) – The default score that will be assigned.

copy() → a shallow copy of D

frozen() → FrozenCardinalBallot

Returns the frozen cardinal ballot (that is hashable) corresponding to the ballot.

Returns:

The frozen cardinal ballot.

Return type:

FrozenCardinalBallot

class FrozenCardinalBallot(init: dict[Project, int | float | mpq] = (), name: str | None = None, meta: dict | None = None)

Bases: dict[Project, int | float | mpq], FrozenBallot, AbstractCardinalBallot

Frozen cardinal ballot, that is, a ballot in which the voter assigned scores to projects. Since there is no frozen dictionary implemented in Python, this class simply inherits from the Python class dict, overriding the set_item method to ensure that it is non-mutable (raising an exception if the method is used).

Parameters:

• init (dict[Project], optional) – Dictionary of Project used to initialise the ballot. In case an AbstractBallot object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given). Defaults to ().

• name (str, optional) – The identifier of the ballot. Defaults to “”.

• meta (dict, optional) – Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc. Defaults to dict().

name

The identifier of the ballot.

Type:

str

meta

Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc.

Type:

dict

class AbstractCumulativeBallot(name: str = '', meta: dict | None = None)

Bases: AbstractCardinalBallot, ABC

Abstract class for cumulative ballots. Essentially used for typing purposes.

class CumulativeBallot(init: dict[Project, int | float | mpq] | None = None, name: str | None = None, meta: dict | None = None)

Bases: CardinalBallot, AbstractCumulativeBallot

Cumulative ballot, that is, a ballot in which the voter distributes a given amount of points to the projects. This is a special type of cardinal ballot (see CardinalBallot).This class inherits from the Python class dict and can be used as one.

Parameters:

• init (dict[Project], optional) – Dictionary of Project used to initialise the ballot. In case an AbstractBallot object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given). Defaults to ().

• name (str, optional) – The identifier of the ballot. Defaults to “”.

• meta (dict, optional) – Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc. Defaults to dict().

name

The identifier of the ballot.

Type:

str

meta

Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc.

Type:

dict

copy() → a shallow copy of D

frozen() → FrozenCumulativeBallot

Returns the frozen cumulative ballot (that is hashable) corresponding to the ballot.

Returns:

The frozen cardinal ballot.

Return type:

FrozenCumulativeBallot

class FrozenCumulativeBallot(init: dict[Project, int | float | mpq] | None = None, name: str | None = None, meta: dict | None = None)

Bases: dict[Project, int | float | mpq], FrozenBallot, AbstractCumulativeBallot

Frozen cumulative ballot, that is, a ballot in which the voter distributes a given amount of points to the projects. This is a special type of cardinal ballot (see CardinalBallot). Since there is no frozen dictionary implemented in Python, this class simply inherits from the Python class dict, overriding the set_item method to ensure that it is non-mutable (raising an exception if the method is used).

Parameters:

• init (dict[Project], optional) – Dictionary of Project used to initialise the ballot. In case an AbstractBallot object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given). Defaults to ().

• name (str, optional) – The identifier of the ballot. Defaults to “”.

• meta (dict, optional) – Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc. Defaults to dict().

name

The identifier of the ballot.

Type:

str

meta

Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc.

Type:

dict

class AbstractOrdinalBallot(name: str = '', meta: dict | None = None)

Bases: AbstractBallot, ABC, Collection[Project]

Abstract class for cumulative ballots. Essentially used for typing purposes.

abstract position(project: Project) → int

Returns the position of a project in the ordinal ballot.

Parameters:

project (Project) – The project.

Returns:

The position of the project.

Return type:

int

class OrdinalBallot(init: Collection[Project] = (), name: str | None = None, meta: dict | None = None)

Bases: dict, Ballot, AbstractOrdinalBallot

Ordinal ballot, that is, a ballot in which the voter has ordered some projects according to their preferences. It behaves as an ordered set (implemented using Python dict for technical reasons). The convention is that the elements are presented from the most preferred one to the least preferred one.

Parameters:

• init (Iterable[Project], optional) – Collection of Project used to initialise the ballot. In case an AbstractBallot object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given). Defaults to ().

• name (str, optional) – The identifier of the ballot. Defaults to “”.

• meta (dict, optional) – Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc. Defaults to dict().

name

The identifier of the ballot.

Type:

str

meta

Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc.

Type:

dict

append(project: Project) → None

Appends a project to the order. If the project is already present, its position does not change.

Parameters:

project (Project) – The project to append.

at_index(index: int) → Project

Returns the project at index index. A ValueError is raised if the index is invalid.

Parameters:

index (int) – The index.

Returns:

The project at position index.

Return type:

Project

copy() → a shallow copy of D

frozen() → FrozenOrdinalBallot

Returns the frozen ordinal ballot (that is hashable) corresponding to the ballot.

Returns:

The frozen ordinal ballot.

Return type:

FrozenOrdinalBallot

index(project: Project) → int

Returns the index of the project given as argument by looping through all the projects until finding it. If the required project is not found, a ValueError is raised.

Parameters:

project (Project) – The project to append.

Returns:

The index of the project in the order.

Return type:

int

position(project: Project) → int

Returns the position of a project in the ordinal ballot.

Parameters:

project (Project) – The project.

Returns:

The position of the project.

Return type:

int

class FrozenOrdinalBallot(iterable: Collection[Project] = (), name: str = '', meta: dict | None = None)

Bases: tuple[Project], FrozenBallot, AbstractOrdinalBallot

Frozen ordinal ballot, that is, a ballot in which the voter has ordered some projects according to their preferences. It derives from the Python class tuple and can be used as one.

Parameters:

• init (Iterable[Project], optional) – Collection of Project used to initialise the tuple. In case an AbstractBallot object is passed, the additional attributes are also copied (except if the corresponding keyword arguments have been given). Defaults to ().

• name (str, optional) – The identifier of the ballot. Defaults to “”.

• meta (dict, optional) – Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc. Defaults to dict().

name

The identifier of the ballot.

Type:

str

meta

Additional information concerning the ballot, stored in a dictionary. Keys and values are typically strings. Could for instance store the gender of the voter, their location etc.

Type:

dict

position(project: Project) → int

Returns the position of a project in the ordinal ballot.

Parameters:

project (Project) – The project.

Returns:

The position of the project.

Return type:

int