civiqhub.errors

The errors of the SDK.

Every error the SDK raises derives from CiviqHubError. Its message says what is wrong; its hint says what to do next, in the words of the product.

An error also derives from the standard exception that means the same thing, when there is one, so that code which does not know the SDK still catches it: except LookupError catches a NotFoundError.

Messages and hints are complete English sentences. None of them holds a token, even in part.

exception civiqhub.errors.AuthenticationError(message, *, hint=None)[source]

Bases: CiviqHubError

Raised when the token is missing, malformed, expired or revoked.

Parameters:
  • message (str)

  • hint (str)

Return type:

None

hint: str = 'Create a personal access token in the settings of your Project, then pass it to civiqhub.connect(token) or set CIVIQHUB_TOKEN.'

What to do next.

exception civiqhub.errors.CiviqHubError(message, *, hint=None)[source]

Bases: Exception

The root of every error of the SDK.

Catch it to handle any error of the SDK in one place. The message says what is wrong. hint says what to do next; it is also attached to the error as a note, so that a traceback shows it under the message.

Every subclass declares its own non-empty hint: a subclass without one raises TypeError when it is defined.

Parameters:
  • message (str) – What is wrong.

  • hint (str) – What to do next. Without it, or when it is empty, the error takes the hint of its class.

Return type:

None

hint: str = 'The message of this error says what is wrong and what to change.'

What to do next. Each error class declares its own; an error raised with a hint of its own carries that one instead.

exception civiqhub.errors.ExposureError(message, *, hint=None)[source]

Bases: CiviqHubError

Raised when data is asked for at a level of detail the dataset does not hold.

An aggregated dataset holds neither individual votes nor actants, for instance.

It does not derive from PermissionError, which is an error of the operating system: an except OSError written for the network would catch it.

Parameters:
  • message (str)

  • hint (str)

Return type:

None

hint: str = 'Ask an administrator of the Project to enable pseudonymised access, then connect with civiqhub.connect(exposure="pseudonymised").'

What to do next.

exception civiqhub.errors.MissingExtraError(message, *, hint=None)[source]

Bases: CiviqHubError, ImportError

Raised when an analysis is asked for and the engine is not installed.

Parameters:
  • message (str)

  • hint (str)

Return type:

None

hint: str = 'Install it with: pip install "civiqhub[selene]".'

What to do next.

exception civiqhub.errors.NotFoundError(message, *, hint=None)[source]

Bases: CiviqHubError, LookupError

Raised when what is asked for is not covered by the token, or does not exist.

An id that does not exist in the dataset raises it too.

Parameters:
  • message (str)

  • hint (str)

Return type:

None

hint: str = 'Check the id or slug; client.group().projects lists what the token covers.'

What to do next.

exception civiqhub.errors.RateLimitedError(message, *, retry_after=None)[source]

Bases: CiviqHubError

Raised when the API asks to slow down.

Parameters:
  • message (str) – What is wrong.

  • retry_after (float | None) – How many seconds to wait before the next call, when the API says it.

Return type:

None

hint: str = 'Wait retry_after seconds, then call again.'

What to do next.

retry_after: float | None

How many seconds to wait before the next call, or None when the API does not say.

exception civiqhub.errors.UnavailableError(message, *, hint=None)[source]

Bases: CiviqHubError, LookupError

Raised when a value is read from an analysis that has none.

Parameters:
  • message (str)

  • hint (str)

Return type:

None

hint: str = 'Test analysis.is_available first; analysis.unavailable says why.'

What to do next.

exception civiqhub.errors.ValidationError(message, *, hint=None)[source]

Bases: CiviqHubError, ValueError

Raised when rows break an invariant of the model.

Parameters:
  • message (str)

  • hint (str)

Return type:

None

hint: str = 'The message names the row and the rule it breaks.'

What to do next.