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: StrEnum

What an Actant is.

HUMAN = 'human'

A human member.

AGENT = 'agent'

A software agent.

OTHER = 'other'

Anything else.

class civiqhub.values.AmendmentStatus(*values)[source]

Bases: StrEnum

Where an Amendment stands.

There is no draft status. Like any unknown value, AmendmentStatus("draft") raises ValueError. A dataset reads the deprecated status DRAFT of an old row as OPEN, and marks it with a DeprecatedValue.

OPEN = 'open'

Not decided yet.

ADOPTED = 'adopted'

Adopted.

REJECTED = 'rejected'

Rejected.

class civiqhub.values.DeprecatedValue(*, section, index, row_id, key, value)[source]

Bases: object

A value of an old dataset that the model no longer has, read and marked.

The Articles model deprecated the status DRAFT of an Amendment, the types CREATE and REMOVE, the pending changes PENDING_CREATE and PENDING_REMOVE, the kind SYNC of 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 a DeprecatedValue, in Dataset.deprecated and on the Project or the Proposal that the row describes.

These are the values that a dataset marks, in any case:

  • in projects: any parent_project_id, the Project that this one was forked from;

  • in proposals: any parent_root_id, the Proposal that this one derives from;

  • in amendments: the status DRAFT, the type CREATE or REMOVE, the change_type CREATE or REMOVE, the item_type PENDING_CREATE or PENDING_REMOVE, the kind SYNC, and any originating_project_id.

The SDK never produces one of these values. A dataset keeps its rows as the source gave them, so Dataset.save writes 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: StrEnum

The 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: object

How 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 None when the source does not say.

  • n_voters (int | None) – The number of Actants who voted, or None when the source does not say.

property turnout: float | None

The share of the Actants who voted: n_voters / n_actants.

None when either number is missing, or when there is no Actant.

class civiqhub.values.Position(*values)[source]

Bases: StrEnum

The side that an Argument takes.

PRO = 'pro'

For.

CON = 'con'

Against.

NEUTRAL = 'neutral'

Neither for nor against.

class civiqhub.values.Role(*values)[source]

Bases: IntEnum

The 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.

PARTICIPANT = 2

Above READER.

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, and dict(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 at SCORES[k].

classmethod from_scores(scores)[source]

Count the votes of a sequence of scores.

A score outside SCORES raises ValidationError.

Parameters:

scores (Iterable[int]) – One score per vote.

Return type:

VoteCounts

property total: int

The number of votes.

property shares: tuple[float, ...]

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: StrEnum

Where 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.