Finding your way

This page says which name to use for each need, which page of the reference documents it, and which file holds it. To understand why the SDK is built this way, read Architecture.

Every name below is exported by the package: import civiqhub is enough, and civiqhub.Project is the same class as civiqhub.entities.Project.

I want to…

Read a Project

I want to

Use

Module

Load the Project that my token covers

civiqhub.connect(), then Client.project

client

List the Projects of a Group

Client.group, Group.projects

client, entities

Read the articles of a Project and their versions

Project.articles, civiqhub.Article, Article.current_version, civiqhub.ArticleVersion

entities

Walk the paragraphs of an article, and find where each Proposal sits

Article.paragraphs, civiqhub.Paragraph, Article.proposals, Proposal.placement, civiqhub.Placement

entities

Find where a Proposal is cited, and export the graph of citations

Proposal.citations, Article.citations, civiqhub.Citation, Project.to_citation_edges

entities

Read the Proposals and their Revisions

Project.proposals, Proposal.revisions, Proposal.current_revision

entities

Walk the tree of the Amendments

civiqhub.Amendment, Proposal.walk_amendments

entities

Walk the tree of the Arguments

Proposal.arguments, Argument.depth, civiqhub.Position

entities, values

Read the participation

Project.participation, civiqhub.Participation

values

Know when the data were read

Project.as_of

entities

Read votes

I want to

Use

Module

Read the vote counts of a Revision

Revision.vote_counts, civiqhub.VoteCounts

values

Read each vote, at the pseudonymised level

Project.votes, civiqhub.Vote

entities

Read the Actants and what each one did

Project.actants, civiqhub.Actant, civiqhub.Member, civiqhub.Agent

entities

Know whether an Actant voted, abstained or never saw a Revision

Actant.vote_state_on, civiqhub.VoteState

entities, values

Choose the level of detail

civiqhub.Exposure, the argument exposure of civiqhub.connect()

values

A vote is never inferred: an Actant who did not vote is “abstained” when the Revision was shown, “not shown” when it was not, and “unknown” when the data do not record what was shown.

Load from a file or from memory

I want to

Use

Module

Save what I loaded, and reopen it later

Dataset.save, civiqhub.load()

dataset, client

Read an old dataset, and find the values that the model deprecated (DRAFT, SYNC, forks…)

Dataset.deprecated, Proposal.deprecated, civiqhub.DeprecatedValue

dataset, values

Read rows held in memory

civiqhub.MemorySource

sources

Read a saved file through a client

civiqhub.FileSource

sources

Build a dataset from rows directly

civiqhub.Dataset

dataset

Try the SDK on synthetic data

civiqhub.make_project(), civiqhub.make_rows(), civiqhub.make_truth()

synthetic

Understand an error

I want to

Use

Module

Catch any error of the SDK

civiqhub.CiviqHubError

errors

Know what to do next

CiviqHubError.hint

errors

Handle a token that is missing or refused

civiqhub.AuthenticationError

errors

Handle a level of detail that the data do not hold

civiqhub.ExposureError

errors

Handle rows that break a rule of the model

civiqhub.ValidationError

errors

Wait when the API asks to slow down

civiqhub.RateLimitedError, RateLimitedError.retry_after

errors

Write a source

I want to

Use

Module

Give the SDK the data of another system

A subclass of civiqhub.Source

sources

Serve stored rows at the level asked for

civiqhub.sources.at_exposure()

sources

Know the format of the rows

civiqhub.dataset.FORMAT

dataset

The docstring of civiqhub.sources says how to write a source in three steps. Architecture says where it fits.

Two names for one object

Each object has two import paths: the module that defines it, and the package that exports it.

from civiqhub import Project
from civiqhub.entities import Project as SameProject

print(Project is SameProject)
True

Import from the package: it is the shorter path, and the one that stays stable. The reference documents each object once, on the page of the module that defines it; the page of the package lists what the package exports.

Where the files are

Path

Content

src/civiqhub/

The SDK. One file per module of the reference: civiqhub.sources is src/civiqhub/sources.py

tests/

The tests, one file per subject. tests/support.py holds the hand-written rows and the fake API that the tests share

docs/

The pages of this site

docs/snippets.md

The code of each use, run by the tests against a fake API

In the reference, the [source] link next to a name opens the code that defines it.

Not written yet

The bridge to the engine civiqhub-selene (the collective regimes, the vote matrix, co-clustering and consensus between opinion groups) is planned.