Source code for civiqhub.entities

# 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 objects of the product.

:class:`Entity` is what every object of the product shares: a frozen value, known by its
id, tied to the :class:`~civiqhub.dataset.Dataset` it comes from. :class:`Group`,
:class:`Project`, :class:`Article` (with its :class:`ArticleVersion`, its
:class:`Paragraph`, the :class:`Placement` of its Proposals and its :class:`Citation` of
other Proposals), :class:`Proposal`,
:class:`Amendment`, :class:`Revision`, :class:`Argument`, :class:`Actant` (with
:class:`Member` and :class:`Agent`) and :class:`Vote` are the objects of the product.

Actants and votes exist only in a pseudonymised dataset. In an aggregated one, reading
them raises :class:`~civiqhub.errors.ExposureError`.
"""

from collections.abc import Iterator
from dataclasses import dataclass, field
from typing import TYPE_CHECKING, ClassVar

from .listing import Listing
from .values import (
    ActantKind,
    AmendmentStatus,
    DeprecatedValue,
    Exposure,
    Participation,
    Position,
    Role,
    VoteCounts,
    VoteState,
)

if TYPE_CHECKING:
    from .dataset import Dataset

__all__ = [
    "Actant",
    "Agent",
    "Amendment",
    "Argument",
    "Article",
    "ArticleVersion",
    "Citation",
    "Entity",
    "Group",
    "Member",
    "Paragraph",
    "Placement",
    "Project",
    "Proposal",
    "Revision",
    "Vote",
]


[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class Entity: """An object of the product: frozen, known by its id, tied to its dataset. Two entities are equal when they are of the same class exactly, have the same id and come from the same dataset object. Two loads of the same Project therefore give entities that differ: to compare contents, compare the fingerprints of the datasets. An entity keeps only the ids of the entities it links to. These entities are read through properties that query its dataset. A subclass is declared with ``@dataclass(frozen=True, kw_only=True, eq=False, repr=False)``, so that it keeps the equality, the hash and the representation defined here. Args: id: The id of the entity. dataset: The dataset that the entity comes from. It is not shown by ``repr``. """ id: str dataset: "Dataset" = field(repr=False) #: The name of the entity in messages, such as ``"proposal"``. noun: ClassVar[str] = "entity" def __eq__(self, other: object) -> bool: if not isinstance(other, Entity): return NotImplemented return type(self) is type(other) and self.id == other.id and self.dataset is other.dataset def __hash__(self) -> int: return hash((type(self).__name__, self.id))
[docs] def _label(self) -> str: """Return a short readable label, which ``repr`` shows after the id. It is empty here. A subclass overrides it, for instance to return the name of a Project. """ return ""
def __repr__(self) -> str: label = self._label() shown = f"{self.id!r}, {label!r}" if label else repr(self.id) return f"{type(self).__name__}({shown})"
[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class Group(Entity): """A community on CiviqHub. It holds Groups and Projects. ``repr`` shows its id and its name, such as ``Group('g-1', 'Demo collective')``. Args: id: The id of the Group. dataset: The dataset that the Group comes from. slug: The short name of the Group in addresses, unique in its dataset. name: The name of the Group. description: The description of the Group. parent_id: The id of the Group that holds this one, or ``None`` at the top. """ slug: str name: str = "" description: str = "" parent_id: str | None = None #: The name of a Group in messages. noun: ClassVar[str] = "group" def _label(self) -> str: return self.name @property def parent(self) -> "Group | None": """The Group that holds this one, or ``None`` at the top.""" return None if self.parent_id is None else self.dataset.groups[self.parent_id] @property def groups(self) -> Listing["Group"]: """The Groups that this Group holds directly, in the order of the rows.""" return self.dataset._groups_in(self.id) @property def projects(self) -> "Listing[Project]": """The Projects of this Group, in the order of the rows.""" return self.dataset._projects_in(self.id)
[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class Project(Entity): """A Project of a Group: the set of its articles and of their versions. Every proposal of a Project has a parent article. :attr:`articles` gives the articles in the order of the Project. ``repr`` shows its id and its name, such as ``Project('budget-2027', 'Budget participatif')``. Args: id: The id of the Project. dataset: The dataset that the Project comes from. slug: The short name of the Project in addresses, unique in its dataset. name: The name of the Project. description: The description of the Project. group_id: The id of the Group of the Project, or ``None`` when the data does not say. """ slug: str name: str = "" description: str = "" group_id: str | None = None #: The name of a Project in messages. noun: ClassVar[str] = "project" def _label(self) -> str: return self.name @property def group(self) -> Group | None: """The Group of the Project, or ``None`` when the data does not say.""" return None if self.group_id is None else self.dataset.groups[self.group_id] @property def as_of(self) -> str: """The instant that the data describes, the one of the dataset.""" return self.dataset.as_of @property def exposure(self) -> Exposure: """The level of detail of the data, the one of the dataset.""" return self.dataset.exposure @property def participation(self) -> Participation: """The counts of what happened in the Project, as the source gave them.""" return self.dataset._participation_of(self.id) @property def articles(self) -> "Listing[Article]": """The articles of the Project, in the order of their positions. The order is the one the source gives in the key ``position`` of the rows: the same rows give the same order, load after load. """ return self.dataset._articles_in(self.id) @property def citations(self) -> "Listing[Citation]": """The citations made in the version in force of each article of the Project. They come by article, in the order of the positions, then in the order of the text. """ return Listing(citation for article in self.articles for citation in article.citations)
[docs] def to_citation_edges(self) -> list[tuple[str, str]]: """Return the graph of the citations of the Project as a list of edges. Each edge is ``(article id, proposal id)``: the article cites the Proposal in its version in force. The ids are opaque strings, and no object of the SDK is in the list, so that a graph library reads it as it is. The edges come in the order of :attr:`citations`. """ return [(citation.article_id, citation.proposal_id) for citation in self.citations]
@property def deprecated(self) -> tuple[DeprecatedValue, ...]: """The deprecated values read in the row of the Project, such as the trace of a fork. It is empty for a Project of the current model. See :class:`~civiqhub.values.DeprecatedValue`. """ return self.dataset._deprecated_of("project", self.id) @property def proposals(self) -> "Listing[Proposal]": """The Proposals of the Project that are not Amendments, in the order of the rows.""" return self.dataset._proposals_in(self.id) @property def revisions(self) -> "Listing[Revision]": """The Revisions of every Proposal of the Project, Amendments included. They come by Proposal, in the order of the rows, then by number. """ return self.dataset._revisions_in(self.id) @property def amendments(self) -> "Listing[Amendment]": """The Amendments of the Project, in the order of the rows.""" return self.dataset._amendments_in(self.id) @property def arguments(self) -> "Listing[Argument]": """The Arguments on the Proposals of the Project, Amendments included. They come by Proposal, in the order of the rows, each Proposal with its Arguments in depth-first order. """ return self.dataset._arguments_in(self.id) @property def actants(self) -> "Listing[Actant]": """The Actants of the dataset, in the order of the rows. A row of actants names no Project: these are all the Actants that the source gave. Raises: ExposureError: The dataset is aggregated. """ self.dataset.require_individual_votes("project.actants") return self.dataset.actants @property def votes(self) -> "Listing[Vote]": """The votes on the Revisions of the Project, Amendments included. Raises: ExposureError: The dataset is aggregated. """ self.dataset.require_individual_votes("project.votes") return self.dataset._votes_in(self.id)
[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class Article(Entity): """An article of a Project: a text in numbered versions, which Proposals belong to. A Project is the set of its articles and of their versions. An article keeps every version it had; :attr:`current_version` is the one in force. ``repr`` shows its id and its title, such as ``Article('art-1', 'Green spaces')``. Args: id: The id of the article. dataset: The dataset that the article comes from. project_id: The id of the Project of the article. position: The place of the article in its Project, from 1, unique within the Project. title: The title of the article. description: The description of the article. current_version_number: The number of the version in force. published_at: When the version in force was published, in ISO 8601, or ``None``. """ project_id: str position: int = 1 title: str = "" description: str = "" current_version_number: int = 1 published_at: str | None = None #: The name of an article in messages. noun: ClassVar[str] = "article" def _label(self) -> str: return self.title @property def project(self) -> Project: """The Project of the article.""" return self.dataset.projects[self.project_id] @property def versions(self) -> "Listing[ArticleVersion]": """Every version of the article, by number.""" return self.dataset._versions_of(self.id) @property def current_version(self) -> "ArticleVersion": """The version in force, the one numbered ``current_version_number``.""" return self.dataset._current_version_of(self.id) @property def paragraphs(self) -> "Listing[Paragraph]": """The top of the tree of paragraphs of the version in force. These are the paragraphs that no other holds, in the order of the text. Each one gives its :attr:`~Paragraph.children`. :meth:`walk_paragraphs` gives them all. """ return self.current_version.paragraphs
[docs] def walk_paragraphs(self) -> "Iterator[Paragraph]": """Walk every paragraph of the version in force, in the order of the text. It is the tree read depth first: each paragraph, then the paragraphs it holds. """ return self.current_version.walk_paragraphs()
@property def proposals(self) -> "Listing[Proposal]": """The Proposals placed in the version in force, in the order of the text. A Proposal outside any paragraph comes first; then the Proposals of each paragraph, in the order of the text and of their ranks. """ return self.current_version.proposals @property def citations(self) -> "Listing[Citation]": """The citations made in the version in force, in the order of the text.""" return self.current_version.citations
[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class ArticleVersion(Entity): """One numbered version of an article, frozen as it was published. A version never changes: a new text is a new version. The rows of versions carry no id of their own, so the id of a version is the id of its article and its number, such as ``art-1.v3``. ``repr`` shows its id and its number, such as ``ArticleVersion('art-1.v3', 'v3')``. Args: id: The id of the version. dataset: The dataset that the version comes from. article_id: The id of the article of the version. number: The number of the version, from 1, unique within its article. title: The title of the article in this version. body: The text of the article in this version. published_at: When the version was published, in ISO 8601, or ``None``. """ article_id: str number: int = 1 title: str = "" body: str = "" published_at: str | None = None #: The name of an article version in messages. noun: ClassVar[str] = "article version" def _label(self) -> str: return f"v{self.number}" @property def article(self) -> Article: """The article of the version.""" return self.dataset.articles[self.article_id] @property def is_current(self) -> bool: """Whether the version is the one in force for its article.""" return self.dataset._current_version_of(self.article_id) is self @property def paragraphs(self) -> "Listing[Paragraph]": """The top of the tree of paragraphs of the version, in the order of the text.""" return self.dataset._top_paragraphs_of(self.id)
[docs] def walk_paragraphs(self) -> "Iterator[Paragraph]": """Walk every paragraph of the version, in the order of the text. It is the tree read depth first: each paragraph, then the paragraphs it holds. """ return iter(self.dataset._paragraphs_of(self.id))
@property def placements(self) -> "Listing[Placement]": """Where each Proposal sits in the version, in the order of the text and of ranks.""" return self.dataset._placements_of(self.id) @property def proposals(self) -> "Listing[Proposal]": """The Proposals placed in the version, in the order of :attr:`placements`.""" return Listing(placement.proposal for placement in self.placements) @property def citations(self) -> "Listing[Citation]": """The citations made in the version, in the order of the text and of ranks.""" return self.dataset._citations_in(self.id)
[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class Paragraph(Entity): """A numbered division of an article version, made by a heading of level 1 to 4. The paragraphs of a version form a tree: a paragraph holds the paragraphs of a deeper level that follow it, up to the next paragraph of its level or of a higher one. The rows give no parent: the tree comes from the levels, in the order of the text. ``paragraph_id`` is the id that the source gives, never prefixed: the prefix ``p-`` belongs to the anchors of the text, and is left out when a row carries it. The same paragraph can keep its id from one version to the next, so the id of the entity also names its version, such as ``art-1.v3#3f2a``. ``repr`` shows its id and its number and title, such as ``Paragraph('art-1.v3#8c1d', '1.1 Parks')``. Args: id: The id of the paragraph. dataset: The dataset that the paragraph comes from. article_id: The id of the article of the paragraph. version_number: The number of the version of the paragraph. paragraph_id: The id of the paragraph within its version, without prefix. level: The level of its heading, from 1 to 4. number: The number of the paragraph, such as ``"1.2"``, as the source gives it. title: The title of the paragraph. parent_id: The id of the paragraph that holds this one, or ``None`` at the top. """ article_id: str version_number: int = 1 paragraph_id: str level: int = 1 number: str = "" title: str = "" parent_id: str | None = None #: The name of a paragraph in messages. noun: ClassVar[str] = "paragraph" def _label(self) -> str: return " ".join(part for part in (self.number, self.title) if part) @property def version(self) -> ArticleVersion: """The article version of the paragraph.""" return self.dataset.article_versions[f"{self.article_id}.v{self.version_number}"] @property def article(self) -> Article: """The article of the paragraph.""" return self.dataset.articles[self.article_id] @property def parent(self) -> "Paragraph | None": """The paragraph that holds this one, or ``None`` at the top of the tree.""" return None if self.parent_id is None else self.dataset.paragraphs[self.parent_id] @property def children(self) -> "Listing[Paragraph]": """The paragraphs that this one holds directly, in the order of the text.""" return self.dataset._children_of_paragraph(self.id) @property def placements(self) -> "Listing[Placement]": """The placements in this paragraph, by rank.""" return self.dataset._placements_in_paragraph(self.id) @property def proposals(self) -> "Listing[Proposal]": """The Proposals placed in this paragraph, by rank.""" return Listing(placement.proposal for placement in self.placements)
[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class Placement(Entity): """Where a Proposal sits in a version of its parent article: a paragraph and a rank. A Proposal is placed in its parent article only, and once per version; elsewhere it appears as a citation. A Proposal written before the first heading of the text sits outside any paragraph: its :attr:`paragraph` is ``None``. The id of a placement names the Proposal and the version, such as ``p-01@art-1.v3``. Args: id: The id of the placement. dataset: The dataset that the placement comes from. proposal_id: The id of the placed Proposal. article_id: The id of the article. version_number: The number of the version of the article. paragraph_id: The id of the paragraph within its version, without prefix, or ``None`` outside any paragraph. rank: The rank of the Proposal in its paragraph, as the source gives it: the Proposals of a paragraph come by rank, then in the order of the rows. """ proposal_id: str article_id: str version_number: int = 1 paragraph_id: str | None = None rank: int = 0 #: The name of a placement in messages. noun: ClassVar[str] = "placement" @property def proposal(self) -> "Proposal": """The placed Proposal.""" return self.dataset.proposals[self.proposal_id] @property def version(self) -> ArticleVersion: """The article version that the Proposal is placed in.""" return self.dataset.article_versions[f"{self.article_id}.v{self.version_number}"] @property def paragraph(self) -> Paragraph | None: """The paragraph that the Proposal is placed in, or ``None`` outside any.""" if self.paragraph_id is None: return None key = f"{self.article_id}.v{self.version_number}#{self.paragraph_id}" return self.dataset.paragraphs[key]
[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class Citation(Entity): """A Proposal cited in the text of an article that is not its parent article. A Proposal has one parent article, where it is placed; any other article can cite it, in a paragraph or before the first heading, even an article of another Project. The source of a citation is the article version that cites, its target is the cited Proposal, and the cited Revision is the one in force of that Proposal: the text cites the Proposal, never a Revision, and always shows its last adopted Revision. The cited Proposal may belong to a Project that the dataset does not hold: its id is kept, and reading the Proposal then raises :class:`~civiqhub.errors.NotFoundError`. The id of a citation names the Proposal and the version, such as ``p-01@art-2.v1``. Args: id: The id of the citation. dataset: The dataset that the citation comes from. proposal_id: The id of the cited Proposal. article_id: The id of the article that cites it. version_number: The number of the version of the article. paragraph_id: The id of the paragraph within its version, without prefix, or ``None`` outside any paragraph. rank: The rank of the citation in its paragraph, as the source gives it. """ proposal_id: str article_id: str version_number: int = 1 paragraph_id: str | None = None rank: int = 0 #: The name of a citation in messages. noun: ClassVar[str] = "citation" @property def proposal(self) -> "Proposal": """The cited Proposal, the target of the citation. Raises: NotFoundError: The Proposal belongs to a Project that the dataset does not hold. """ return self.dataset.proposals[self.proposal_id] @property def version(self) -> ArticleVersion: """The article version that cites the Proposal, the source of the citation.""" return self.dataset.article_versions[f"{self.article_id}.v{self.version_number}"] @property def article(self) -> Article: """The article that cites the Proposal.""" return self.dataset.articles[self.article_id] @property def paragraph(self) -> Paragraph | None: """The paragraph where the Proposal is cited, or ``None`` outside any.""" if self.paragraph_id is None: return None key = f"{self.article_id}.v{self.version_number}#{self.paragraph_id}" return self.dataset.paragraphs[key] @property def cited_revision(self) -> "Revision": """The Revision that the citation shows: the one in force of the cited Proposal. It is read, never stored: when an Amendment is adopted, the citation shows the new Revision. Raises: NotFoundError: The Proposal belongs to a Project that the dataset does not hold. """ return self.proposal.current_revision
[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class Proposal(Entity): """A statement put to the collective of a Project. A Proposal changes through numbered Revisions, one of which is current. A vote is on one Revision: the vote counts of a Proposal are those of its current Revision, not a sum over its Revisions. ``repr`` shows its id and the first 60 characters of its text, such as ``Proposal('p-01', 'Plant 150 trees in the parks.')``. Args: id: The id of the Proposal. dataset: The dataset that the Proposal comes from. project_id: The id of the Project of the Proposal. article_id: The id of the parent article of the Proposal, kept as the source gave it, or ``None``. author_id: The pseudonym of the author. It is ``None`` in an aggregated dataset. created_at: When the Proposal was created, in ISO 8601, or ``None``. current_revision_id: The id of the current Revision. Without it, the Revision with the highest number is current. """ project_id: str article_id: str | None = None author_id: str | None = None created_at: str | None = None current_revision_id: str | None = None #: The name of a Proposal in messages. noun: ClassVar[str] = "proposal" def _label(self) -> str: return self.text[:60] @property def project(self) -> Project: """The Project of the Proposal.""" return self.dataset.projects[self.project_id] @property def article(self) -> Article | None: """The parent article of the Proposal, or ``None`` for a Proposal of a Group. Raises: NotFoundError: The Proposal names a parent article that the dataset does not hold, as when the source gives no articles. """ return None if self.article_id is None else self.dataset.articles[self.article_id] @property def placement(self) -> Placement | None: """Where the Proposal sits in the version in force of its parent article. It is ``None`` for a Proposal of a Group, and when the source gives no placement of the Proposal in that version. Raises: NotFoundError: The Proposal names a parent article that the dataset does not hold. """ article = self.article if article is None: return None return self.dataset._placement_of(self.id, article.current_version.id) @property def citations(self) -> "Listing[Citation]": """The citations of this Proposal in the version in force of each citing article. A citation is made by an article, not by a Proposal: these are the citations that come to this Proposal. To read what an article cites, use :attr:`Article.citations`. """ return self.dataset._citations_of(self.id) @property def deprecated(self) -> tuple[DeprecatedValue, ...]: """The deprecated values read in the rows of this Proposal. They come from its row of ``proposals``, then from the rows of ``amendments`` for it: the status ``DRAFT`` or the kind ``SYNC`` of an Amendment, or a creation, a removal or a pending change, which builds no Amendment. It is empty for a Proposal of the current model. See :class:`~civiqhub.values.DeprecatedValue`. """ return self.dataset._deprecated_of("proposal", self.id) @property def revisions(self) -> "Listing[Revision]": """The Revisions of the Proposal, by increasing number.""" return self.dataset._revisions_of(self.id) @property def current_revision(self) -> "Revision": """The Revision in force.""" return self.dataset._current_revision_of(self.id) @property def text(self) -> str: """The affirmation of the current Revision.""" return self.current_revision.affirmation @property def vote_counts(self) -> VoteCounts: """The vote counts of the current Revision.""" return self.current_revision.vote_counts @property def is_amendment(self) -> bool: """Whether the Proposal is an Amendment.""" return False @property def amendments(self) -> "Listing[Amendment]": """The Amendments that target this Proposal directly, in the order of the rows.""" return self.dataset._amendments_of(self.id)
[docs] def walk_amendments(self) -> Iterator[tuple[int, "Proposal"]]: """Walk the tree of the Amendments of this Proposal, depth first. Yields: ``(0, self)`` first, then each Amendment with its depth: 1 for an Amendment to this Proposal, 2 for an Amendment to such an Amendment, and so on. """ stack: list[tuple[int, Proposal]] = [(0, self)] while stack: depth, proposal = stack.pop() yield depth, proposal stack.extend((depth + 1, child) for child in reversed(proposal.amendments))
@property def arguments(self) -> "Listing[Argument]": """The Arguments on this Proposal, depth first: each one, then its replies.""" return self.dataset._arguments_of(self.id) @property def votes(self) -> "Listing[Vote]": """The votes on the current Revision. Raises: ExposureError: The dataset is aggregated. """ self.dataset.require_individual_votes("proposal.votes") return self.dataset._votes_on(self.current_revision.id) @property def author(self) -> "Actant | None": """The Actant who wrote the Proposal, or ``None`` when the source does not say. Raises: ExposureError: The dataset is aggregated. """ self.dataset.require_individual_votes("proposal.author") return None if self.author_id is None else self.dataset.actants[self.author_id]
[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class Revision(Entity): """One numbered version of a Proposal. Votes are cast on a Revision. ``repr`` shows its id and its number, such as ``Revision('p-01.r2', 'r2')``. Args: id: The id of the Revision. dataset: The dataset that the Revision comes from. proposal_id: The id of the Proposal of the Revision. number: The number of the Revision, from 1, unique within its Proposal. affirmation: The text of the Proposal in this Revision. description: The description of the Proposal in this Revision. created_at: When the Revision was created, in ISO 8601, or ``None``. content_hash: The digest of the content that the source gave, or ``None``. amendment_id: The id of the amendment whose adoption produced this Revision, or ``None``. """ proposal_id: str number: int = 1 affirmation: str = "" description: str = "" created_at: str | None = None content_hash: str | None = None amendment_id: str | None = None #: The name of a Revision in messages. noun: ClassVar[str] = "revision" def _label(self) -> str: return f"r{self.number}" @property def proposal(self) -> Proposal: """The Proposal of the Revision.""" return self.dataset.proposals[self.proposal_id] @property def is_current(self) -> bool: """Whether the Revision is the one in force for its Proposal.""" return self.dataset._current_revision_of(self.proposal_id) is self @property def vote_counts(self) -> VoteCounts: """The five vote counts of the Revision, all zero when the source gave none.""" return self.dataset._vote_counts_of(self.id) @property def amendment(self) -> "Amendment | None": """The Amendment whose adoption produced this Revision, or ``None``. It is also ``None`` when ``amendment_id`` names a row of ``amendments`` that builds no Amendment: a deprecated creation or removal, marked in :attr:`Dataset.deprecated <civiqhub.dataset.Dataset.deprecated>`. """ if self.amendment_id is None: return None return self.dataset._amendment_by_row(self.amendment_id) @property def votes(self) -> "Listing[Vote]": """The votes on the Revision, in the order of the rows. Raises: ExposureError: The dataset is aggregated. ``vote_counts`` stays readable. """ self.dataset.require_individual_votes("revision.votes") return self.dataset._votes_on(self.id)
[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class Amendment(Proposal): """A Proposal that amends another Proposal, on one Revision of it. An Amendment has its own Revisions, votes and vote counts, as every Proposal. Once adopted, it produces a new Revision of the Proposal it targets. Only the local change of a Proposal exists: an Amendment has no type. An old row can hold the deprecated status ``DRAFT``, read as ``OPEN``, or the deprecated kind ``SYNC`` of a cascade. The Amendment is built, and :attr:`~Proposal.deprecated` marks these values. Args: id: The id of the Proposal that is an Amendment. dataset: The dataset that the Amendment comes from. project_id: The id of the Project of the Amendment. article_id: The id of the parent article, or ``None``. author_id: The pseudonym of the author. It is ``None`` in an aggregated dataset. created_at: When the Amendment was created, in ISO 8601, or ``None``. current_revision_id: The id of the current Revision of the Amendment. amendment_id: The id of the row of the section ``amendments``. target_id: The id of the Proposal that the Amendment targets. target_revision_id: The id of the Revision of the target that it amends. status: Whether the Amendment is open, adopted or rejected. adopted_revision_id: The id of the Revision of the target that its adoption produced, or ``None``. is_stale: Whether the target changed since the Amendment was written. """ amendment_id: str target_id: str target_revision_id: str status: AmendmentStatus = AmendmentStatus.OPEN adopted_revision_id: str | None = None is_stale: bool = False #: The name of an Amendment in messages. noun: ClassVar[str] = "amendment" @property def is_amendment(self) -> bool: """Whether the Proposal is an Amendment: always for an Amendment.""" return True @property def target(self) -> Proposal: """The Proposal that the Amendment targets.""" return self.dataset.proposals[self.target_id] @property def target_revision(self) -> Revision: """The Revision of the target that the Amendment amends.""" return self.dataset.revisions[self.target_revision_id] @property def is_adopted(self) -> bool: """Whether the Amendment was adopted.""" return self.status is AmendmentStatus.ADOPTED @property def adopted_revision(self) -> Revision | None: """The Revision of the target that the adoption produced, or ``None``.""" if self.adopted_revision_id is None: return None return self.dataset.revisions[self.adopted_revision_id] @property def root(self) -> Proposal: """The first Proposal that is not an Amendment, following the targets.""" proposal: Proposal = self while isinstance(proposal, Amendment): proposal = proposal.target return proposal
[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class Argument(Entity): """A reasoned stance on a Proposal. Arguments reply to each other as a tree. ``repr`` shows its id and the first 60 characters of its text. Args: id: The id of the Argument. dataset: The dataset that the Argument comes from. proposal_id: The id of the Proposal that the Argument is about. revision_id: The id of the Revision of that Proposal it was written on, or ``None``. author_id: The pseudonym of the author. It is ``None`` in an aggregated dataset. position: For, against or neither, or ``None`` when the source does not say. text: The text of the Argument. score: The score, from -2 to +2, when the source gives one, or ``None``. parent_id: The id of the Argument that this one replies to, or ``None``. n_supports: How many times the Argument was supported. """ proposal_id: str revision_id: str | None = None author_id: str | None = None position: Position | None = None text: str = "" score: int | None = None parent_id: str | None = None n_supports: int = 0 #: The name of an Argument in messages. noun: ClassVar[str] = "argument" def _label(self) -> str: return self.text[:60] @property def proposal(self) -> Proposal: """The Proposal that the Argument is about.""" return self.dataset.proposals[self.proposal_id] @property def revision(self) -> Revision | None: """The Revision that the Argument was written on, or ``None``.""" if self.revision_id is None: return None return self.dataset.revisions[self.revision_id] @property def parent(self) -> "Argument | None": """The Argument that this one replies to, or ``None`` at the top of a thread.""" if self.parent_id is None: return None return self.dataset.arguments[self.parent_id] @property def replies(self) -> "Listing[Argument]": """The Arguments that reply to this one directly, in the order of the rows.""" return self.dataset._replies_to(self.id) @property def depth(self) -> int: """How deep the Argument is in its thread: 0 at the top.""" return self.dataset._depth_of(self.id) @property def author(self) -> "Actant | None": """The Actant who wrote the Argument, or ``None`` when the source does not say. Raises: ExposureError: The dataset is aggregated. """ self.dataset.require_individual_votes("argument.author") return None if self.author_id is None else self.dataset.actants[self.author_id]
[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class Actant(Entity): """Anyone who acts in a Project: a human member or an agent. The SDK knows an Actant by its pseudonym only, which is its id: never by a name, a display name, an e-mail address or an internal id. A pseudonym is valid in its dataset only. Two Actants from two datasets are never equal, even with the same pseudonym: an Actant cannot be followed from one load to the next. The dataset builds a :class:`Member` for a human, an :class:`Agent` for an agent, and an Actant of kind ``other`` otherwise. Args: id: The pseudonym of the Actant. dataset: The dataset that the Actant comes from. kind: Human, agent or other. role: The role of the Actant in the Project, or ``None`` when the source does not say. """ kind: ActantKind = ActantKind.HUMAN role: Role | None = None #: The name of an Actant in messages. noun: ClassVar[str] = "actant" @property def pseudonym(self) -> str: """The pseudonym of the Actant: its id.""" return self.id @property def votes(self) -> "Listing[Vote]": """The votes of the Actant, in the order of the rows.""" return self.dataset._votes_of(self.id) @property def arguments(self) -> "Listing[Argument]": """The Arguments that the Actant wrote, in the order of the rows.""" return self.dataset._arguments_by(self.id)
[docs] def vote_on(self, target: Proposal | Revision) -> "Vote | None": """Return the vote of the Actant on a Revision, or ``None``. Args: target: A Revision, or a Proposal, for its current Revision. A vote on an older Revision of the Proposal is not returned. """ revision = target.current_revision if isinstance(target, Proposal) else target return self.dataset._vote_of(self.id, revision.id)
[docs] def vote_state_on(self, target: Proposal | Revision) -> VoteState: """Say whether the Actant voted on a Revision, abstained, or did not see it. The rule has three steps. A vote exists: ``VOTED``. Otherwise, when the dataset records impressions: ``ABSTAINED`` if the Revision was shown to the Actant, ``NOT_SHOWN`` if not. Otherwise: ``UNKNOWN``. A missing vote is never read as a neutral vote, nor as an abstention when the impressions are not recorded. Args: target: A Revision, or a Proposal, for its current Revision. """ revision = target.current_revision if isinstance(target, Proposal) else target if self.dataset._vote_of(self.id, revision.id) is not None: return VoteState.VOTED if not self.dataset.has_impressions: return VoteState.UNKNOWN if self.dataset._was_shown(self.id, revision.id): return VoteState.ABSTAINED return VoteState.NOT_SHOWN
[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class Member(Actant): """A human member of a Project, known by a pseudonym."""
[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class Agent(Actant): """A software agent that takes part with the same grammar as a member."""
[docs] @dataclass(frozen=True, kw_only=True, eq=False, repr=False) class Vote(Entity): """The vote of one Actant on one Revision, from -2 to +2. 0 is a deliberate choice, not an abstention: an abstention is the absence of a vote. ``repr`` shows its id and its signed score, such as ``Vote('m-001@p-01.r2', '+2')``. Args: id: ``"{actant_id}@{revision_id}"``. dataset: The dataset that the vote comes from. actant_id: The pseudonym of the Actant who voted. revision_id: The id of the Revision voted on. score: The score, from -2 to +2. cast_at: When the vote was cast, in ISO 8601, or ``None``. """ actant_id: str revision_id: str score: int cast_at: str | None = None #: The name of a vote in messages. noun: ClassVar[str] = "vote" def _label(self) -> str: return f"{self.score:+d}" if self.score else "0" @property def actant(self) -> Actant: """The Actant who voted.""" return self.dataset.actants[self.actant_id] @property def revision(self) -> Revision: """The Revision voted on.""" return self.dataset.revisions[self.revision_id] @property def proposal(self) -> Proposal: """The Proposal of the Revision voted on.""" return self.revision.proposal
[docs] def to_record(self) -> tuple[str, str, int]: """Return ``(actant_id, revision_id, score)``.""" return (self.actant_id, self.revision_id, self.score)