civiqhub.values¶
The small values that the objects of a Project carry.
The closed choices of the product are enumerations: Exposure, Role,
ActantKind, AmendmentStatus, Position and VoteState.
VoteCounts holds the five vote counts of a Revision, and Participation
the counts of a Project. DeprecatedValue marks a value of an old dataset that the
model no longer has.
Every value is frozen and hashable. The counts are raw: no mean, no entropy and no consensus label is computed from them.
- civiqhub.values.SCORES = (-2, -1, 0, 1, 2)¶
The scores a vote can take, from -2 to +2.
- class civiqhub.values.ActantKind(*values)[source]¶
Bases:
StrEnumWhat an Actant is.
- HUMAN = 'human'¶
A human member.
- AGENT = 'agent'¶
A software agent.
- OTHER = 'other'¶
Anything else.
- class civiqhub.values.AmendmentStatus(*values)[source]¶
Bases:
StrEnumWhere an Amendment stands.
There is no draft status. Like any unknown value,
AmendmentStatus("draft")raisesValueError. A dataset reads the deprecated statusDRAFTof an old row asOPEN, and marks it with aDeprecatedValue.- OPEN = 'open'¶
Not decided yet.
- ADOPTED = 'adopted'¶
Adopted.
- REJECTED = 'rejected'¶
Rejected.
- class civiqhub.values.DeprecatedValue(*, section, index, row_id, key, value)[source]¶
Bases:
objectA value of an old dataset that the model no longer has, read and marked.
The Articles model deprecated the status
DRAFTof an Amendment, the typesCREATEandREMOVE, the pending changesPENDING_CREATEandPENDING_REMOVE, the kindSYNCof the cascades, and the traces of forks and uplinks. The server no longer writes them, but old datasets and snapshots still hold them. A dataset reads them without failing and marks each one with aDeprecatedValue, inDataset.deprecatedand on the Project or the Proposal that the row describes.These are the values that a dataset marks, in any case:
in
projects: anyparent_project_id, the Project that this one was forked from;in
proposals: anyparent_root_id, the Proposal that this one derives from;in
amendments: thestatusDRAFT, thetypeCREATEorREMOVE, thechange_typeCREATEorREMOVE, theitem_typePENDING_CREATEorPENDING_REMOVE, thekindSYNC, and anyoriginating_project_id.
The SDK never produces one of these values. A dataset keeps its rows as the source gave them, so
Dataset.savewrites back what it read, and adds none.- Parameters:
section (str) – The section of the row, such as
"amendments".index (int) – The position of the row in its section, from 0.
row_id (str) – The id of the row.
key (str) – The key of the value in the row.
value (str) – The value, as the row gives it.
- class civiqhub.values.Exposure(*values)[source]¶
Bases:
StrEnumThe level of detail that a dataset holds.
- AGGREGATED = 'aggregated'¶
Vote counts per Revision and participation; nothing about who voted.
- PSEUDONYMISED = 'pseudonymised'¶
One row per vote; an Actant is known by a pseudonym only.
- class civiqhub.values.Participation(*, n_proposals, n_amendments, n_arguments, n_votes, n_actants, n_voters)[source]¶
Bases:
objectHow much a Project is used, in counts.
Every field is given by keyword. A negative count raises
ValidationError.- Parameters:
n_proposals (int) – The number of Proposals.
n_amendments (int) – The number of Amendments.
n_arguments (int) – The number of Arguments.
n_votes (int) – The number of Votes.
n_actants (int | None) – The number of Actants, or
Nonewhen the source does not say.n_voters (int | None) – The number of Actants who voted, or
Nonewhen the source does not say.
- property turnout: float | None¶
The share of the Actants who voted:
n_voters / n_actants.Nonewhen either number is missing, or when there is no Actant.
- class civiqhub.values.Position(*values)[source]¶
Bases:
StrEnumThe side that an Argument takes.
- PRO = 'pro'¶
For.
- CON = 'con'¶
Against.
- NEUTRAL = 'neutral'¶
Neither for nor against.
- class civiqhub.values.Role(*values)[source]¶
Bases:
IntEnumThe roles in a Group or a Project, from the lowest to the highest.
A higher role includes the lower ones, so roles compare:
Role.MODERATOR > Role.PARTICIPANT.- READER = 1¶
The lowest role.
- REPRESENTATIVE = 3¶
Above
PARTICIPANT.
- MODERATOR = 4¶
Above
REPRESENTATIVE.
- ADMINISTRATOR = 5¶
The highest role.
- class civiqhub.values.VoteCounts(counts=(0, 0, 0, 0, 0))[source]¶
Bases:
Mapping[int,int]The five vote counts of a Revision, from score -2 to score +2.
It reads as a mapping from each score to its number of votes:
vote_counts[2]is the number of votes at +2, anddict(vote_counts)gives the five counts. It holds counts and no other statistic. Zero everywhere means that nobody voted.Five counts that are not non-negative integers raise
ValidationError.- Parameters:
counts (tuple[int, int, int, int, int]) – The number of votes at each score, in the order of
SCORES:counts[k]is the number of votes atSCORES[k].
- classmethod from_scores(scores)[source]¶
Count the votes of a sequence of scores.
A score outside
SCORESraisesValidationError.- Parameters:
scores (Iterable[int]) – One score per vote.
- Return type:
- property total: int¶
The number of votes.
The share of the votes at each score, in the order of
SCORES.Five zeros when nobody voted.
- class civiqhub.values.VoteState(*values)[source]¶
Bases:
StrEnumWhere an Actant stands with a Revision.
A missing vote is never a zero, nor a neutral vote.
- VOTED = 'voted'¶
The Actant voted.
- ABSTAINED = 'abstained'¶
The Revision was shown to the Actant, who did not vote.
- NOT_SHOWN = 'not_shown'¶
The Revision was not shown to the Actant.
- UNKNOWN = 'unknown'¶
The Actant did not vote, and the dataset does not record what was shown.