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: object

Reads one source at one level of exposure, and keeps what it read.

A client loads a Dataset the 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:
  • source (Source) – Where the rows come from: the API, a file, memory, or a source of your own.

  • exposure (Exposure) – The level of detail asked for: "aggregated" (the default) or "pseudonymised".

Raises:

ValidationError – The source is not a Source, or the level is unknown. The message lists the two levels.

source: Source

Where the rows come from.

exposure: Exposure

The level of detail of every dataset the client loads.

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:
Return type:

Dataset

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 ref is left out and the source covers several Projects.

Return type:

Project

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:

Group

refresh()[source]

Forget the datasets loaded so far: the next call reads the source again.

The objects already given stay valid and unchanged: they belong to their own dataset.

Return type:

None

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 variable CIVIQHUB_TOKEN is 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:

Client

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:
Return type:

Dataset