civiqhub.client¶
The way in: a token or a source, then a Project or a Group.
connect() returns a Client, which holds a source and a level of exposure,
and gives the Project or the Group that the source covers. load() reopens a file
written by save(), without network and without token.
The default level is aggregated: the most careful one.
- class civiqhub.client.Client(source, *, exposure=Exposure.AGGREGATED)[source]¶
Bases:
objectReads one source at one level of exposure, and keeps what it read.
A client loads a
Datasetthe first time it is asked for a container, and gives the same one afterwards without reading the source again.refresh()forgets them, so that the next call reads the source again.- Parameters:
- Raises:
ValidationError – The source is not a
Source, or the level is unknown. The message lists the two levels.
- load(container=None)[source]¶
Return the dataset of what the source covers, read once and then kept.
- Parameters:
container (str | None) – The id or the slug of one Project, when the source covers several. Each container is loaded and kept apart.
- Returns:
The dataset, whose source is the description of the source.
- Raises:
CiviqHubError – The source could not give the rows; the error says why.
ValidationError – The rows break a rule of the model.
- Return type:
- project(ref=None)[source]¶
Return the Project with this id or slug, or the one that the source covers.
- Parameters:
ref (str | None) – The id or the slug of the Project. Without it, the source must cover exactly one Project.
- Raises:
NotFoundError – No Project has this id or slug, or
refis left out and the source covers several Projects.- Return type:
- group(ref=None)[source]¶
Return the Group with this id or slug, or the one that the source covers.
- Parameters:
ref (str | None) – The id or the slug of the Group. Without it, the source must cover exactly one Group.
- Raises:
NotFoundError – The source covers no Group, as a token of a Project does; or no Group has this id or slug.
- Return type:
- civiqhub.client.connect(token=None, *, exposure=Exposure.AGGREGATED, source=None, base_url=DEFAULT_URL)[source]¶
Open CiviqHub with a personal access token, or with a source of your own.
Nothing is read until a Project or a Group is asked for.
- Parameters:
token (str | None) – The personal access token. Without it and without
source, the variableCIVIQHUB_TOKENis read.exposure (Exposure | str) –
"aggregated"(the default): the vote counts of each Revision."pseudonymised": one row per vote, when the Project allows it.source (Source | None) – A source that replaces the API: a file, memory, or a source of your own.
base_url (str) – The base address of the API, when the source is the API.
- Returns:
A client of the source.
- Raises:
ValidationError – Both a token and a source are given, or a base address with a source, or the level is unknown.
AuthenticationError – The source is the API and no valid token is found.
- Return type:
- civiqhub.client.load(path)[source]¶
Reopen a dataset written by
save().No network and no token are needed. It is the same as
Dataset.from_file.- Parameters:
path (str | Path) – The path of the file.
- Raises:
NotFoundError – No file is at this path.
ValidationError – The file is not JSON, or not in the format of a dataset.
- Return type: