Class: QgsProperty

A store for object properties.

QgsProperty objects are used for storing properties for objects, which can then be transformed to a QVariant value by evaluating them against a supplied QgsExpressionContext. Multiple QgsProperty objects can be grouped using a QgsPropertyCollection for easier bulk storage, retrieval and evaluation.

QgsProperty objects are implicitly shared and can be inexpensively copied.

Enums

Type	alias of PropertyType

Methods

asExpression	Returns an expression string representing the state of the property, or an empty string if the property could not be converted to an expression
convertToTransformer	Attempts to convert an existing expression based property to a base expression with corresponding transformer.
expressionString	Returns the expression used for the property value.
field	Returns the current field name the property references.
isActive	Returns whether the property is currently active.
isProjectColor	Returns True if the property is set to a linked project color.
isStaticValueInContext	Returns True if the property is effectively a static value in the specified context.
loadVariant	Loads this property from a QVariantMap, wrapped in a QVariant.
prepare	Prepares the property against a specified expression context.
propertyType	Returns the property type.
referencedFields	Returns the set of any fields referenced by the property for a specified expression context.
setActive	Sets whether the property is currently active.
setExpressionString	Sets the expression to use for the property value.
setField	Sets the field name the property references.
setStaticValue	Sets the static value for the property.
setTransformer	Sets an optional transformer to use for manipulating the calculated values for the property.
staticValue	Returns the current static value for the property.
toVariant	Saves this property to a QVariantMap, wrapped in a QVariant.
transformer	Returns the existing transformer used for manipulating the calculated values for the property, if set.
value	Calculates the current value of the property, including any transforms which are set for the property
valueAsBool	Calculates the current value of the property and interprets it as an boolean.
valueAsColor	Calculates the current value of the property and interprets it as a color.
valueAsDateTime	Calculates the current value of the property and interprets it as a datetime.
valueAsDouble	Calculates the current value of the property and interprets it as a double.
valueAsInt	Calculates the current value of the property and interprets it as an integer.
valueAsString	Calculates the current value of the property and interprets it as a string.

Static Methods

fromExpression	Returns a new ExpressionBasedProperty created from the specified expression.
fromField	Returns a new FieldBasedProperty created from the specified field name.
fromValue	Returns a new StaticProperty created from the specified value.
propertyMapToVariantMap	Convert a map of QgsProperty to a map of QVariant This is useful to save a map of properties
variantMapToPropertyMap	Convert a map of QVariant to a map of QgsProperty This is useful to restore a map of properties.

class qgis.core.QgsProperty

Bases: object

__init__()

Constructor for a QgsProperty. The property will be set to an InvalidProperty type.

__init__(other: QgsProperty)

Parameters:

other (QgsProperty)

Type

alias of PropertyType

asExpression(self) → str

Returns an expression string representing the state of the property, or an empty string if the property could not be converted to an expression

Return type:

str

convertToTransformer(self) → bool

Attempts to convert an existing expression based property to a base expression with corresponding transformer. Returns True if conversion was successful. Note that calling this method requires multiple parsing of expressions, so it should only be called in non-performance critical code.

Return type:

bool

expressionString(self) → str

Returns the expression used for the property value. If the property is not a ExpressionBasedProperty this will return an empty string.

See also

setExpressionString()

Return type:

str

field(self) → str

Returns the current field name the property references. If the property is not a FieldBasedProperty this will return an empty string.

See also

setField()

Return type:

str

static fromExpression(expression: str | None, isActive: bool = True) → QgsProperty

Returns a new ExpressionBasedProperty created from the specified expression.

Parameters:

• expression (Optional[str])

• isActive (bool = True)

Return type:

QgsProperty

static fromField(fieldName: str | None, isActive: bool = True) → QgsProperty

Returns a new FieldBasedProperty created from the specified field name.

Parameters:

• fieldName (Optional[str])

• isActive (bool = True)

Return type:

QgsProperty

static fromValue(value: Any, isActive: bool = True) → QgsProperty

Returns a new StaticProperty created from the specified value.

Parameters:

• value (Any)

• isActive (bool = True)

Return type:

QgsProperty

isActive(self) → bool

