API

The Data Validation API provides an interface to use components of the App, without running the App from a GUI.

Validation Manager

class tk_multi_data_validation.api.ValidationManager(bundle=None, rule_settings=None, include_rules=None, exclude_rules=None, logger=None, notifier=None, has_ui=False)

Bases: object

Manager class for data validation.

This class is responsible for retrieving the data validation rules from the current bundle’s settings, and creating the set of ValidationRule objects that define how the data should be validated.

This class object may be passed to the tk_multi_data_validation.widgets.ValidationWidget to help manager validation rules, and executing their actions.

It also coordinates the execution of validation rule check and fix functions.

Initialize the validation manager from the settings data.

The hook “hook_data_validation” will be used to get the validation data for the manager by calling the hook’s method “get_validation_data”. NOTE the data returned by this hook method will be modified.

Parameters:

• bundle (TankBundle) – The bundle instance for the app.

• rule_settings (dict) – The rule settings to use for this manager. Default is to use the current bunlde’s settings.

• include_rules (list<str>) – List of rule ids to include from the app’s default rules list.

• exclude_rules (list<str>) – List of rule ids to exclude from the app’s default rules list.

• logger (A standard python logger.) – This is a standard python logger to use during validation. A default logger will be provided if not supplied.

• notifier (ValidationNotifer) – A notifier object to emit Qt signals.

• has_ui (bool) – Set to True if the manager is being used with a UI, else False.

Signal ValidationNotifier.validate_rule_begin(ValidationRule):

Emits before a validation rule check function is executed. The returned parameter is the validation rule.

Signal ValidationNotifier.validate_rule_finished(ValidationRule):

Emits after a validation rule check function is executed. The returned parameter is the validation rule.

property notifier

Get the notifier for the validation manager.

property rules

Get the list of validtaion rules obtained from the validation data.

property rule_types

Get or set the rule types.

property errors

Get the list of rules which did not pass the last time their respective validate function was executed.

property accept_rule_fn

Get or set the function called to check if the validation should be applied to the given rule.

This property must be a function that takes a single param (ValidationRule) and returns a bool to indicate if the rule should be validated or not.

property has_ui

Get the flag indicating if this manager is running with a User Interface.

get_rule(rule_id)

Return the validation rule object for the id.

Parameters:

rule_id (str) – The validation rule unique identifier.

Returns:

The validation rule.

Return type:

ValidationRule

reset()

Reset the manager state.

Clear the errors.

validate()

Validate the data by executing all validation rule check functions.

This method will reset the current validation manager state before validating any rules. This means that any errors found on a previous validation operation will be removed.

Returns:

True if all validation rule checks passed (data is valid), else False.

Return type:

bool

validate_rules(rules, fetch_dependencies=True, emit_signals=True)

Validate the given list of rules.

This method will not reset the current validation manager state. This means that if a rule was found to have errors and it is not processed in this validation operation, than the error will remain.

Parameters:

• rules (list<ValidationRule> | ValidationRule) – The list of rules to validate. This method will also accept a single validation object.

• fetch_dependencies (bool) – Set to True to ensure all dependencies for a rule are validated before the rule itself is validated. Set to False will not fetch any missing dependencies to validate first. Set to None to prompt user to fetch or not. Defaults to True.

• emit_signals – True will emit notifier signals when validation begins and ends.

• emit_signals – bool

validate_rule(rule, emit_signals=True)

Validate the data with the given rule.

The check function executed to validate the DCC data is implemented by the ValidationRule (e.g. the manager does nothing to validate the data, it is just responsible for executing the validate functions).

Parameters:

rule (ValidationRule) – The rule to validate data by

Returns:

True if the validation rule check passed (data is valid for this rule), else False.

Return type:

bool

resolve(pre_validate=True, post_validate=False, retry_until_success=True)

Resolve the current data violations found by the validate method.

The fix function executed to resolve the DCC data violations is implemented by the ValidationRule (e.g. the manager does nothing to validate the data, it is just responsible for executing the fix functions).

Parameters:

• pre_validate (bool) – True will run each rule’s validation before its fix, to ensure the error data passed to the fix accurately reflects the most current data.

• post_validate (bool) – True will run the validation step after the resolve step, to check that the scene data is valid after resolution steps applied. Default False.

