marks.BallotMarks¶

class marks.BallotMarks(marks: List = [])¶

Bases: object

Wrap up ranking list of a ballot with useful methods.

__init__(marks: List = []) → None¶

Constructor

Parameters:: marks (List, optional) – List of mark names, including candidates and special marks, representing ranked choices on a ballot. Defaults to empty list.

Methods

`__init__`([marks])	Constructor
`apply_rules`([combine_writein_marks, ...])	Applies rules to ballot, modifying marks as necessary.
`check_writein_match`(candidate_name)	Returns true if the mark name matches partial or exact writein matching rules.
`clear_rules`()	Put object back to its init state.
`combine_writein_marks`(ballot_marks)	Return copied BallotMarks object with any ballot marks that meet writein match criteria changed into WRITEIN constant.
`copy`()	Make a copy.
`get_marks`()
`get_unique_candidates`()
`get_unique_marks`()
`new_rule_set`([combine_writein_marks, ...])	A constructor of sorts.
`remove_duplicate_candidate_marks`(ballot_marks)	Return copied BallotMarks object with duplicated candidate marks removed, including WRITEIN constant.
`remove_mark`(ballot_marks, remove_mark_names)	Return a copied BallotMarks object with any ballot marks present in remove_mark_names removed.
`update_marks`(new_marks)	Update marks property along with unique_marks and unique_candidates based on a new list of marks names.

Attributes

`MAYBE_EXHAUSTED`
`MAYBE_EXHAUSTED_BY_DUPLICATE_RANKING`
`MAYBE_EXHAUSTED_BY_OVERVOTE`
`MAYBE_EXHAUSTED_BY_SKIPPED_RANKING`
`NOT_EXHAUSTED`
`OVERVOTE`
`POSTTALLY_EXHAUSTED_BY_ABSTENTION`
`POSTTALLY_EXHAUSTED_BY_DUPLICATE_RANKING`
`POSTTALLY_EXHAUSTED_BY_OVERVOTE`
`POSTTALLY_EXHAUSTED_BY_RANK_LIMIT`
`POSTTALLY_EXHAUSTED_BY_SKIPPED_RANKING`
`PRETALLY_EXHAUST`
`SKIPPED`
`UNDERVOTE`
`WRITEIN`
`writein_anycase_exact_match_words`
`writein_partial_match_words`

apply_rules(combine_writein_marks: bool = False, exclude_writein_marks: bool = False, exclude_duplicate_candidate_marks: bool = False, exclude_overvote_marks: bool = False, exclude_skipped_marks: bool = False, treat_combined_writeins_as_exhaustable_duplicates: bool = False, exhaust_on_duplicate_candidate_marks: bool = False, exhaust_on_overvote_marks: bool = False, exhaust_on_N_repeated_skipped_marks: int = 0, writeins_eliminated_first: bool = False) → None¶

Applies rules to ballot, modifying marks as necessary.

Parameters:

combine_writein_marks (bool, optional) – If True, any marks which are guessed to be a write-in candidate are replaced with the constant BallotMarks.WRITEIN, defaults to False
exclude_writein_marks (bool, optional) – If True, all BallotMarks.WRITEIN marks are removed, defaults to False
exclude_duplicate_candidate_marks (bool, optional) – If True, duplicated candidate marks are removed, defaults to False
exclude_overvote_marks (bool, optional) – If True, BallotMarks.OVERVOTE marks are removed, defaults to False
exclude_skipped_marks (bool, optional) – If True, BallotMarks.SKIPPED marks are removed, defaults to False
treat_combined_writeins_as_exhaustable_duplicates (bool, optional) – If True and combine_writein_marks is True, duplicate writein marks are considered after they have been combined, defaults to False
exhaust_on_duplicate_candidate_marks (bool, optional) – If True, ballot is truncated following a duplicated candidate mark, defaults to False
exhaust_on_overvote_marks (bool, optional) – If True, ballot is truncated following a BallotMarks.OVERVOTE mark, defaults to False, defaults to False
exhaust_on_N_repeated_skipped_marks (bool, optional) – If > 0, ballot is truncated following at least N BallotMarks.SKIPPED marks which are followed by a non-skipped mark, defaults to 0

Raises:

RuntimeError – Raised if rules already applied to this object. To apply fresh rules, first execute the clean_rules method.

static check_writein_match(candidate_name: str) → bool¶

Returns true if the mark name matches partial or exact writein matching rules. Exact matching strings specified in BallotMarks.writein_anycase_exact_match_words. Partial matching strings specified in BallotMarks.writein_partial_match_words.

Parameters:: mark (str) – mark name to be checked for writein match
Returns:: True if mark name is a match to writein conditions, else False.
Return type:: bool

clear_rules()¶: Put object back to its init state.

static combine_writein_marks(ballot_marks: BallotMarks) → BallotMarks¶

Return copied BallotMarks object with any ballot marks that meet writein match criteria changed into WRITEIN constant.

Parameters:: ballot_marks (BallotMarks) – BallotMarks object to copy and combine the writein marks of.
Returns:: Copied BallotMarks object with matching marks converted to writein constant.
Return type:: BallotMarks

copy() → BallotMarks¶

Make a copy.

Returns:: Returns a copy of BallotMarks object
Return type:: BallotMarks

get_marks() → List¶

Returns:: List of current marks
Return type:: List

get_unique_candidates() → Set¶

Returns:: Set of unique candidate marks
Return type:: Set

get_unique_marks() → Set¶

Returns:: Set of unique marks
Return type:: Set

static new_rule_set(combine_writein_marks: bool = False, exclude_writein_marks: bool = False, exclude_duplicate_candidate_marks: bool = False, exclude_overvote_marks: bool = False, exclude_skipped_marks: bool = False, treat_combined_writeins_as_exhaustable_duplicates: bool = False, exhaust_on_duplicate_candidate_marks: bool = False, exhaust_on_overvote_marks: bool = False, exhaust_on_N_repeated_skipped_marks: int = 0, writeins_eliminated_first: bool = False) → Dict¶

A constructor of sorts. Returns passed and default parameters as a dictionary.

Parameters:

combine_writein_marks (bool, optional) – combine writein marks that match writein patterns, defaults to False
exclude_writein_marks (bool, optional) – treat writein marks, defaults to False
exclude_duplicate_candidate_marks (bool, optional) – [description], defaults to False
exclude_overvote_marks (bool, optional) – [description], defaults to False
exclude_skipped_marks (bool, optional) – [description], defaults to False
treat_combined_writeins_as_exhaustable_duplicates (bool, optional) – [description], defaults to False
exhaust_on_duplicate_candidate_marks (bool, optional) – [description], defaults to False
exhaust_on_overvote_marks (bool, optional) – [description], defaults to False
exhaust_on_N_repeated_skipped_marks (int, optional) – Number of consecutive skip marks which cause exhaustion, defaults to 0

Returns:

[description]

Return type:

Dict

static remove_duplicate_candidate_marks(ballot_marks: BallotMarks) → BallotMarks¶

Return copied BallotMarks object with duplicated candidate marks removed, including WRITEIN constant.

Parameters:: ballot_marks (BallotMarks) – Object to copy and from which to remove duplicates.
Returns:: Copied object with duplicate candidates removed.
Return type:: BallotMarks

static remove_mark(ballot_marks: BallotMarks, remove_mark_names: List | Set) → BallotMarks¶

Return a copied BallotMarks object with any ballot marks present in remove_mark_names removed.

Parameters:

ballot_marks (BallotMarks) – Object to copy and remove marks from.
remove_mark_names (List or Set) – List or Set of mark names to be removed.

Returns:

Copied object with specified marks removed.

Return type:

BallotMarks

update_marks(new_marks: List[str]) → None¶

Update marks property along with unique_marks and unique_candidates based on a new list of marks names.

Parameters:: new_marks (List) – List of new ordered mark names to replace old ones.