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 |
||
List the Projects of a Group |
||
Read the articles of a Project and their versions |
|
|
Walk the paragraphs of an article, and find where each Proposal sits |
|
|
Find where a Proposal is cited, and export the graph of citations |
|
|
Read the Proposals and their Revisions |
|
|
Walk the tree of the Amendments |
||
Walk the tree of the Arguments |
||
Read the participation |
||
Know when the data were read |
Read votes¶
I want to |
Use |
Module |
|---|---|---|
Read the vote counts of a Revision |
||
Read each vote, at the pseudonymised level |
||
Read the Actants and what each one did |
|
|
Know whether an Actant voted, abstained or never saw a Revision |
||
Choose the level of detail |
|
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 |
||
Read an old dataset, and find the values that the model deprecated ( |
|
|
Read rows held in memory |
||
Read a saved file through a client |
||
Build a dataset from rows directly |
||
Try the SDK on synthetic data |
|
Understand an error¶
I want to |
Use |
Module |
|---|---|---|
Catch any error of the SDK |
||
Know what to do next |
||
Handle a token that is missing or refused |
||
Handle a level of detail that the data do not hold |
||
Handle rows that break a rule of the model |
||
Wait when the API asks to slow down |
Write a source¶
I want to |
Use |
Module |
|---|---|---|
Give the SDK the data of another system |
A subclass of |
|
Serve stored rows at the level asked for |
||
Know the format of the rows |
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 |
|---|---|
The SDK. One file per module of the reference: |
|
The tests, one file per subject. |
|
The pages of this site |
|
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.