Snippets

Each snippet is the exact code for one use of the SDK, in eight lines at most. It reads on its own: it starts with import civiqhub and needs nothing from the snippets before it. The tests run every snippet of this page and of the README, against a fake API that opens no connection.

The snippets S1 to S7 read the CiviqHub API with a personal access token. civiqhub.connect() reads the token in the environment variable CIVIQHUB_TOKEN; civiqhub.connect("civ_pat_...") takes it as an argument. The snippets S8 and S9 need neither a token nor a network.

Under each snippet, “Reads alone” says whether every name of the snippet is clear without a comment, or lists the names that still need one.

S1. Load the Project that the token covers

import civiqhub

project = civiqhub.connect().project()
for proposal in project.proposals:
    print(proposal.id, proposal.text)

Reads alone: yes.

S2. Read the Revisions and their vote counts

import civiqhub

project = civiqhub.connect().project()
print("Data as of", project.as_of)
for proposal in project.proposals:
    for revision in proposal.revisions:
        print(revision.number, revision.vote_counts, revision is proposal.current_revision)

Reads alone: yes.

S3. Walk the tree of the Amendments and the tree of the Arguments

import civiqhub

proposal = civiqhub.connect().project().proposals[0]
for depth, amendment in proposal.walk_amendments():
    print("  " * depth, amendment.id, amendment.text)
for argument in proposal.arguments:
    print("  " * argument.depth, argument.position, argument.text)

Reads alone: no. walk_amendments() gives the Proposal itself first, at depth 0, before its Amendments; the name does not say it.

S4. Read the participation

import civiqhub

participation = civiqhub.connect().project().participation
print(participation.n_voters, "of", participation.n_actants, "actants voted")
print("Turnout:", participation.turnout)

Reads alone: yes.

S5. List the Projects of a Group

import civiqhub

group = civiqhub.connect().group()
for project in group.projects:
    print(project.slug, project.name)

Reads alone: yes.

S6. Read the hint of an error

import civiqhub

try:
    civiqhub.connect("a token copied badly")
except civiqhub.AuthenticationError as error:
    print(error)
    print(error.hint)

Reads alone: yes.

S7. Save, then reopen without network

import civiqhub

project = civiqhub.connect().project()
path = project.dataset.save("consultation.json")
dataset = civiqhub.load(path)
print(dataset.fingerprint() == project.dataset.fingerprint())

Reads alone: no. dataset: why the Project is saved through its dataset, and what a dataset is (all that the source gave at one instant), needs one sentence.

S8. Read rows held in memory

Rows from any system, in the format civiqhub.dataset/0, go through a MemorySource. Here, the rows are synthetic.

import civiqhub

rows = civiqhub.make_rows(seed=1)
source = civiqhub.MemorySource(rows)
project = civiqhub.connect(source=source, exposure="pseudonymised").project()
print(len(project.actants), "actants,", len(project.votes), "votes")
48 actants, 415 votes

Reads alone: no. exposure="pseudonymised": the word “exposure” for the level of detail needs a comment.

S9. Try the SDK on a synthetic Project

The synthetic Project is made up from a seed: it describes nobody.

import civiqhub

project = civiqhub.make_project()
proposal = project.proposals[0]
print(project.name)
print(proposal.text, proposal.current_revision.vote_counts)
Demo project (synthetic)
Synthetic proposal 01. VoteCounts(-2: 8, -1: 4, 0: 6, +1: 4, +2: 8)

Reads alone: yes.