• retry_until_success (bool) – Set to True will try to fun the resolution operation until all rules have been resolved. The maximum number of tries to resolve will be equal to the number of rules in the manager. This will perform post validate step, evne if post validate has been set to False. Default True.

Returns:

True if the resolve operation was successful, else False. Note that if the post_validate param is False, this will always be True, since the return status is based on the status returned by post validating the data.

Return type:

bool

resolve_rules(rules, pre_validate=True, fetch_dependencies=None, emit_signals=True)

Resolve the given list of rules.

Parameters:

• rules (list<ValidationRule> | ValidationRule) – The list of rules to resolve. This method will also accept a single validation object.

• pre_validate (bool) – True will run each rule’s validation before its fix, to ensure the error data passed to the fix accurately reflects the most current data.

• fetch_dependencies (bool) – Set to True to ensure all dependencies for a rule are resolved before the rule itself is resolved. Set to False will not fetch any missing dependencies to resolve first. Set to None to prompt user to fetch or not. Defaults to None.

resolve_rule(rule, pre_validate=True, emit_signals=True)

Resolve the validation rule.

Parameters:

rule (ValidationRule) – The validation rule to resolve

Validation Rule

class tk_multi_data_validation.api.data.ValidationRule(rule_data, bundle=None)

Bases: object

A validation rule to be applied to the DCC data, which determines if the DCC data is valid or not.

The key properties of the rule are the check_func and fix_func; these functions define the how the DCC data is validated and provides an automated function to resolve data that is not valid. See the list of class properties below for more information on what data is contained in the validation rule object.

Create a validation rule with the provided data.

Parameters:

rule_data (dict) – The data that defines the rule.

rule_data dict format

id

type:

str

description:

The unique identifier for this rule.

name

type:

str

description:

The display name for this rule.

data_type:

type:

str

description:

The name of the data type that this rule pertains to.

description

type:

str

description:

Text that describes what the rule checks for in the data.

required

type:

bool

description:

True indicates that this rule should be applied when validating the data.

checked

type:

bool

description:

True indicates that this rule has a checked state (for UI purposes), False indicates the rule is unchecked.

check_name

type:

str

description:

The display name for the rule’s check function.

check_func

type:

function

description:

The function the rule executes to check the data for violations agains the rule.

fix_name

type:

str

description:

The display name for the rule’s fix function.

fix_func

type:

function

description:

The function the rule executes to fix the data violations found after applying the rule’s check function to the data.

fix_tooltip

type:

str

description:

Text that describes what the rule’s fix function will do.

error_msg

type:

str

description:

Text that describes how the data is not valid.

warn_msg

type:

str

description:

Text that describes the warning for this rule.

get_kwargs

type:

function

description:

A function that returns a dictionary of keyword arguments to pass to the check and fix functions.

actions

type:

list<dict>

description:

A list of actions that can be applied to the data to resolve any errors for this rule.

Required Keys

name

type:

str

description:

The display text for the action.

callback

type:

function

description:

The function to call when the action is invoked.

Optional Keys

tooltip

type:

str

description:

Text to display as for the item action’s tooltip help messages.

item_actions

type:

list<dict>

description:

A list of actions that can be applied to the particular data for this rule, to resolve the error.

Required Keys

name

type:

str

description:

The display text for the action.

callback

type:

function

description:

The function to call when the action is invoked.

Optional Keys

tooltip

type:

str

description:

Text to display as for the item action’s tooltip help messages.

dependencies

type:

dict<str>

description:

A dict of the valiation rule ids that this rule depends on and their display name. All dependency rules must be fixed before this rule can be fixed.

Parameters:

bundle (TankBundle) – (optional) The bundle instance for the app. If not specified, the current bundle will be retrieved.

static check_data(data)

Raise an exception if the data is not valid to create a ValidationRule object.

property id

Get the unique identifier for this rule.

property type

Get the ValidationRuleType of this rule.

property rule_type_name

Get the display name for the type of this rule.

property data_type

Get the data type that this rule peratins to.

property name

Get the display name for thsi rule.

property description

Get the description text for what this rule does.

property required

Get the property flag indicating if this rule should be executed to validate the data.

property manual

Get the property flag indicating if this rule cannot be automatically checked.

These types of rules must be manually validated by user.

property optional

Get the property flag indicating if this rule is optional.

property check_name

Get the display name for the check function of this rule.

property fix_name

Get the display name for the fix function of this rule.

property fix_tooltip

Get the text that describes what the fix function does for this rule.

property error_message

Get or set the text that describes how the current data errors.

property warn_message

Get or set the text that describes the current warnings.

property checked

Get the set the property flag indicating that an optional rule is checked (turned on).

This is meant to be used to set the UI check state for an optional rule.

property manual_checked

Get the set the property flag indicating that a manual rule is checked (user set as valid).

This is meant to be used to set the UI check state for a manual rule.

property check_func

Get the function that this rule executes to validate the data.

It is encouraged to use the exec_check method instead of getting this function and calling it directly.

property fix_func

Get the function that this rule executes to fix the data violations found by the rule.

It is encouraged to use the exec_fix method instead of getting this function and calling it directly.

property get_kwargs

Get the function that returns the extra keyword arguments dict to pass to the check and fix functions.

property actions

Get the list of actions that can be applied to all error items (as a group) for this rule.

These do no include the primary check or fix functions. This property is a list of dicts, which contain a name and callback keys, and optionally contains keys: tooltip.

property item_actions

Get the list of actions that can be applied invididual error items (one at a time) for this rule.

These do no include the primary check or fix functions. This property is a list of dicts, which contain a name and callback keys, and optionally contains keys: tooltip.

property valid

Get the valid state of the rule.

This will reflect the status returned by the rule’s check function the last time it was executed. If the value of this property is None, this indicates that the rule’s check function was not executed, or the rule’s valid state cannot be determined because at least one of the rule’s dependencies is not valid or could not be checked (due to one of its dependencies).

property errors

Get the error data for this rule, based on the last time its check function executed.

This will contain the error data items found by the rule’s check function the last time it was executed.

property error_count

Get the number of errors found by the rule’s check function the last time it was executed.

Validation checks may opt to return the error count instead of the error items for performance reasons.

property fix_executed

Get the flag indicating if the rule’s fix method was executed at least once.

property dependencies

Get the dependencies information for this rule.

Dependent rules must be fixed before this rule can be fixed. This defines the order that rules are fixed in, when fixing in bulk.

get_data(field)

Get the data from the rule.

Parameters:

field (str) – The field to get data for

Returns:

The data for the specified field

Return type:

any

get_actions_data(pre_validate=False)

Return the action data required to execute the action callback functions.

Parameters:

pre_validate (bool) – True will validate the rule before getting the errors to include in the action data. This ensures that the error data included is not stale.

Returns:

The action data required to execute the callback functions.

Return type:

List[dict]

get_error_item_ids()

Convenience method to get a list of the item ids from the data errors.

Returns:

The item ids of the error items.

Return type:

list

get_error_messages()

Return the list of current error messages.

If there was a run time error during the check or fix function, the error messages will contain these run time error messages. The default error message will not be included.

If the check and fix functions executed successfully, then return the default error message for the rule (e.g. assumes if the check/fix ran successfully than if there is an error, it will be due to finding actual validation errors related to the rule).

Returns:

The error messages.

Return type:

list

get_warning_messages()

Return the list of current warning messages.

get_dependency_ids()

Get the validation rules (ids) that this rule depends on.

Dependent rules must be fixed before this rule can be fixed. This defines the order that rules are fixed in, when fixing in bulk.

get_dependency_names()

Get the validation rules (display names) that this rule depends on.

Dependent rules must be fixed before this rule can be fixed. This defines the order that rules are fixed in, when fixing in bulk.

get_errors()

Execute this rule’s check function to get the most up to date error data.

The rule’s check function will be executed, the errors property will be updated with the check function’s result, and the result will be returned.

Returns:

The most up to date error data.

Return type:

list

set_failed_dependency(dependency_rule)

Set the failed dependency for this rule.

Set the failed dependency as None to indicate that this rule has no failed dependencies.

This value is used to determine if it is safe to execute the rule’s check and fix functions. If a dependency does not succeed, then the data may not be in a proper state for the dependent rule to act on; thus, attempting to execute the rule’s check or fix function on the data may yield incorrect results.

Parameters:

dependency_rule (ValidationRule) – The dependency rule that failed. Pass None to indicate that the rule has no failed dependencies.

has_failed_dependency()

Return True if this rule has a dependency that failed.

