Source code for civiqhub.values

# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at https://mozilla.org/MPL/2.0/.

"""The small values that the objects of a Project carry.

The closed choices of the product are enumerations: :class:`Exposure`, :class:`Role`,
:class:`ActantKind`, :class:`AmendmentStatus`, :class:`Position` and :class:`VoteState`.
:class:`VoteCounts` holds the five vote counts of a Revision, and :class:`Participation`
the counts of a Project. :class:`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.
"""

from collections.abc import Iterable, Iterator, Mapping
from dataclasses import dataclass, fields
from enum import IntEnum, StrEnum

from .errors import ValidationError

__all__ = [
    "SCORES",
    "ActantKind",
    "AmendmentStatus",
    "DeprecatedValue",
    "Exposure",
    "Participation",
    "Position",
    "Role",
    "VoteCounts",
    "VoteState",
]

#: The scores a vote can take, from -2 to +2.
SCORES = (-2, -1, 0, 1, 2)


[docs] class Exposure(StrEnum): """The level of detail that a dataset holds.""" #: Vote counts per Revision and participation; nothing about who voted. AGGREGATED = "aggregated" #: One row per vote; an Actant is known by a pseudonym only. PSEUDONYMISED = "pseudonymised"
[docs] class Role(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``. """ #: The lowest role. READER = 1 #: Above :attr:`READER`. PARTICIPANT = 2 #: Above :attr:`PARTICIPANT`. REPRESENTATIVE = 3 #: Above :attr:`REPRESENTATIVE`. MODERATOR = 4 #: The highest role. ADMINISTRATOR = 5
[docs] class ActantKind(StrEnum): """What an Actant is.""" #: A human member. HUMAN = "human" #: A software agent. AGENT = "agent" #: Anything else. OTHER = "other"
[docs] class AmendmentStatus(StrEnum): """Where an Amendment stands. There is no draft status. Like any unknown value, ``AmendmentStatus("draft")`` raises :class:`ValueError`. A dataset reads the deprecated status ``DRAFT`` of an old row as :attr:`OPEN`, and marks it with a :class:`DeprecatedValue`. """ #: Not decided yet. OPEN = "open" #: Adopted. ADOPTED = "adopted" #: Rejected. REJECTED = "rejected"
[docs] class Position(StrEnum): """The side that an Argument takes.""" #: For. PRO = "pro" #: Against. CON = "con" #: Neither for nor against. NEUTRAL = "neutral"
[docs] class VoteState(StrEnum): """Where an Actant stands with a Revision. A missing vote is never a zero, nor a neutral vote. """ #: The Actant voted. VOTED = "voted" #: The Revision was shown to the Actant, who did not vote. ABSTAINED = "abstained" #: The Revision was not shown to the Actant. NOT_SHOWN = "not_shown" #: The Actant did not vote, and the dataset does not record what was shown. UNKNOWN = "unknown"
[docs] @dataclass(frozen=True, kw_only=True) class DeprecatedValue: """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 :attr:`Dataset.deprecated <civiqhub.dataset.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 :meth:`Dataset.save <civiqhub.dataset.Dataset.save>` writes back what it read, and adds none. Args: section: The section of the row, such as ``"amendments"``. index: The position of the row in its section, from 0. row_id: The id of the row. key: The key of the value in the row. value: The value, as the row gives it. """ section: str index: int row_id: str key: str value: str def __str__(self) -> str: return ( f"{self.section}[{self.index}] (id {self.row_id!r}): the {self.key} " f"{self.value!r} is deprecated" )
def _is_count(value: object) -> bool: return isinstance(value, int) and not isinstance(value, bool) and value >= 0 def _is_score(value: object) -> bool: return isinstance(value, int) and not isinstance(value, bool) and value in SCORES def _signed(score: int) -> str: return f"{score:+d}" if score else "0"
[docs] @dataclass(frozen=True, repr=False) class VoteCounts(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 :class:`~civiqhub.errors.ValidationError`. Args: counts: The number of votes at each score, in the order of :data:`SCORES`: ``counts[k]`` is the number of votes at ``SCORES[k]``. """ counts: tuple[int, int, int, int, int] = (0, 0, 0, 0, 0) def __post_init__(self) -> None: counts: object = self.counts if not ( isinstance(counts, tuple) and len(counts) == len(SCORES) and all(_is_count(count) for count in counts) ): raise ValidationError( "Vote counts are five non-negative integers, from score -2 to score +2; " f"got {counts!r}." )
[docs] @classmethod def from_scores(cls, scores: Iterable[int]) -> "VoteCounts": """Count the votes of a sequence of scores. A score outside :data:`SCORES` raises :class:`~civiqhub.errors.ValidationError`. Args: scores: One score per vote. """ counts = [0] * len(SCORES) for score in scores: if not _is_score(score): raise ValidationError(f"A score is an integer from -2 to +2; got {score!r}.") counts[SCORES.index(score)] += 1 return cls((counts[0], counts[1], counts[2], counts[3], counts[4]))
def __getitem__(self, score: int) -> int: if not _is_score(score): raise KeyError(score) return self.counts[SCORES.index(score)] def __iter__(self) -> Iterator[int]: return iter(SCORES) def __len__(self) -> int: return len(SCORES) @property def total(self) -> int: """The number of votes.""" return sum(self.counts) @property def shares(self) -> tuple[float, ...]: """The share of the votes at each score, in the order of :data:`SCORES`. Five zeros when nobody voted. """ total = self.total return tuple(count / total if total else 0.0 for count in self.counts) def __repr__(self) -> str: cells = ", ".join(f"{_signed(score)}: {count}" for score, count in self.items()) return f"{type(self).__name__}({cells})"
[docs] @dataclass(frozen=True, kw_only=True) class Participation: """How much a Project is used, in counts. Every field is given by keyword. A negative count raises :class:`~civiqhub.errors.ValidationError`. Args: n_proposals: The number of Proposals. n_amendments: The number of Amendments. n_arguments: The number of Arguments. n_votes: The number of Votes. n_actants: The number of Actants, or ``None`` when the source does not say. n_voters: The number of Actants who voted, or ``None`` when the source does not say. """ n_proposals: int n_amendments: int n_arguments: int n_votes: int n_actants: int | None n_voters: int | None def __post_init__(self) -> None: for field in fields(self): value = getattr(self, field.name) if value is None and field.name in ("n_actants", "n_voters"): continue if not _is_count(value): raise ValidationError( f"Participation counts are integers, zero or more; got {field.name}={value!r}." ) @property def turnout(self) -> 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. """ if self.n_voters is None or not self.n_actants: return None return self.n_voters / self.n_actants