Uranium
Application Framework
Loading...
Searching...
No Matches
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.
 
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.
 
 __hash__ (self)
 
 __getstate__ (self)
 
 __setstate__ (self, state)
 
str key (self)
 The key of this setting.
 
Optional[DefinitionContainerInterface] container (self)
 The container of this setting.
 
Optional["SettingDefinition"] parent (self)
 The parent of this setting.
 
List["SettingDefinition"] children (self)
 A list of children of this setting.
 
List["SettingRelation"] relations (self)
 A list of SettingRelation objects of this setting.
 
str serialize (self)
 Serialize this setting to a string.
 
Set[str] getAllKeys (self)
 
Dict[str, Any] serialize_to_dict (self)
 
None deserialize (self, Union[str, Dict[str, Any]] serialized)
 Deserialize this setting from a string or dict.
 
Optional["SettingDefinition"] getChild (self, str key)
 Get a child by key.
 
bool matchesFilter (self, **Any kwargs)
 
List["SettingDefinition"] findDefinitions (self, **Any kwargs)
 
bool isAncestor (self, str key)
 Check whether a certain setting is an ancestor of this definition.
 
bool isDescendant (self, str key)
 Check whether a certain setting is a descendant of this definition.
 
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.
 
List[str] getPropertyNames (cls, DefinitionPropertyType def_type=None)
 
bool hasProperty (cls, str name)
 
Optional[str] getPropertyType (cls, str name)
 Get the type of a specified property.
 
bool isRequiredProperty (cls, str name)
 Check if the specified property is considered a required property.
 
bool isReadOnlyProperty (cls, str name)
 Check if the specified property is considered a read-only property.
 
Optional[str] dependsOnProperty (cls, str name)
 
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.
 
Any settingValueFromString (cls, str type_name, str string_value)
 Convert a string to a value according to a setting type.
 
str settingValueToString (cls, str type_name, Any value)
 Convert a setting value to a string according to a setting type.
 
Callable[[str], ValidatorgetValidatorForType (cls, str type_name)
 Get the validator type for a certain setting type.
 

Public Attributes

 key
 

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
 
 _key
 
 _container
 
 _parent
 
 _i18n_catalog
 
 _children
 
 _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,
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__()

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.

◆ __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,
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()

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.

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.

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

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

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.

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

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

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.

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

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: