civiqhub.entities¶
The objects of the product.
Entity is what every object of the product shares: a frozen value, known by its
id, tied to the Dataset it comes from. Group,
Project, Article (with its ArticleVersion, its
Paragraph, the Placement of its Proposals and its Citation of
other Proposals), Proposal,
Amendment, Revision, Argument, Actant (with
Member and Agent) and Vote are the objects of the product.
Actants and votes exist only in a pseudonymised dataset. In an aggregated one, reading
them raises ExposureError.
- class civiqhub.entities.Actant(*, id, dataset, kind=ActantKind.HUMAN, role=None)[source]¶
Bases:
EntityAnyone 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
Memberfor a human, anAgentfor an agent, and an Actant of kindotherotherwise.- Parameters:
id (str) – The pseudonym of the Actant.
dataset (Dataset) – The dataset that the Actant comes from.
kind (ActantKind) – Human, agent or other.
role (Role | None) – The role of the Actant in the Project, or
Nonewhen the source does not say.
- noun: ClassVar[str] = 'actant'¶
The name of an Actant in messages.
- property pseudonym: str¶
The pseudonym of the Actant: its id.
- property arguments: Listing[Argument]¶
The Arguments that the Actant wrote, in the order of the rows.
- vote_state_on(target)[source]¶
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:ABSTAINEDif the Revision was shown to the Actant,NOT_SHOWNif not. Otherwise:UNKNOWN. A missing vote is never read as a neutral vote, nor as an abstention when the impressions are not recorded.
- class civiqhub.entities.Agent(*, id, dataset, kind=ActantKind.HUMAN, role=None)[source]¶
Bases:
ActantA software agent that takes part with the same grammar as a member.
- Parameters:
id (str)
dataset (Dataset)
kind (ActantKind)
role (Role | None)
- class civiqhub.entities.Amendment(*, id, dataset, project_id, article_id=None, author_id=None, created_at=None, current_revision_id=None, amendment_id, target_id, target_revision_id, status=AmendmentStatus.OPEN, adopted_revision_id=None, is_stale=False)[source]¶
Bases:
ProposalA 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 asOPEN, or the deprecated kindSYNCof a cascade. The Amendment is built, anddeprecatedmarks these values.- Parameters:
id (str) – The id of the Proposal that is an Amendment.
dataset (Dataset) – The dataset that the Amendment comes from.
project_id (str) – The id of the Project of the Amendment.
article_id (str | None) – The id of the parent article, or
None.author_id (str | None) – The pseudonym of the author. It is
Nonein an aggregated dataset.created_at (str | None) – When the Amendment was created, in ISO 8601, or
None.current_revision_id (str | None) – The id of the current Revision of the Amendment.
amendment_id (str) – The id of the row of the section
amendments.target_id (str) – The id of the Proposal that the Amendment targets.
target_revision_id (str) – The id of the Revision of the target that it amends.
status (AmendmentStatus) – Whether the Amendment is open, adopted or rejected.
adopted_revision_id (str | None) – The id of the Revision of the target that its adoption produced, or
None.is_stale (bool) – Whether the target changed since the Amendment was written.
- noun: ClassVar[str] = 'amendment'¶
The name of an Amendment in messages.
- property is_amendment: bool¶
Whether the Proposal is an Amendment: always for an Amendment.
- property is_adopted: bool¶
Whether the Amendment was adopted.
- class civiqhub.entities.Argument(*, id, dataset, proposal_id, revision_id=None, author_id=None, position=None, text='', score=None, parent_id=None, n_supports=0)[source]¶
Bases:
EntityA reasoned stance on a Proposal. Arguments reply to each other as a tree.
reprshows its id and the first 60 characters of its text.- Parameters:
id (str) – The id of the Argument.
dataset (Dataset) – The dataset that the Argument comes from.
proposal_id (str) – The id of the Proposal that the Argument is about.
revision_id (str | None) – The id of the Revision of that Proposal it was written on, or
None.author_id (str | None) – The pseudonym of the author. It is
Nonein an aggregated dataset.position (Position | None) – For, against or neither, or
Nonewhen the source does not say.text (str) – The text of the Argument.
score (int | None) – The score, from -2 to +2, when the source gives one, or
None.parent_id (str | None) – The id of the Argument that this one replies to, or
None.n_supports (int) – How many times the Argument was supported.
- noun: ClassVar[str] = 'argument'¶
The name of an Argument in messages.
- property parent: Argument | None¶
The Argument that this one replies to, or
Noneat the top of a thread.
- property replies: Listing[Argument]¶
The Arguments that reply to this one directly, in the order of the rows.
- property depth: int¶
How deep the Argument is in its thread: 0 at the top.
- property author: Actant | None¶
The Actant who wrote the Argument, or
Nonewhen the source does not say.- Raises:
ExposureError – The dataset is aggregated.
- class civiqhub.entities.Article(*, id, dataset, project_id, position=1, title='', description='', current_version_number=1, published_at=None)[source]¶
Bases:
EntityAn 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;
current_versionis the one in force.reprshows its id and its title, such asArticle('art-1', 'Green spaces').- Parameters:
id (str) – The id of the article.
dataset (Dataset) – The dataset that the article comes from.
project_id (str) – The id of the Project of the article.
position (int) – The place of the article in its Project, from 1, unique within the Project.
title (str) – The title of the article.
description (str) – The description of the article.
current_version_number (int) – The number of the version in force.
published_at (str | None) – When the version in force was published, in ISO 8601, or
None.
- noun: ClassVar[str] = 'article'¶
The name of an article in messages.
- property versions: Listing[ArticleVersion]¶
Every version of the article, by number.
- property current_version: ArticleVersion¶
The version in force, the one numbered
current_version_number.
- property paragraphs: 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
children.walk_paragraphs()gives them all.
- walk_paragraphs()[source]¶
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 type:
Iterator[Paragraph]
- class civiqhub.entities.ArticleVersion(*, id, dataset, article_id, number=1, title='', body='', published_at=None)[source]¶
Bases:
EntityOne 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.reprshows its id and its number, such asArticleVersion('art-1.v3', 'v3').- Parameters:
id (str) – The id of the version.
dataset (Dataset) – The dataset that the version comes from.
article_id (str) – The id of the article of the version.
number (int) – The number of the version, from 1, unique within its article.
title (str) – The title of the article in this version.
body (str) – The text of the article in this version.
published_at (str | None) – When the version was published, in ISO 8601, or
None.
- noun: ClassVar[str] = 'article version'¶
The name of an article version in messages.
- property is_current: bool¶
Whether the version is the one in force for its article.
- property paragraphs: Listing[Paragraph]¶
The top of the tree of paragraphs of the version, in the order of the text.
- walk_paragraphs()[source]¶
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 type:
Iterator[Paragraph]
- property placements: Listing[Placement]¶
Where each Proposal sits in the version, in the order of the text and of ranks.
- property proposals: Listing[Proposal]¶
The Proposals placed in the version, in the order of
placements.
- class civiqhub.entities.Citation(*, id, dataset, proposal_id, article_id, version_number=1, paragraph_id=None, rank=0)[source]¶
Bases:
EntityA 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
NotFoundError. The id of a citation names the Proposal and the version, such asp-01@art-2.v1.- Parameters:
id (str) – The id of the citation.
dataset (Dataset) – The dataset that the citation comes from.
proposal_id (str) – The id of the cited Proposal.
article_id (str) – The id of the article that cites it.
version_number (int) – The number of the version of the article.
paragraph_id (str | None) – The id of the paragraph within its version, without prefix, or
Noneoutside any paragraph.rank (int) – The rank of the citation in its paragraph, as the source gives it.
- noun: ClassVar[str] = 'citation'¶
The name of a citation in messages.
- property proposal: Proposal¶
The cited Proposal, the target of the citation.
- Raises:
NotFoundError – The Proposal belongs to a Project that the dataset does not hold.
- property version: ArticleVersion¶
The article version that cites the Proposal, the source of the citation.
- property paragraph: Paragraph | None¶
The paragraph where the Proposal is cited, or
Noneoutside any.
- property cited_revision: 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.
- class civiqhub.entities.Entity(*, id, dataset)[source]¶
Bases:
objectAn 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.- Parameters:
id (str) – The id of the entity.
dataset (Dataset) – The dataset that the entity comes from. It is not shown by
repr.
- noun: ClassVar[str] = 'entity'¶
The name of the entity in messages, such as
"proposal".
- class civiqhub.entities.Group(*, id, dataset, slug, name='', description='', parent_id=None)[source]¶
Bases:
EntityA community on CiviqHub. It holds Groups and Projects.
reprshows its id and its name, such asGroup('g-1', 'Demo collective').- Parameters:
id (str) – The id of the Group.
dataset (Dataset) – The dataset that the Group comes from.
slug (str) – The short name of the Group in addresses, unique in its dataset.
name (str) – The name of the Group.
description (str) – The description of the Group.
parent_id (str | None) – The id of the Group that holds this one, or
Noneat the top.
- noun: ClassVar[str] = 'group'¶
The name of a Group in messages.
- class civiqhub.entities.Member(*, id, dataset, kind=ActantKind.HUMAN, role=None)[source]¶
Bases:
ActantA human member of a Project, known by a pseudonym.
- Parameters:
id (str)
dataset (Dataset)
kind (ActantKind)
role (Role | None)
- class civiqhub.entities.Paragraph(*, id, dataset, article_id, version_number=1, paragraph_id, level=1, number='', title='', parent_id=None)[source]¶
Bases:
EntityA 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_idis the id that the source gives, never prefixed: the prefixp-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 asart-1.v3#3f2a.reprshows its id and its number and title, such asParagraph('art-1.v3#8c1d', '1.1 Parks').- Parameters:
id (str) – The id of the paragraph.
dataset (Dataset) – The dataset that the paragraph comes from.
article_id (str) – The id of the article of the paragraph.
version_number (int) – The number of the version of the paragraph.
paragraph_id (str) – The id of the paragraph within its version, without prefix.
level (int) – The level of its heading, from 1 to 4.
number (str) – The number of the paragraph, such as
"1.2", as the source gives it.title (str) – The title of the paragraph.
parent_id (str | None) – The id of the paragraph that holds this one, or
Noneat the top.
- noun: ClassVar[str] = 'paragraph'¶
The name of a paragraph in messages.
- property version: ArticleVersion¶
The article version of the paragraph.
- property parent: Paragraph | None¶
The paragraph that holds this one, or
Noneat the top of the tree.
- class civiqhub.entities.Placement(*, id, dataset, proposal_id, article_id, version_number=1, paragraph_id=None, rank=0)[source]¶
Bases:
EntityWhere 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
paragraphisNone. The id of a placement names the Proposal and the version, such asp-01@art-1.v3.- Parameters:
id (str) – The id of the placement.
dataset (Dataset) – The dataset that the placement comes from.
proposal_id (str) – The id of the placed Proposal.
article_id (str) – The id of the article.
version_number (int) – The number of the version of the article.
paragraph_id (str | None) – The id of the paragraph within its version, without prefix, or
Noneoutside any paragraph.rank (int) – 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.
- noun: ClassVar[str] = 'placement'¶
The name of a placement in messages.
- property version: ArticleVersion¶
The article version that the Proposal is placed in.
- class civiqhub.entities.Project(*, id, dataset, slug, name='', description='', group_id=None)[source]¶
Bases:
EntityA Project of a Group: the set of its articles and of their versions.
Every proposal of a Project has a parent article.
articlesgives the articles in the order of the Project.reprshows its id and its name, such asProject('budget-2027', 'Budget participatif').- Parameters:
id (str) – The id of the Project.
dataset (Dataset) – The dataset that the Project comes from.
slug (str) – The short name of the Project in addresses, unique in its dataset.
name (str) – The name of the Project.
description (str) – The description of the Project.
group_id (str | None) – The id of the Group of the Project, or
Nonewhen the data does not say.
- noun: ClassVar[str] = 'project'¶
The name of a Project in messages.
- property as_of: str¶
The instant that the data describes, the one of the dataset.
- property participation: Participation¶
The counts of what happened in the Project, as the source gave them.
- property articles: Listing[Article]¶
The articles of the Project, in the order of their positions.
The order is the one the source gives in the key
positionof the rows: the same rows give the same order, load after load.
- property citations: 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.
- to_citation_edges()[source]¶
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 ofcitations.- Return type:
list[tuple[str, str]]
- property deprecated: 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
DeprecatedValue.
- property proposals: Listing[Proposal]¶
The Proposals of the Project that are not Amendments, in the order of the rows.
- property revisions: 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.
- property arguments: 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.
- property actants: 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.
- property votes: Listing[Vote]¶
The votes on the Revisions of the Project, Amendments included.
- Raises:
ExposureError – The dataset is aggregated.
- class civiqhub.entities.Proposal(*, id, dataset, project_id, article_id=None, author_id=None, created_at=None, current_revision_id=None)[source]¶
Bases:
EntityA 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.
reprshows its id and the first 60 characters of its text, such asProposal('p-01', 'Plant 150 trees in the parks.').- Parameters:
id (str) – The id of the Proposal.
dataset (Dataset) – The dataset that the Proposal comes from.
project_id (str) – The id of the Project of the Proposal.
article_id (str | None) – The id of the parent article of the Proposal, kept as the source gave it, or
None.author_id (str | None) – The pseudonym of the author. It is
Nonein an aggregated dataset.created_at (str | None) – When the Proposal was created, in ISO 8601, or
None.current_revision_id (str | None) – The id of the current Revision. Without it, the Revision with the highest number is current.
- noun: ClassVar[str] = 'proposal'¶
The name of a Proposal in messages.
- property article: Article | None¶
The parent article of the Proposal, or
Nonefor 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.
- property placement: Placement | None¶
Where the Proposal sits in the version in force of its parent article.
It is
Nonefor 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.
- property citations: 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
Article.citations.
- property deprecated: tuple[DeprecatedValue, ...]¶
The deprecated values read in the rows of this Proposal.
They come from its row of
proposals, then from the rows ofamendmentsfor it: the statusDRAFTor the kindSYNCof 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. SeeDeprecatedValue.
- property text: str¶
The affirmation of the current Revision.
- property vote_counts: VoteCounts¶
The vote counts of the current Revision.
- property is_amendment: bool¶
Whether the Proposal is an Amendment.
- property amendments: Listing[Amendment]¶
The Amendments that target this Proposal directly, in the order of the rows.
- walk_amendments()[source]¶
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.- Return type:
Iterator[tuple[int, Proposal]]
- property arguments: Listing[Argument]¶
The Arguments on this Proposal, depth first: each one, then its replies.
- property votes: Listing[Vote]¶
The votes on the current Revision.
- Raises:
ExposureError – The dataset is aggregated.
- property author: Actant | None¶
The Actant who wrote the Proposal, or
Nonewhen the source does not say.- Raises:
ExposureError – The dataset is aggregated.
- class civiqhub.entities.Revision(*, id, dataset, proposal_id, number=1, affirmation='', description='', created_at=None, content_hash=None, amendment_id=None)[source]¶
Bases:
EntityOne numbered version of a Proposal. Votes are cast on a Revision.
reprshows its id and its number, such asRevision('p-01.r2', 'r2').- Parameters:
id (str) – The id of the Revision.
dataset (Dataset) – The dataset that the Revision comes from.
proposal_id (str) – The id of the Proposal of the Revision.
number (int) – The number of the Revision, from 1, unique within its Proposal.
affirmation (str) – The text of the Proposal in this Revision.
description (str) – The description of the Proposal in this Revision.
created_at (str | None) – When the Revision was created, in ISO 8601, or
None.content_hash (str | None) – The digest of the content that the source gave, or
None.amendment_id (str | None) – The id of the amendment whose adoption produced this Revision, or
None.
- noun: ClassVar[str] = 'revision'¶
The name of a Revision in messages.
- property is_current: bool¶
Whether the Revision is the one in force for its Proposal.
- property vote_counts: VoteCounts¶
The five vote counts of the Revision, all zero when the source gave none.
- property amendment: Amendment | None¶
The Amendment whose adoption produced this Revision, or
None.It is also
Nonewhenamendment_idnames a row ofamendmentsthat builds no Amendment: a deprecated creation or removal, marked inDataset.deprecated.
- property votes: Listing[Vote]¶
The votes on the Revision, in the order of the rows.
- Raises:
ExposureError – The dataset is aggregated.
vote_countsstays readable.
- class civiqhub.entities.Vote(*, id, dataset, actant_id, revision_id, score, cast_at=None)[source]¶
Bases:
EntityThe 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.
reprshows its id and its signed score, such asVote('m-001@p-01.r2', '+2').- Parameters:
id (str) –
"{actant_id}@{revision_id}".dataset (Dataset) – The dataset that the vote comes from.
actant_id (str) – The pseudonym of the Actant who voted.
revision_id (str) – The id of the Revision voted on.
score (int) – The score, from -2 to +2.
cast_at (str | None) – When the vote was cast, in ISO 8601, or
None.
- noun: ClassVar[str] = 'vote'¶
The name of a vote in messages.