Returns whether the property is currently active.

See also

setActive()

Return type:

bool

isProjectColor(self) → bool

Returns True if the property is set to a linked project color.

Added in version 3.6.

Return type:

bool

isStaticValueInContext(self, context: QgsExpressionContext)

Returns True if the property is effectively a static value in the specified context.

I.e. if the property type is QgsProperty.ExpressionBasedProperty with a fixed value expression (‘some static value’), this method will return True.

Parameters:

context (QgsExpressionContext) -> (bool) – expression context

Returns:

• True if property is a static value

• staticValue: evaluated static value if property is effectively a static value

Added in version 3.24.

loadVariant(self, property: Any) → bool

Loads this property from a QVariantMap, wrapped in a QVariant. You can use QgsXmlUtils.readVariant to load it from an XML document.

See also

toVariant()

Parameters:

property (Any)

Return type:

bool

prepare(self, context: QgsExpressionContext = QgsExpressionContext()) → bool

Prepares the property against a specified expression context. Calling prepare before evaluating the property multiple times allows precalculation of expensive setup tasks such as parsing expressions. Returns True if preparation was successful.

Parameters:

context (QgsExpressionContext = QgsExpressionContext())

Return type:

bool

static propertyMapToVariantMap(propertyMap: Dict[str | None, QgsProperty]) → Dict[str, Any]

Convert a map of QgsProperty to a map of QVariant This is useful to save a map of properties

Added in version 3.20.

Parameters:

propertyMap (Dict[Optional[str], QgsProperty])

Return type:

Dict[str, Any]

propertyType(self) → Qgis.PropertyType

Returns the property type.

Return type:

Qgis.PropertyType

referencedFields(self, context: QgsExpressionContext = QgsExpressionContext(), ignoreContext: bool = False) → Set[str]

Returns the set of any fields referenced by the property for a specified expression context.

Note

The optional argument ignoreContext has been added in QGIS 3.14. When set to True, even fields not set in context’s fields() will be reported - this is useful e.g. with vector tiles where the actual available field names may not be known beforehand.

Parameters:

• context (QgsExpressionContext = QgsExpressionContext())

• ignoreContext (bool = False)

Return type:

Set[str]

setActive(self, active: bool)

Sets whether the property is currently active.

See also

isActive()

Parameters:

active (bool)

setExpressionString(self, expression: str | None)

Sets the expression to use for the property value. Calling this will transform the property into an ExpressionBasedProperty.

See also

expressionString()

Parameters:

expression (Optional[str])

setField(self, field: str | None)

Sets the field name the property references. Calling this will transform the property into an FieldBasedProperty.

See also

field()

Parameters:

field (Optional[str])

setStaticValue(self, value: Any)

Sets the static value for the property. Calling this will transform the property into an StaticProperty.

See also

staticValue()

Parameters:

value (Any)

setTransformer(self, transformer: QgsPropertyTransformer | None)

Sets an optional transformer to use for manipulating the calculated values for the property.

Parameters:

transformer (Optional[QgsPropertyTransformer]) – transformer to install. Ownership is transferred to the property, and any existing transformer will be deleted. Set to None to remove an existing transformer.

See also

transformer()

staticValue(self) → Any

Returns the current static value for the property. If the property is not a StaticProperty this will return an invalid variant.

See also

setStaticValue()

Return type:

Any

toVariant(self) → Any

Saves this property to a QVariantMap, wrapped in a QVariant. You can use QgsXmlUtils.writeVariant to save it to an XML document.

See also

loadVariant()

Return type:

Any

transformer(self) → QgsPropertyTransformer | None

Returns the existing transformer used for manipulating the calculated values for the property, if set.

See also

setTransformer()

Return type:

Optional[QgsPropertyTransformer]

value(self, context: QgsExpressionContext, defaultValue: Any = None)

Calculates the current value of the property, including any transforms which are set for the property

Parameters:

• context (QgsExpressionContext) – QgsExpressionContext to evaluate the property for. The variables and functions contained in the expression context can be used to alter the calculated value for the property, so that a property is able to respond to the current environment, layers and features within QGIS.

• defaultValue (Any = None) -> (Any) – default value to return if the property is not active or cannot be calculated

