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:
CiviqHubErrorRaised 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:
ExceptionThe 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.
hintsays 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 raisesTypeErrorwhen 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:
CiviqHubErrorRaised 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: anexcept OSErrorwritten 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,ImportErrorRaised 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,LookupErrorRaised 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:
CiviqHubErrorRaised 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
Nonewhen the API does not say.
Bases:
CiviqHubError,LookupErrorRaised when a value is read from an analysis that has none.
- Parameters:
message (str)
hint (str)
- Return type:
None
What to do next.
- exception civiqhub.errors.ValidationError(message, *, hint=None)[source]¶
Bases:
CiviqHubError,ValueErrorRaised 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.