Uranium
Application Framework
Loading...
Searching...
No Matches
UM.Settings.SettingDefinition.SettingDefinition Class Reference

Public Member Functions

None __init__ (self, str key, Optional[DefinitionContainerInterface] container=None, Optional["SettingDefinition"] parent=None, Optional[i18nCatalog] i18n_catalog=None)
 
None extend_category (self, str value_id, str value_display, Optional[str] plugin_id=None, Optional[str] plugin_version=None)
 
Any __getattr__ (self, str name)
 
None __setattr__ (self, str name, Any value)
 
 __hash__ (self)
 
 __getstate__ (self)
 
 __setstate__ (self, state)
 
str key (self)
 
Optional[DefinitionContainerInterface] container (self)
 
Optional["SettingDefinition"] parent (self)
 
List["SettingDefinition"] children (self)
 
List["SettingRelation"] relations (self)
 
str serialize (self)
 
Set[str] getAllKeys (self)
 
Dict[str, Any] serialize_to_dict (self)
 
None deserialize (self, Union[str, Dict[str, Any]] serialized)
 
Optional["SettingDefinition"] getChild (self, str key)
 
bool matchesFilter (self, **Any kwargs)
 
List["SettingDefinition"] findDefinitions (self, **Any kwargs)
 
bool isAncestor (self, str key)
 
bool isDescendant (self, str key)
 
Set[str] getAncestors (self)
 
str __repr__ (self)
 
bool __eq__ (self, Any other)
 
None addSupportedProperty (cls, str name, DefinitionPropertyType property_type, bool required=False, bool read_only=False, Any default=None, Optional[str] depends_on=None)
 
List[str] getPropertyNames (cls, DefinitionPropertyType def_type=None)
 
bool hasProperty (cls, str name)
 
Optional[str] getPropertyType (cls, str name)
 
bool isRequiredProperty (cls, str name)
 
bool isReadOnlyProperty (cls, str name)
 
Optional[str] dependsOnProperty (cls, str name)
 
None addSettingType (cls, str type_name, Optional[Callable[[str], Any]] from_string, Callable[[Any], str] to_string, Optional[Validator] validator=None)
 
Any settingValueFromString (cls, str type_name, str string_value)
 
str settingValueToString (cls, str type_name, Any value)
 
