Getting started¶
This page installs the SDK and reads a synthetic Project, without a token and without the network. The tests of the repository run every Python block of this page and compare what it prints with the output shown.
Install¶
pip install civiqhub
The version on PyPI, 0.0.1, only reserves the name. To run what this page shows, install the development branch:
pip install "civiqhub @ git+https://github.com/civiqhub/civiqhub-py@develop"
Python 3.11 or later is required. The SDK depends on nothing but the standard library.
Open a synthetic project¶
civiqhub.make_project() gives a Project made up from a seed. It describes nobody, and it has a known structure: three opinion groups of Actants and two blocks of Proposals, which the votes follow.
import civiqhub
project = civiqhub.make_project()
print(project)
print(len(project.proposals), "proposals,", len(project.amendments), "amendments")
Project('pr-demo', 'Demo project (synthetic)')
15 proposals, 2 amendments
The Project is read through a civiqhub.MemorySource, at the pseudonymised level: it holds every vote, each Actant known by a pseudonym.
Read proposals and vote counts¶
A Proposal has one or more Revisions; the current one is current_revision. The votes of a Revision are counted from score -2 to score +2 in civiqhub.VoteCounts. Everything was read at one instant, as_of.
print("Data as of", project.as_of)
for proposal in project.proposals[:3]:
revision = proposal.current_revision
print(proposal.id, revision.number, revision.vote_counts)
Data as of 2026-01-01T00:00:00Z
p-01 1 VoteCounts(-2: 8, -1: 4, 0: 6, +1: 4, +2: 8)
p-02 1 VoteCounts(-2: 4, -1: 8, 0: 2, +1: 5, +2: 11)
p-03 1 VoteCounts(-2: 10, -1: 1, 0: 5, +1: 10, +2: 9)
The counts are raw: the SDK computes no mean and no label of consensus. The Proposal p-15 has two Revisions; the second one comes from an Amendment that was adopted.
amended = project.proposals[14]
print([revision.number for revision in amended.revisions])
print(amended.current_revision.amendment)
[1, 2]
Amendment('p-16', 'Synthetic amendment 16.')
Read the participation¶
participation gives the counts of the Project. turnout is the share of the Actants who voted.
participation = project.participation
print(participation.n_voters, "of", participation.n_actants, "actants voted")
print(participation.turnout)
48 of 48 actants voted
1.0
Save and reopen¶
What a source gave is a civiqhub.Dataset: the Project, and everything around it, at one instant. save() writes it to a file, and civiqhub.load() reopens it without the network.
import tempfile
from pathlib import Path
with tempfile.TemporaryDirectory() as folder:
path = project.dataset.save(Path(folder) / "demo.json")
reopened = civiqhub.load(path)
print(reopened.fingerprint() == project.dataset.fingerprint())
print(reopened.source)
True
file demo.json
The fingerprint identifies the rows: the same rows give the same fingerprint, on every system.
Connect with a token¶
To read your own Project, create a personal access token in the settings of the Project and set it in the environment variable CIVIQHUB_TOKEN. civiqhub.connect() reads it, and gives a civiqhub.Client:
import civiqhub
project = civiqhub.connect().project()
group = civiqhub.connect("civ_pat_...").group()
The second line passes the token as an argument instead. A token covers one Project or one Group, and never more than what its owner sees. The SDK only reads: it sends no change.
Exposure levels¶
The level of exposure is the level of detail of the data, a value of civiqhub.Exposure. connect() asks for the aggregated level by default: the vote counts and the participation, and nothing about who voted. Asking an aggregated Project for its Actants or its votes raises civiqhub.ExposureError, whose hint says what to do.
aggregated = civiqhub.make_project(exposure="aggregated")
print(aggregated.dataset.exposure)
try:
aggregated.actants
except civiqhub.ExposureError as error:
print(error.hint)
aggregated
Ask an administrator of the Project to enable pseudonymised access, then connect with civiqhub.connect(exposure="pseudonymised").
The pseudonymised level gives one row per vote. An administrator of the Project must enable it.
Next¶
Finding your way says which name to use for what, and where it lives.
Architecture explains how the SDK is built and why a dataset is frozen.
Snippets holds the code of each use in eight lines.
The reference documents every public name.