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: 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 Member for a human, an Agent for an agent, and an Actant of kind other otherwise.

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 None when 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 votes: Listing[Vote]

The votes of the Actant, in the order of the rows.

property arguments: Listing[Argument]

The Arguments that the Actant wrote, in the order of the rows.

vote_on(target)[source]

Return the vote of the Actant on a Revision, or None.

Parameters:

target (Proposal | Revision) – A Revision, or a Proposal, for its current Revision. A vote on an older Revision of the Proposal is not returned.

Return type:

Vote | None

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

Parameters:

target (Proposal | Revision) – A Revision, or a Proposal, for its current Revision.

Return type:

VoteState

class civiqhub.entities.Agent(*, id, dataset, kind=ActantKind.HUMAN, role=None)[source]

Bases: Actant

A software agent that takes part with the same grammar as a member.

Parameters:
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: 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 deprecated marks 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 None in 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 target: Proposal

The Proposal that the Amendment targets.

property target_revision: Revision

The Revision of the target that the Amendment amends.

property is_adopted: bool

Whether the Amendment was adopted.

property adopted_revision: Revision | None

The Revision of the target that the adoption produced, or None.

property root: Proposal

The first Proposal that is not an Amendment, following the targets.

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

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 None in an aggregated dataset.

  • position (Position | None) – For, against or neither, or None when 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 proposal: Proposal

The Proposal that the Argument is about.

property revision: Revision | None

The Revision that the Argument was written on, or None.

property parent: Argument | None

The Argument that this one replies to, or None at 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 None when 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: 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; current_version is the one in force.

repr shows its id and its title, such as Article('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 project: Project

The Project of the article.

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]

property proposals: 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.

property citations: Listing[Citation]

The citations made in the version in force, in the order of the text.

class civiqhub.entities.ArticleVersion(*, id, dataset, article_id, number=1, title='', body='', published_at=None)[source]

Bases: 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').

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 article: Article

The article of the version.

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.

property citations: Listing[Citation]

The citations made in the version, in the order of the text and of ranks.

class civiqhub.entities.Citation(*, id, dataset, proposal_id, article_id, version_number=1, paragraph_id=None, rank=0)[source]

Bases: 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 NotFoundError. The id of a citation names the Proposal and the version, such as p-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 None outside 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 article: Article

The article that cites the Proposal.

property paragraph: Paragraph | None

The paragraph where the Proposal is cited, or None outside 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: object

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.

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

_label()[source]

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

str

class civiqhub.entities.Group(*, id, dataset, slug, name='', description='', parent_id=None)[source]

Bases: Entity

A community on CiviqHub. It holds Groups and Projects.

repr shows its id and its name, such as Group('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 None at the top.

noun: ClassVar[str] = 'group'

The name of a Group in messages.

property parent: Group | None

The Group that holds this one, or None at the top.

property groups: Listing[Group]

The Groups that this Group holds directly, in the order of the rows.

property projects: Listing[Project]

The Projects of this Group, in the order of the rows.

class civiqhub.entities.Member(*, id, dataset, kind=ActantKind.HUMAN, role=None)[source]

Bases: Actant

A human member of a Project, known by a pseudonym.

Parameters:
class civiqhub.entities.Paragraph(*, id, dataset, article_id, version_number=1, paragraph_id, level=1, number='', title='', parent_id=None)[source]

Bases: 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').

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 None at the top.

noun: ClassVar[str] = 'paragraph'

The name of a paragraph in messages.

property version: ArticleVersion

The article version of the paragraph.

property article: Article

The article of the paragraph.

property parent: Paragraph | None

The paragraph that holds this one, or None at the top of the tree.

property children: Listing[Paragraph]

The paragraphs that this one holds directly, in the order of the text.

property placements: Listing[Placement]

The placements in this paragraph, by rank.

property proposals: Listing[Proposal]

The Proposals placed in this paragraph, by rank.

class civiqhub.entities.Placement(*, id, dataset, proposal_id, article_id, version_number=1, paragraph_id=None, rank=0)[source]

Bases: 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 paragraph is None. The id of a placement names the Proposal and the version, such as p-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 None outside 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 proposal: Proposal

The placed Proposal.

property version: ArticleVersion

The article version that the Proposal is placed in.

property paragraph: Paragraph | None

The paragraph that the Proposal is placed in, or None outside any.

class civiqhub.entities.Project(*, id, dataset, slug, name='', description='', group_id=None)[source]

Bases: Entity

A Project of a Group: the set of its articles and of their versions.

Every proposal of a Project has a parent article. articles gives the articles in the order of the Project.

repr shows its id and its name, such as Project('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 None when the data does not say.

noun: ClassVar[str] = 'project'

The name of a Project in messages.

property group: Group | None

The Group of the Project, or None when the data does not say.

property as_of: str

The instant that the data describes, the one of the dataset.

property exposure: Exposure

The level of detail of the data, 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 position of 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 of citations.

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 amendments: Listing[Amendment]

The Amendments of the Project, in the order of the rows.

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: 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.').

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 None in 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 project: Project

The Project of the Proposal.

property article: 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.

property placement: 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.

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

property revisions: Listing[Revision]

The Revisions of the Proposal, by increasing number.

property current_revision: Revision

The Revision in force.

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 None when 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: 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').

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 proposal: Proposal

The Proposal of the Revision.

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 None when amendment_id names a row of amendments that builds no Amendment: a deprecated creation or removal, marked in Dataset.deprecated.

property votes: Listing[Vote]

The votes on the Revision, in the order of the rows.

Raises:

ExposureError – The dataset is aggregated. vote_counts stays readable.

class civiqhub.entities.Vote(*, id, dataset, actant_id, revision_id, score, cast_at=None)[source]

Bases: 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').

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.

property actant: Actant

The Actant who voted.

property revision: Revision

The Revision voted on.

property proposal: Proposal

The Proposal of the Revision voted on.

to_record()[source]

Return (actant_id, revision_id, score).

Return type:

tuple[str, str, int]