Callable[[str], ValidatorgetValidatorForType (cls, str type_name)
 

Public Attributes

 key = set()
 
 children
 

Protected Member Functions

bool _matches1l8nProperty (self, str property_name, Any value, catalog)
 
None _deserialize_dict (self, Dict[str, Any] serialized)
 
Set[str] _updateAncestors (self)
 
Dict[str, "SettingDefinition"] _updateDescendants (self, "SettingDefinition" definition=None)
 

Protected Attributes

 _all_keys = set()
 
str _key = key
 
Optional[DefinitionContainerInterface] _container = container
 
Optional["SettingDefinition"] _parent = parent
 
 _i18n_catalog = i18n_catalog
 
list _children = []
 
list _relations = []
 

Detailed Description

Defines a single Setting with its properties.

This class defines a single Setting with all its properties. This class is considered immutable,
the only way to change it is using deserialize(). Should any state need to be stored for a definition,
create a SettingInstance pointing to the definition, then store the value in that instance.

== Supported Properties

The SettingDefinition class contains a concept of "supported properties". These are properties that
are supported when serializing or deserializing a setting. These properties are defined through the
addSupportedProperty() method. Each property needs a name and a type. In addition, there are two
optional boolean value to indicate whether the property is "required" and whether it is "read only".
Currently, four types of supported properties are defined. Please DefinitionPropertyType for a description
of these types.

Required properties are properties that should be present when deserializing a setting. If the property
is not present, an error will be raised. Read-only properties are properties that should never change
after creating a SettingDefinition. This means they cannot be stored in a SettingInstance object.

Constructor & Destructor Documentation

◆ __init__()

None UM.Settings.SettingDefinition.SettingDefinition.__init__ ( self,
str key,
Optional[DefinitionContainerInterface] container = None,
Optional["SettingDefinition"] parent = None,
Optional[i18nCatalog] i18n_catalog = None )
Construcutor

:param key: :type{string} The unique, machine readable/writable key to use for this setting.
:param container: :type{DefinitionContainerInterface} The container of this setting. Defaults to None.
:param parent: :type{SettingDefinition} The parent of this setting. Defaults to None.
:param i18n_catalog: :type{i18nCatalog} The translation catalog to use for this setting. Defaults to None.

Member Function Documentation

◆ __getattr__()

Any UM.Settings.SettingDefinition.SettingDefinition.__getattr__ ( self,
str name )
Override __getattr__ to provide access to definition properties.

◆ __getstate__()

UM.Settings.SettingDefinition.SettingDefinition.__getstate__ ( self)
For Pickle support.

This should be identical to Pickle's default behaviour but the default
behaviour doesn't combine well with a non-default __getattr__.

◆ __hash__()

UM.Settings.SettingDefinition.SettingDefinition.__hash__ ( self)
Ensure that the SettingDefinition is hashable, so it can be used in a set.

◆ __setattr__()

None UM.Settings.SettingDefinition.SettingDefinition.__setattr__ ( self,
str name,
Any value )
Override __setattr__ to enforce invariant status of definition properties.

◆ __setstate__()

UM.Settings.SettingDefinition.SettingDefinition.__setstate__ ( self,
state )
For Pickle support.

This should be identical to Pickle's default behaviour but the default
behaviour doesn't combine well with a non-default __getattr__.

◆ _deserialize_dict()

None UM.Settings.SettingDefinition.SettingDefinition._deserialize_dict ( self,
Dict[str, Any] serialized )
protected
protected:

Deserialize from a dictionary

◆ addSettingType()

None UM.Settings.SettingDefinition.SettingDefinition.addSettingType ( cls,
str type_name,
Optional[Callable[[str], Any]] from_string,
Callable[[Any], str] to_string,
Optional[Validator] validator = None )
Add a new setting type to the list of accepted setting types.

:param type_name: The name of the new setting type.
:param from_string: A function to call that converts to a proper value of this type from a string.
:param to_string: A function that converts a value of this type to a string.

◆ addSupportedProperty()

None UM.Settings.SettingDefinition.SettingDefinition.addSupportedProperty ( cls,
str name,
DefinitionPropertyType property_type,
bool required = False,
bool read_only = False,
Any default = None,
Optional[str] depends_on = None )
Define a new supported property for SettingDefinitions.

Since applications may want custom properties in their definitions, most properties are handled
dynamically. This allows the application to define what extra properties it wants to support.
Additionally, it can indicate whether a properties should be considered "required". When a
required property is not missing during deserialization, an AttributeError will be raised.

:param name: :type{string} The name of the property to define.
:param property_type: :type{DefinitionPropertyType} The type of property.
:param kwargs: Keyword arguments. Possible values:
:param required:     True if missing the property indicates an error should be raised. Defaults to False.
:param read_only:    True if the property should never be set on a SettingInstance. Defaults to False. Note
that for Function properties this indicates whether the result of the function should be stored.
:param default:      The default value for this property. This will be returned when the specified property
is not defined for this definition.
:param depends_on:   Key to another property that this property depends on; eg; if that value changes, this
value should be re-evaluated.

◆ children()

List["SettingDefinition"] UM.Settings.SettingDefinition.SettingDefinition.children ( self)
A list of children of this setting.

:return: :type{list<SettingDefinition>}

◆ container()

Optional[DefinitionContainerInterface] UM.Settings.SettingDefinition.SettingDefinition.container ( self)
The container of this setting.

:return:

◆ dependsOnProperty()

Optional[str] UM.Settings.SettingDefinition.SettingDefinition.dependsOnProperty ( cls,
str name )
Check if the specified property depends on another property

The value of certain properties can change if the value of another property changes. This is used to signify
that relation.

:param name: :type{string} The name of the property to check if it depends on another setting.

:return: :type{string} The property it depends on or None if it does not depend on another property.

◆ deserialize()

None UM.Settings.SettingDefinition.SettingDefinition.deserialize ( self,
Union[str, Dict[str, Any]] serialized )
Deserialize this setting from a string or dict.

:param serialized: :type{string or dict} A serialized representation of this setting.

◆ extend_category()

None UM.Settings.SettingDefinition.SettingDefinition.extend_category ( self,
str value_id,
str value_display,
Optional[str] plugin_id = None,
Optional[str] plugin_version = None )
Append a category to the setting.

:param value_id: :type{str} The id of the category.
:param value_display: :type{str} The display name of the category. If the display string needs to be translated, provide the translated string.
:param plugin_id: :type{Optional[str]} The id of the plugin that owns the category. Defaults to None.
:param plugin_version: :type{Optional[str]} The version of the plugin that owns the category. Defaults to None.

◆ findDefinitions()

List["SettingDefinition"] UM.Settings.SettingDefinition.SettingDefinition.findDefinitions ( self,
**Any kwargs )
Find all definitions matching certain criteria.

This will search this definition and its children for definitions matching the search criteria.

:param kwargs: :type{dict} A dictionary of keyword arguments that need to match properties of the children.

:return: :type{list} A list of children matching the search criteria. The list will be empty if no children
were found.

◆ getAllKeys()

Set[str] UM.Settings.SettingDefinition.SettingDefinition.getAllKeys ( self)
Gets the key of this setting definition and of all its descendants.

:return: A set of the key in this definition and all its descendants.

◆ getAncestors()

Set[str] UM.Settings.SettingDefinition.SettingDefinition.getAncestors ( self)
Get a set of keys representing the setting's ancestors.

◆ getChild()

Optional["SettingDefinition"] UM.Settings.SettingDefinition.SettingDefinition.getChild ( self,
str key )
Get a child by key

:param key: :type{string} The key of the child to get.

:return: :type{SettingDefinition} The child with the specified key or None if not found.

◆ getPropertyNames()

List[str] UM.Settings.SettingDefinition.SettingDefinition.getPropertyNames ( cls,
DefinitionPropertyType def_type = None )
Get the names of all supported properties.

:param type: :type{DefinitionPropertyType} The type of property to get the name of. Defaults to None which means all properties.

:return: A list of all the names of supported properties.

◆ getPropertyType()

Optional[str] UM.Settings.SettingDefinition.SettingDefinition.getPropertyType ( cls,
str name )
Get the type of a specified property.

:param name: :type{str} The name of the property to find the type of.

:return: DefinitionPropertyType corresponding to the type of the property or None if not found.

◆ getValidatorForType()

Callable[[str],Validator] UM.Settings.SettingDefinition.SettingDefinition.getValidatorForType ( cls,
str type_name )
Get the validator type for a certain setting type.

◆ hasProperty()

bool UM.Settings.SettingDefinition.SettingDefinition.hasProperty ( cls,
str name )
Check if a property with the specified name is defined as a supported property.

:param name: :type{string} The name of the property to check if it is supported.

:return: True if the property is supported, False if not.

◆ isAncestor()

bool UM.Settings.SettingDefinition.SettingDefinition.isAncestor ( self,
str key )
Check whether a certain setting is an ancestor of this definition.

:param key: :type{str} The key of the setting to check.

:return: True if the specified setting is an ancestor of this definition, False if not.

◆ isDescendant()

bool UM.Settings.SettingDefinition.SettingDefinition.isDescendant ( self,
str key )
Check whether a certain setting is a descendant of this definition.

:param key: :type{str} The key of the setting to check.

:return: True if the specified setting is a descendant of this definition, False if not.

◆ isReadOnlyProperty()

bool UM.Settings.SettingDefinition.SettingDefinition.isReadOnlyProperty ( cls,
str name )
Check if the specified property is considered a read-only property.

Read-only properties are properties that cannot have their value set in SettingInstance objects.

:param name: :type{string} The name of the property to check if it is read-only or not.

:return: True if the property is supported and is read-only, False if it is not required or is not part of the
list of supported properties.

◆ isRequiredProperty()

bool UM.Settings.SettingDefinition.SettingDefinition.isRequiredProperty ( cls,
str name )
Check if the specified property is considered a required property.

Required properties are checked when deserializing a SettingDefinition and if not present an error
will be reported.

:param name: :type{string} The name of the property to check if it is required or not.

:return: True if the property is supported and is required, False if it is not required or is not part of the
list of supported properties.

◆ key()

str UM.Settings.SettingDefinition.SettingDefinition.key ( self)
The key of this setting.

:return: :type{string}

◆ matchesFilter()

bool UM.Settings.SettingDefinition.SettingDefinition.matchesFilter ( self,
**Any kwargs )
Check if this setting definition matches the provided criteria.

:param kwargs: :type{dict} A dictionary of keyword arguments that need to match its attributes.

◆ parent()

Optional["SettingDefinition"] UM.Settings.SettingDefinition.SettingDefinition.parent ( self)
The parent of this setting.

:return: :type{SettingDefinition}

◆ relations()

List["SettingRelation"] UM.Settings.SettingDefinition.SettingDefinition.relations ( self)
A list of SettingRelation objects of this setting.

:return: :type{list<SettingRelation>}

◆ serialize()

str UM.Settings.SettingDefinition.SettingDefinition.serialize ( self)
Serialize this setting to a string.

:return: :type{string} A serialized representation of this setting.

◆ serialize_to_dict()

Dict[str, Any] UM.Settings.SettingDefinition.SettingDefinition.serialize_to_dict ( self)
Serialize this setting to a dict.

:return: :type{dict} A representation of this setting definition.

◆ settingValueFromString()

Any UM.Settings.SettingDefinition.SettingDefinition.settingValueFromString ( cls,
str type_name,
str string_value )
Convert a string to a value according to a setting type.

:param type_name: :type{string} The name of the type to convert to.
:param string_value: :type{string} The string to convert.

:return: The string converted to a proper value.

:exception ValueError: Raised when the specified type does not exist.

◆ settingValueToString()

str UM.Settings.SettingDefinition.SettingDefinition.settingValueToString ( cls,
str type_name,
Any value )
Convert a setting value to a string according to a setting type.

:param type_name: :type{string} The name of the type to convert from.
:param value: The value to convert.

:return: :type{string} The specified value converted to a string.

:exception ValueError: Raised when the specified type does not exist.

The documentation for this class was generated from the following file: