validio_sdk package

Subpackages

Submodules

validio_sdk.config module

Persistent configuration.

class validio_sdk.config.Config(config_dir: Path | None = None)

Bases: object

Config management.

A class to work with configuration such as reading, writing and deleting.

exists() → bool

Check if any configuration exist.

read() → ValidioConfig

Read persistent configuration.

Will return None if no configuration is created yet.

Returns:

The configuration, or None

Return type:

ValidioConfig | None

Raises:

ConfigNotFoundError if no configuration exists

Raises:

ConfigNotFoundError if the configuration is invalid

remove() → None

Remove the configuration at the instance’s config_path.

write(config: ValidioConfig) → None

Write the passed configuration to disk.

This will fully overwrite the existing configuration, including any fields that’s not a part of the ValidioConfig.

Parameters:

config – A ValidioConfig object.

class validio_sdk.config.ValidioConfig(endpoint: str = '', access_key: str = '', access_secret: str = '', default_namespace: str = 'default')

Bases: object

Representation of configuration to use in the Validio system and SDK.

property access_secret: str
asdict() → dict[str, str]

Return a dictionary representation of the class.

This is used from our ClassJSONEncoder to ensure we save JSON representing the class with the external property names. By doing this we can also ensure that we can serialize the config by passing the JSON to the constructor.

validio_sdk.config.default_config_dir() → Path

Get the default config dir based on the OS.

validio_sdk.dbt module

Utilities for dbt.

validio_sdk.dbt.trim_manifest_json(manifest: dict) → dict

Takes a dbt manifest json and discards all the fields that are not relevant used by the validio platform.

Parameters:

manifest – The manifest object

async validio_sdk.dbt.upload_artifacts(client: APIClient | Client, credential_id: str, job_name: str, manifest: dict, run_results: dict | None) → None

Helper function to upload dbt artifacts. The artifacts are additionally trimmed before uploading.

Parameters:

  • client – Client to use for the artifacts upload.

  • credential_id – DBTCore credential id to upload artifacts on behalf of.

  • job_name – Job associated with the artifacts.

  • manifest – manifest.json payload

  • run_results – run_results.json payload

validio_sdk.exception module

Exceptions used throughout the system.

exception validio_sdk.exception.ConfigInvalidError

Bases: ValidioError

Exception when the configuration file is invalid.

exception validio_sdk.exception.ConfigNotFoundError(endpoint_env: str, access_key_env: str, secret_access_key_env: str)

Bases: ValidioError

Exception when no configuration is found.

exception validio_sdk.exception.ForbiddenError

Bases: ValidioError

Exception throw when doing forbidden request.

This happens when trying to access API methods not allowed, e.g. adding resources to a namespace the API key is not part of.

exception validio_sdk.exception.ManifestConfigurationError(*args: Any)

Bases: ValidioError

Raised when there is an invalid configuration in the manifest.

exception validio_sdk.exception.UnauthorizedError(access_key_env: str, secret_access_key_env: str)

Bases: ValidioError

Exception thrown when unauthorized request is made.

exception validio_sdk.exception.ValidioBugError(*args: Any)

Bases: ValidioError

Same as ValidioError but marked for bugs to be reported.

exception validio_sdk.exception.ValidioConnectionError(endpoint_env: str, e: Exception)

Bases: ValidioError

Exception thrown when connection to Validio backend fails.

exception validio_sdk.exception.ValidioError(*args: Any)

Bases: Exception

Base exception used for every exception thrown by Validio.

exception validio_sdk.exception.ValidioResourceError(resource: Resource, message: str)

Bases: ValidioError

Exception related to a specific resource.

exception validio_sdk.exception.ValidioTimeoutError(method: str | None = None, timeout: int | float | None = None)

Bases: ValidioError

Validio specific timeout error.

validio_sdk.features module

Opt-in feature flags for experimental server capabilities.

Features listed here gate SDK support for server-side capabilities that may change or be removed. Users opt in via --feature <name> (repeatable) or --all-features on the CLI. The SDK must keep working for users who do not opt in, even if the server later drops or changes a gated feature — default code paths must not reference gated GraphQL types.

The CLI writes the selection to the VALIDIO_FEATURES environment variable; subprocesses (e.g. the user’s manifest program) inherit it automatically.

class validio_sdk.features.Feature(*values)

Bases: str, Enum

Opt-in feature flags.

Flag names are not part of the stable API — a feature may graduate (the flag gets removed) or be dropped entirely between releases.

GCP_GEMINI_ENTERPRISE_CREDENTIAL = 'gemini'
JIRA = 'jira'
MICROSOFT_FOUNDRY_CREDENTIAL = 'microsoft-foundry'
OPEN_EDGE = 'open-edge'
SAP_IQ = 'sap-iq'
validio_sdk.features.all_features() → frozenset[Feature]

All known features.

validio_sdk.features.is_enabled(feature: Feature) → bool

Return True if the given feature is opted in for this process.

validio_sdk.features.set_enabled(features: frozenset[Feature]) → None

Replace the set of enabled features.

Writes to the VALIDIO_FEATURES environment variable so subprocesses inherit the selection. Call once at CLI startup after parsing arguments.

validio_sdk.metadata module

Metadata information about the package.

validio_sdk.metadata.version() → str

Get the version of the SDK from the metadata.

validio_sdk.poll module

Helpers related to source polls.

class validio_sdk.poll.SourcePollInfo(source_id: str, poll_id: str, poll_timestamp: datetime)

Bases: object

Details about a poll that was started.

Variables:

  • source_id – The id of the source being polled.

  • poll_id – The id of the started poll.

  • poll_timestamp – The time at which the poll was initiated.

poll_id: str
poll_timestamp: datetime
source_id: str
class validio_sdk.poll.SourcePollResult(info: SourcePollInfo, error: Exception | None = None, has_incidents: bool | None = None)

Bases: object

The outcome of polling a source.

Variables:

  • info – Details about the started poll. Can be passed to wait_until_poll_completion to resume waiting for the same poll.

  • error – Any error that occurred while waiting for the poll. When set, has_incidents is left unset.

  • has_incidents – Whether any new incidents were created while polling. Only set once the poll completed successfully.

error: Exception | None = None
has_incidents: bool | None = None
info: SourcePollInfo
async validio_sdk.poll.poll_source(*, source_id_or_name: str, client: APIClient, namespace: str | None = None, poll_interval_seconds: float = 5.0, timeout_seconds: float | None = None) → SourcePollResult

Manually poll a source and check if it produced new incidents.

The source is polled with the sourceManualPoll API, we then wait for the poll to complete and finally check the incidents API for any incidents created since the poll started.

Resolving the source and starting the poll raise on failure. Once the poll is started, waiting for it never raises; any error from that phase is returned on the result instead, along with the info that can be passed to wait_until_poll_completion to retry the waiting phase.

Parameters:

  • source_id_or_name – The id or the resource name of the source to poll. If a resource name is given it is resolved to its id.

  • client – The APIClient to use for the requests.

  • namespace – The namespace to look up the source in. Required when a resource name is given since resource names are only unique within a namespace. Ignored when an id is given.

  • poll_interval_seconds – How long to wait between progress checks. The progress API is rate limited so this should not be too low.

  • timeout_seconds – Maximum time to wait for the poll to complete. If None we wait indefinitely.

Returns:

A SourcePollResult describing the outcome.

Raises:

ValidioError – If the source can’t be resolved or the poll can’t be started.

async validio_sdk.poll.wait_until_poll_completion(*, client: APIClient, info: SourcePollInfo, poll_interval_seconds: float = 5.0, timeout_seconds: float | None = None) → SourcePollResult

Wait for an already started poll to complete and check for incidents.

This is the second phase of poll_source and can be used to resume waiting for a poll that was already started, e.g. to retry after a timeout.

Errors are returned as part of the result rather than raised.

Parameters:

  • client – The APIClient to use for the requests.

  • info – Details about the started poll, as returned in a SourcePollResult.

  • poll_interval_seconds – How long to wait between progress checks. The progress API is rate limited so this should not be too low.

  • timeout_seconds – Maximum time to wait for the poll to complete. If None we wait indefinitely.

Returns:

A SourcePollResult describing the outcome.

Module contents

class validio_sdk.BooleanFilter(*, field: str, operator: BooleanFilterOperator, name: str, source: Source, display_name: str | None = None, ignore_changes: bool = False, recreate_on_change: bool = False)

Bases: Filter

A Boolean filter configuration.

https://docs.validio.io/docs/filters#boolean-filter

class validio_sdk.BooleanFilterOperator(*values)

Bases: str, Enum

Configures the behavior of a Boolean filter.

IS_TRUE: Allow values equal to TRUE IS_FALSE: Allow values equal to FALSE

IS_FALSE = 'IS_FALSE'
IS_TRUE = 'IS_TRUE'
exception validio_sdk.ConfigInvalidError

Bases: ValidioError

Exception when the configuration file is invalid.

exception validio_sdk.ConfigNotFoundError(endpoint_env: str, access_key_env: str, secret_access_key_env: str)

Bases: ValidioError

Exception when no configuration is found.

class validio_sdk.EnumFilter(*, field: str, values: list[str], name: str, source: Source, operator: EnumFilterOperator = EnumFilterOperator.ALLOW, display_name: str | None = None, ignore_changes: bool = False, recreate_on_change: bool = False)

Bases: Filter

An Enum filter configuration.

https://docs.validio.io/docs/filters#enum

class validio_sdk.EnumFilterOperator(*values)

Bases: str, Enum

Configures the behavior of an Enum filter.

ALLOW: Allow values in the enum DENY: Deny values in the enum

ALLOW = 'ALLOW'
DENY = 'DENY'
class validio_sdk.NullFilter(*, field: str, name: str, source: Source, operator: NullFilterOperator = NullFilterOperator.IS, display_name: str | None = None, ignore_changes: bool = False, recreate_on_change: bool = False)

Bases: Filter

A Null filter configuration.

https://docs.validio.io/docs/filters#null

class validio_sdk.NullFilterOperator(*values)

Bases: str, Enum

Configures the behavior of a Null filter.

IS: Filter in NULL values IS_NOT: Filter in Non-NULL values

IS = 'IS'
IS_NOT = 'IS_NOT'
class validio_sdk.SourcePollInfo(source_id: str, poll_id: str, poll_timestamp: datetime)

Bases: object

Details about a poll that was started.

Variables:

  • source_id – The id of the source being polled.

  • poll_id – The id of the started poll.

  • poll_timestamp – The time at which the poll was initiated.

poll_id: str
poll_timestamp: datetime
source_id: str
class validio_sdk.SourcePollResult(info: SourcePollInfo, error: Exception | None = None, has_incidents: bool | None = None)

Bases: object

The outcome of polling a source.

Variables:

  • info – Details about the started poll. Can be passed to wait_until_poll_completion to resume waiting for the same poll.

  • error – Any error that occurred while waiting for the poll. When set, has_incidents is left unset.

  • has_incidents – Whether any new incidents were created while polling. Only set once the poll completed successfully.

error: Exception | None = None
has_incidents: bool | None = None
info: SourcePollInfo
class validio_sdk.SqlFilter(*, query: str, name: str, source: Source, display_name: str | None = None, ignore_changes: bool = False, recreate_on_change: bool = False)

Bases: Filter

A SQL filter configuration.

https://docs.validio.io/docs/filters#sql-filter

class validio_sdk.StringFilter(*, field: str, operator: StringFilterOperator, name: str, source: Source, value: str | None = None, display_name: str | None = None, ignore_changes: bool = False, recreate_on_change: bool = False)

Bases: Filter

A String filter configuration.

https://docs.validio.io/docs/filters#string

class validio_sdk.StringFilterOperator(*values)

Bases: str, Enum

Configures the behavior of a String filter.

IS_EMPTY: The string is empty IS_NOT_EMPTY: The string is not empty CONTAINS: The string contains DOES_NOT_CONTAIN: The string does not contain STARTS_WITH: The string is prefixed with ENDS_WITH: The string is suffixed with IS_EXACTLY: Exact match of full string REGEX: Regular expressions

CONTAINS = 'CONTAINS'
DOES_NOT_CONTAIN = 'DOES_NOT_CONTAIN'
ENDS_WITH = 'ENDS_WITH'
IS_EMPTY = 'IS_EMPTY'
IS_EXACTLY = 'IS_EXACTLY'
IS_NOT_EMPTY = 'IS_NOT_EMPTY'
REGEX = 'REGEX'
STARTS_WITH = 'STARTS_WITH'
class validio_sdk.ThresholdFilter(*, field: str, value: float, name: str, source: Source, operator: ThresholdFilterOperator, display_name: str | None = None, ignore_changes: bool = False, recreate_on_change: bool = False)

Bases: Filter

A Threshold filter configuration.

https://docs.validio.io/docs/filters#threshold-filter

class validio_sdk.ThresholdFilterOperator(*values)

Bases: str, Enum

Configures the behavior of a String filter.

EQUAL: The value equals (==) NOT_EQUAL: The value does not equal (!=) LESS_THAN: The value is less than (<) LESS_THAN_OR_EQUAL: The value is less than or equal (<=) GREATER_THAN: The value is greater than (>) GREATER_THAN_OR_EQUAL: The value is greater than or equal (>=)

EQUAL = 'EQUAL'
GREATER_THAN = 'GREATER'
GREATER_THAN_OR_EQUAL = 'GREATER_EQUAL'
LESS_THAN = 'LESS'
LESS_THAN_OR_EQUAL = 'LESS_EQUAL'
NOT_EQUAL = 'NOT_EQUAL'
exception validio_sdk.UnauthorizedError(access_key_env: str, secret_access_key_env: str)

Bases: ValidioError

Exception thrown when unauthorized request is made.

exception validio_sdk.ValidioConnectionError(endpoint_env: str, e: Exception)

Bases: ValidioError

Exception thrown when connection to Validio backend fails.

exception validio_sdk.ValidioError(*args: Any)

Bases: Exception

Base exception used for every exception thrown by Validio.

validio_sdk.load_jtd_schema(filepath: Path) → dict

Reads a jtd schema from a file on disk.

Parameters:

filepath – Path to the file containing the schema contents.

async validio_sdk.poll_source(*, source_id_or_name: str, client: APIClient, namespace: str | None = None, poll_interval_seconds: float = 5.0, timeout_seconds: float | None = None) → SourcePollResult

Manually poll a source and check if it produced new incidents.

The source is polled with the sourceManualPoll API, we then wait for the poll to complete and finally check the incidents API for any incidents created since the poll started.

Resolving the source and starting the poll raise on failure. Once the poll is started, waiting for it never raises; any error from that phase is returned on the result instead, along with the info that can be passed to wait_until_poll_completion to retry the waiting phase.

Parameters:

  • source_id_or_name – The id or the resource name of the source to poll. If a resource name is given it is resolved to its id.

  • client – The APIClient to use for the requests.

  • namespace – The namespace to look up the source in. Required when a resource name is given since resource names are only unique within a namespace. Ignored when an id is given.

  • poll_interval_seconds – How long to wait between progress checks. The progress API is rate limited so this should not be too low.

  • timeout_seconds – Maximum time to wait for the poll to complete. If None we wait indefinitely.

Returns:

A SourcePollResult describing the outcome.

Raises:

ValidioError – If the source can’t be resolved or the poll can’t be started.

async validio_sdk.wait_until_poll_completion(*, client: APIClient, info: SourcePollInfo, poll_interval_seconds: float = 5.0, timeout_seconds: float | None = None) → SourcePollResult

Wait for an already started poll to complete and check for incidents.

This is the second phase of poll_source and can be used to resume waiting for a poll that was already started, e.g. to retry after a timeout.

Errors are returned as part of the result rather than raised.

Parameters:

  • client – The APIClient to use for the requests.

  • info – Details about the started poll, as returned in a SourcePollResult.

  • poll_interval_seconds – How long to wait between progress checks. The progress API is rate limited so this should not be too low.

  • timeout_seconds – Maximum time to wait for the poll to complete. If None we wait indefinitely.

Returns:

A SourcePollResult describing the outcome.