See set_failed_dependency for more information about the usage and purpose of this value.

exec_check(force=False)

Execute the rule’s check function.

It is reccommended to use this method to execute the rule’s check function, instead of directly invoking the check function, so that the rule’s properties are updated consistently after the check function is executed.

Parameters:

force (bool) – Set to True to run the check function no matter if there are failed dependencies. Set to False to only run the check if there there is not a failed dependency. Default is False.

Returns:

False is returned if failed to execute the check (there is a failed dependency or the check function threw an exception). None is returned if the rule does not have a check function. Otherwise, the result returned by the check function is sanitized by _process_check_result and returned.

Return type:

list | bool | None

exec_fix(pre_validate=True, force=False)

Execute the rule’s fix function.

It is reccommended to use this method to execute the rule’s fix function, instead of directly invoking the fix function, so that the rule’s properties are updated consistently after the fix function is executed.

Validate will run before executing the fix if pre_validate=True. It is encouraged to pre validate so that the error data is always retrieved right before running the fix, and the error data accurately reflects the current data. If not pre validated, then the fix will be applied to the error data that was retrieved the last time the validate was run (this requires user to always manually validate before fix, and ensure the error data reflects the current data before running the fix).

Fetching nor fixing dependencies is not handled in this method (see the ValidationManager resolve methods), though it will fail immediately if there are errors and it has the failed dependency property set.

Parameters:

• pre_validate (bool) – Set to True to run the rule’s validate function before fixing. This ensures the error data passed to the fix function accurately reflect the current data.

• force (bool) – Set to True to run the fix function no matter if there are failed dependencies. Set to False to only run the fix if there there is not a failed dependency. Default is False.

Returns:

The result of the fix function.

Return type:

bool

Raises:

Exception – If the fix operation was not successful.

reset()

Reset the state of the rule to its initial state.

Validation Widget

class tk_multi_data_validation.widgets.ValidationWidget(parent, group_rules_by=None, pre_validate_before_actions=True)

Bases: object

The main widget for the Data Validation App.

This widget displays the provided data validation rules, and provides the user interface to execute the rule check and fix functions. When data violations are found, a details widget will display the individual data items that violate the rules.

Create the validation widget.

Parameters:

• parent (QWidget) – The parent widget

• group_rules_by (str) – The validation rule field that the view will group rules by

• pre_validate_before_actions (bool) – True will run validation before executing actions so that the action callback acts on the most up to date error data. Default True. Default True.

property view_mode

Get or set the current view mode.

property group_rules_by

Get the field to group the validation rules by in the main view.

property validate_button

Get the validate all button.

This may be useful to disconnect the default callback for the fix all button clicked signal, to execute a custom validate all operation.

property fix_button

Get the fix all button.

This may be useful to disconnect the default callback for the fix all button clicked signal, to execute a custom fix all operation.

property publish_button

Get the publish button.

property validate_rules_callback

Get or set the custom callback triggered when the validate button is clicked.

This property must be a function that accepts a single parameter that is a ValidationRule object or a list of ValidationRule objects.

property validate_all_callback

Get or set the custom callback triggered when the validate button is clicked.

This property must be a function that accepts a single parameter that is a list of ValidationRule objects.

property fix_all_callback

Get or set the custom callback triggered when the fix button is clicked.

This property must be a function that accepts a single parameter that is a list of ValidationRule objects.

property fix_rules_callback

Get or set the custom callback triggered when the fix button is clicked.

This property must be a function that accepts a single parameter that is a single ValiationRule object or a list of ValidationRule objects.

property pre_validate_before_actions

Get or set the property that decides if validation is ran before executing actions on the current affected (error) objects.

save_state(settings_manager)

Save the widget state in the settings.

Parameters:

settings_manager (UserSettings) – The Toolkit settings object to save the widget settings to.

restore_state(settings_manager)

Restore the widget state from the settings.

Parameters:

settings_manager (UserSettings) – The Toolkit settings object to restore the widget settings to.

turn_on_details(on)

Turn details on to show the right-hand side details panel widget.

Parameters:

on (bool) – Set to True to turn on, or False to turn off.

turn_on_rule_type_filter(on)

Turn rule type filter on to show the left-hand side filter widget.

Parameters:

on (bool) – Set to True to turn on, or False to turn off.