Returns:

• calculated value for property

• ok: True if conversion was successful

See also

valueAsString()

See also

valueAsColor()

See also

valueAsDouble()

See also

valueAsInt()

See also

valueAsBool()

valueAsBool(self, context: QgsExpressionContext, defaultValue: bool = False)

Calculates the current value of the property and interprets it as an boolean.

Parameters:

• context (QgsExpressionContext) – QgsExpressionContext to evaluate the property for.

• defaultValue (bool = False) -> (bool) – default boolean to return if the property cannot be calculated as an boolean

Returns:

• value parsed to boolean

• ok: True if conversion was successful

See also

value()

See also

valueAsDateTime()

See also

valueAsString()

See also

valueAsColor()

See also

valueAsDouble()

See also

valueAsInt()

valueAsColor(self, context: QgsExpressionContext, defaultColor: QColor | Qt.GlobalColor = QColor())

Calculates the current value of the property and interprets it as a color.

Parameters:

• context (QgsExpressionContext) – QgsExpressionContext to evaluate the property for.

• defaultColor (Union[QColor, Qt.GlobalColor] = QColor()) -> (QColor) – default color to return if the property cannot be calculated as a color

Returns:

• value parsed to color

• ok: True if conversion was successful

See also

value()

See also

valueAsDateTime()

See also

valueAsString()

See also

valueAsDouble()

See also

valueAsInt()

See also

valueAsBool()

valueAsDateTime(self, context: QgsExpressionContext, defaultDateTime: QDateTime | datetime.datetime = QDateTime())

Calculates the current value of the property and interprets it as a datetime.

Parameters:

• context (QgsExpressionContext) – QgsExpressionContext to evaluate the property for.

• defaultDateTime (Union[QDateTime, datetime.datetime] = QDateTime()) -> (QDateTime) – default datetime to return if the property cannot be calculated as a datetime

Returns:

• value parsed to datetime

• ok: True if conversion was successful

See also

value()

See also

valueAsString()

See also

valueAsColor()

See also

valueAsDouble()

See also

valueAsInt()

See also

valueAsBool()

Added in version 3.14.

valueAsDouble(self, context: QgsExpressionContext, defaultValue: float = 0)

Calculates the current value of the property and interprets it as a double.

Parameters:

• context (QgsExpressionContext) – QgsExpressionContext to evaluate the property for.

• defaultValue (float = 0) -> (float) – default double to return if the property cannot be calculated as a double

Returns:

• value parsed to double

• ok: True if conversion was successful

See also

value()

See also

valueAsDateTime()

See also

valueAsString()

See also

valueAsColor()

See also

valueAsInt()

See also

valueAsBool()

valueAsInt(self, context: QgsExpressionContext, defaultValue: int = 0)

Calculates the current value of the property and interprets it as an integer.

Parameters:

• context (QgsExpressionContext) – QgsExpressionContext to evaluate the property for.

• defaultValue (int = 0) -> (int) – default integer to return if the property cannot be calculated as an integer

Returns:

• value parsed to integer

• ok: True if conversion was successful

See also

value()

See also

valueAsDateTime()

See also

valueAsString()

See also

valueAsColor()

See also

valueAsDouble()

See also

valueAsBool()

valueAsString(self, context: QgsExpressionContext, defaultString: str | None = '')

Calculates the current value of the property and interprets it as a string.

Parameters:

• context (QgsExpressionContext) – QgsExpressionContext to evaluate the property for.

• defaultString (Optional[str] = '') -> (str) – default string to return if the property cannot be calculated as a string

Returns:

• value parsed to string

• ok: True if conversion was successful

See also

value()

See also

valueAsDateTime()

See also

valueAsColor()

See also

valueAsDouble()

See also

valueAsInt()

See also

valueAsBool()

static variantMapToPropertyMap(variantMap: Dict[str, Any]) → Dict[str, QgsProperty]

Convert a map of QVariant to a map of QgsProperty This is useful to restore a map of properties. The properties are created using QgsProperty.loadVariant

Added in version 3.20.

Parameters:

variantMap (Dict[str, Any])

Return type:

Dict[str, QgsProperty]