Uranium
Application Framework
UM.Settings.SettingDefinition.SettingDefinition Class Reference

Defines a single Setting with its properties. More...

Public Member Functions

None __init__ (self, str key, Optional[DefinitionContainerInterface] container=None, Optional["SettingDefinition"] parent=None, i18nCatalog i18n_catalog=None)
 Construcutor. More...
 
Any __getattr__ (self, str name)
 Override getattr to provide access to definition properties.
 
None __setattr__ (self, str name, Any value)
 Override setattr to enforce invariant status of definition properties.
 
def __getstate__ (self)
 For Pickle support. More...
 
def __setstate__ (self, state)
 For Pickle support. More...
 
str key (self)
 The key of this setting. More...
 
Optional[DefinitionContainerInterface] container (self)
 The container of this setting. More...
 
Optional["SettingDefinition"] parent (self)
 The parent of this setting. More...
 
List["SettingDefinition"] children (self)
 A list of children of this setting. More...
 
List["SettingRelation"] relations (self)
 A list of SettingRelation objects of this setting. More...
 
str serialize (self)
 Serialize this setting to a string. More...
 
Set[str] getAllKeys (self)
 Gets the key of this setting definition and of all its descendants. More...
 
Dict[str, Any] serialize_to_dict (self)
 Serialize this setting to a dict. More...
 
None deserialize (self, Union[str, Dict[str, Any]] serialized)
 Deserialize this setting from a string or dict. More...
 
Optional["SettingDefinition"] getChild (self, str key)
 Get a child by key. More...
 
bool matchesFilter (self, **Any kwargs)
 Check if this setting definition matches the provided criteria. More...
 
List["SettingDefinition"] findDefinitions (self, **Any kwargs)
 Find all definitions matching certain criteria. More...
 
bool isAncestor (self, str key)
 Check whether a certain setting is an ancestor of this definition. More...
 
bool isDescendant (self, str key)
 Check whether a certain setting is a descendant of this definition. More...
 
Set[str] getAncestors (self)
 Get a set of keys representing the setting's ancestors.
 
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)
 Define a new supported property for SettingDefinitions. More...
 
List[str] getPropertyNames (cls, DefinitionPropertyType type=None)
 Get the names of all supported properties. More...
 
bool hasProperty (cls, str name)
 Check if a property with the specified name is defined as a supported property. More...
 
Optional[str] getPropertyType (cls, str name)
 Get the type of a specified property. More...
 
bool isRequiredProperty (cls, str name)
 Check if the specified property is considered a required property. More...
 
bool isReadOnlyProperty (cls, str name)
 Check if the specified property is considered a read-only property. More...
 
str dependsOnProperty (cls, str name)
 Check if the specified property depends on another property. More...
 
None addSettingType (cls, str type_name, Callable[[str], Any] from_string, Callable[[Any], str] to_string, Validator validator=None)
 Add a new setting type to the list of accepted setting types. More...
 
Any settingValueFromString (cls, str type_name, str string_value)
 Convert a string to a value according to a setting type. More...
 
str settingValueToString (cls, str type_name, Any value)
 Convert a setting value to a string according to a setting type. More...
 
Callable[[str], ValidatorgetValidatorForType (cls, str type_name)
 Get the validator type for a certain setting type.
 

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,
i18nCatalog   i18n_catalog = None 
)

Construcutor.

Parameters
keystring The unique, machine readable/writable key to use for this setting.
containerDefinitionContainerInterface The container of this setting. Defaults to None.
parentSettingDefinition The parent of this setting. Defaults to None.
i18n_catalogi18nCatalog The translation catalog to use for this setting. Defaults to None.

Member Function Documentation

◆ __getstate__()

def 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.

◆ __setstate__()

def 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.

◆ addSettingType()

None UM.Settings.SettingDefinition.SettingDefinition.addSettingType (   cls,
str  type_name,
Callable[[str], Any]  from_string,
Callable[[Any],str]  to_string,
Validator   validator = None 
)

Add a new setting type to the list of accepted setting types.

Parameters
type_nameThe name of the new setting type.
from_stringA function to call that converts to a proper value of this type from a string.
to_stringA 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.

Parameters
namestring The name of the property to define.
property_typeDefinitionPropertyType The type of property.
kwargsKeyword arguments. Possible values:
requiredTrue if missing the property indicates an error should be raised. Defaults to False.
read_onlyTrue 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.
defaultThe default value for this property. This will be returned when the specified property is not defined for this definition.
depends_onKey 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.

Returns
list<SettingDefinition>

◆ container()

Optional[DefinitionContainerInterface] UM.Settings.SettingDefinition.SettingDefinition.container (   self)

The container of this setting.

Returns

◆ dependsOnProperty()

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.

Parameters
namestring The name of the property to check if it depends on another setting.
Returns
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.

Parameters
serializedstring or dict A serialized representation of this setting.

◆ 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.

Parameters
kwargsdict A dictionary of keyword arguments that need to match properties of the children.
Returns
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.

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

◆ getChild()

Optional["SettingDefinition"] UM.Settings.SettingDefinition.SettingDefinition.getChild (   self,
str  key 
)

Get a child by key.

Parameters
keystring The key of the child to get.
Returns
SettingDefinition The child with the specified key or None if not found.

◆ getPropertyNames()

List[str] UM.Settings.SettingDefinition.SettingDefinition.getPropertyNames (   cls,
DefinitionPropertyType   type = None 
)

Get the names of all supported properties.

Parameters
typeDefinitionPropertyType The type of property to get the name of. Defaults to None which means all properties.
Returns
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.

Parameters
namestr The name of the property to find the type of.
Returns
DefinitionPropertyType corresponding to the type of the property or None if not found.

◆ hasProperty()

bool UM.Settings.SettingDefinition.SettingDefinition.hasProperty (   cls,
str  name 
)

Check if a property with the specified name is defined as a supported property.

Parameters
namestring The name of the property to check if it is supported.
Returns
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.

Parameters
keystr The key of the setting to check.
Returns
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.

Parameters
keystr The key of the setting to check.
Returns
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.

Parameters
namestring The name of the property to check if it is read-only or not.
Returns
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.

Parameters
namestring The name of the property to check if it is required or not.
Returns
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.

Returns
string

◆ matchesFilter()

bool UM.Settings.SettingDefinition.SettingDefinition.matchesFilter (   self,
**Any  kwargs 
)

Check if this setting definition matches the provided criteria.

Parameters
kwargsdict 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.

Returns
SettingDefinition

◆ relations()

List["SettingRelation"] UM.Settings.SettingDefinition.SettingDefinition.relations (   self)

A list of SettingRelation objects of this setting.

Returns
list<SettingRelation>

◆ serialize()

str UM.Settings.SettingDefinition.SettingDefinition.serialize (   self)

Serialize this setting to a string.

Returns
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.

Returns
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.

Parameters
type_namestring The name of the type to convert to.
string_valuestring The string to convert.
Returns
The string converted to a proper value.
Exceptions
ValueErrorRaised 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.

Parameters
type_namestring The name of the type to convert from.
valueThe value to convert.
Returns
string The specified value converted to a string.
Exceptions
ValueErrorRaised when the specified type does not exist.

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