set_validation_rules(validation_rules, validation_rule_types=None)

Set the validation rule types and data for the widget.

This will reinitialize the validation rule models with the given data.

Parameters:

• validation_rules (list<ValidationRule>) – The validation rules data

• validation_rule_types (list<ValidationRuleType>) – The type of validation rules to group the data by

get_active_rules()

Get the list of the validation rules that are currently active.

A validation rule is considered to be active if it is visible in the current view. Validation operations, like “Validate” and “Fix All”, may only be applied to active rules.

Returns:

The list of validation rules.

Return type:

list<ValidationRule>

show_validation_error(show=True, text=None)

Show the validation warning.

The validation warning indicates that the scene has changed since the last validation. Showing the validation warning will display a warning icon and text describing the warning.

Parameters:

• show (bool) – True will show the validation warning, False will hide it.

• text (str) – Additional warning details to display.

show_validation_warning(show=True, text=None)

Show the validation warning.

The validation warning indicates that the scene has changed since the last validation. Showing the validation warning will display a warning icon and text describing the warning.

Parameters:

• show (bool) – True will show the validation warning, False will hide it.

• text (str) – Additional warning details to display.

reset()

Reset the validation state of the widget.

on_validate_all()

Callback triggered when the validation all button has been triggered.

If the custom validate all callback is set, then get all rules from the model to resolve and pass it to the custom callback, else call the default validate all operation.

on_fix_all()

Callback triggered when the fix all button has been triggered.

If the custom fix all callback is set, then get all rules from the model to resolve and pass it to the custom callback, else call the default fix all operation.

on_validate_rules(rules, refresh_details=False)

Callback triggered to validate a specific set of rules.

Parameters:

• rule (VaildationRule | list<ValidationRule>) – The validation rule or list of rules to validate.

• refresh_details (bool) – Set to True to refresh the details widget after validation.

on_fix_rules(rules)

Callback triggered to fix a specific set of rules.

Parameters:

rule (VaildationRule | list<ValidationRule>) – The validation rule or list of rules to fix.

validate_rule_begin(rule)

Call this method before a validaiton rule is check function is executed.

Parameters:

rule (ValidationRule) – The rule that is about to start executing its check function.

validate_rule_finished(rule, update_rule_type=True)

Call this method after a validation rule check function has finished executing.

Parameters:

• rule (ValidationRule) – The rule that finished executing its check function.

• update_rule_type (bool) – True will update the rule type model data based on the updated rule.

validate_all_begin(rules=None)

Call this method before all validation rules are checked.

Parameters:

rules (List[ValidationRule]) – The list of rules that are about to be validated.

validate_all_finished()

Call this method after all validation rules have been checked.

fix_all_begin(rules=None)

Call this method before all validation rules are fixed.

Parameters:

rules (List[ValidationRule]) – The list of rules that are about to be fixed.

fix_all_finished()

Call this method after all validation rules have been fixed.

fix_rule_begin(rule)

Call this method before a validaiton rule is fix function is executed.

Parameters:

rule (ValidationRule) – The rule that is about to start executing its fix function.

fix_rule_finished(rule)

Call this method after a validation rule fix function has finished executing.

Parameters:

rule (ValidationRule) – The rule that finished executing its fix function.

rule_show_actions_callback(view, index, pos)

The validation rule action to show the list of action items was triggered.

Parameters:

• view (QAbstractItemView) – The view the index belongs to.

• index (sgtk.platform.qt.QtCore.QModelIndex) – The index to act on

• pos (sgtk.platform.qt.QtCore.QPoint) – The mouse position captured on triggered this callback

rule_check_action_callback(view, index, pos)

The validation rule action to execute the rule check function was triggered.

Parameters:

• view (QAbstractItemView) – The view the index belongs to.

• index (sgtk.platform.qt.QtCore.QModelIndex) – The index to act on

• pos (sgtk.platform.qt.QtCore.QPoint) – The mouse position captured on triggered this callback

rule_fix_action_callback(view, index, pos)

The validation rule action to execute the rule fix function was triggered.

Parameters:

• view (QAbstractItemView) – The view the index belongs to.

• index (sgtk.platform.qt.QtCore.QModelIndex) – The index to act on

• pos (sgtk.platform.qt.QtCore.QPoint) – The mouse position captured on triggered this callback