Variable Register

Manages custom variable data for report design and generation.

CplusVariableInfo dataclass

CplusVariableInfo(name, init_value, default_value, final_value)

Contains information about a CPLUS variable within a layout scope.

update_final_value

update_final_value(context)

Computes the final value of the variable to be used in the layout.

Default implementation does nothing.

Parameters:

Name	Type	Description	Default
context	BaseReportContext	Report context object used to compute the final variable value.	required

Source code in src/cplus_plugin/lib/reports/variables.py

def update_final_value(self, context: BaseReportContext):
    """Computes the final value of the variable to be used
    in the layout.

    Default implementation does nothing.

    :param context: Report context object used to compute the
    final variable value.
    :type context: ReportContext
    """
    pass

LayoutVariableRegister

LayoutVariableRegister()

Manages variables and their corresponding values for use in layout design and report generation.

Source code in src/cplus_plugin/lib/reports/variables.py

def __init__(self):
    self._var_infos = {}
    self._init_vars()

var_name_init_values property

var_name_init_values

Creates a collection of variable names and their corresponding initial values.

Returns:

Type	Description
dict	Collection of variable names and corresponding initial values.

variable_names property

variable_names

Gets the names of the registered variables.

Returns:

Type	Description
list	A collection of registered variable names.

is_analysis_report

is_analysis_report(layout)

Checks whether the layout has been produced from a report generation process.

Parameters:

Name	Type	Description	Default
layout	QgsPrintLayout	Layout to check whether its from a report generation process.	required

Returns:

Type	Description
bool	True if the layout is from a report generation process, else False.

Source code in src/cplus_plugin/lib/reports/variables.py

def is_analysis_report(self, layout: QgsPrintLayout) -> bool:
    """Checks whether the layout has been produced from a report
    generation process.

    :param layout: Layout to check whether its from a report
    generation process.
    :type layout: QgsPrintLayout

    :returns: True if the layout is from a report generation
    process, else False.
    :rtype: bool
    """
    return layout.customProperty(self.VAR_CPLUS_REPORT_PROPERTY, False)

register_variables

register_variables(layout)

Registers custom variables and their corresponding initial values in the layout.

Parameters:

Name	Type	Description	Default
layout	QgsPrintLayout	Layout object where the custom variables will be registered.	required

Source code in src/cplus_plugin/lib/reports/variables.py

def register_variables(self, layout: QgsPrintLayout):
    """Registers custom variables and their corresponding
    initial values in the layout.

    :param layout: Layout object where the custom
    variables will be registered.
    :type layout: QgsPrintLayout
    """
    # If layout from analysis process, do not register
    # the variables.
    if self.is_analysis_report(layout):
        return

    # Remove any duplicate cplus variable names and values
    var_names, var_values = self.remove_variables(layout)

    # Get cplus variable names and corresponding initial values
    var_name_init_values = self.var_name_init_values
    for var_name, init_value in var_name_init_values.items():
        var_names.append(var_name)
        var_values.append(init_value)

    layout.setCustomProperty(self.VAR_NAMES_PROPERTY, var_names)
    layout.setCustomProperty(self.VAR_VALUES_PROPERTY, var_values)

remove_var_name_in_collection classmethod

remove_var_name_in_collection(cplus_var_name, layout_var_names, layout_var_values)

Remove cplus variable name matches and corresponding values in the layout variable name/value mapping.

Source code in src/cplus_plugin/lib/reports/variables.py

@classmethod
def remove_var_name_in_collection(
    cls,
    cplus_var_name: str,
    layout_var_names: typing.List[str],
    layout_var_values: typing.List[str],
):
    """Remove cplus variable name matches and corresponding
    values in the layout variable name/value mapping.
    """
    while cplus_var_name in layout_var_names:
        idx = layout_var_names.index(cplus_var_name)
        _ = layout_var_names.pop(idx)
        _ = layout_var_values.pop(idx)

remove_variables

remove_variables(layout)

Removes duplicate variable names from the layout, this is done prior to registering new ones.

Parameters:

Name	Type	Description	Default
layout	QgsPrintLayout	Layout whose cplus variables are to be removed.	required

Returns:

Type	Description
tuple	Tuple only containing non-cplus variable names and corresponding values respectively.

Source code in src/cplus_plugin/lib/reports/variables.py

def remove_variables(
    self, layout: QgsPrintLayout
) -> typing.Tuple[typing.List, typing.List]:
    """Removes duplicate variable names from the layout,
    this is done prior to registering new ones.

    :param layout: Layout whose cplus variables are to be removed.
    :type layout: QgsPrintLayout

    :returns: Tuple only containing non-cplus variable names
    and corresponding values respectively.
    :rtype: tuple
    """
    cplus_var_names = self.variable_names
    var_names = layout.customProperty(self.VAR_NAMES_PROPERTY, list())
    var_values = layout.customProperty(self.VAR_VALUES_PROPERTY, list())

    # Remove only cplus variable names and values
    for cvn in cplus_var_names:
        self.remove_var_name_in_collection(cvn, var_names, var_values)

    return var_names, var_values

set_report_flag

set_report_flag(layout)

Set a flag indicating that the layout has been produced from a report generation process.

Parameters:

Name	Type	Description	Default
layout	QgsPrintLayout	Layout to add the flag as a custom property.	required

Source code in src/cplus_plugin/lib/reports/variables.py

def set_report_flag(self, layout: QgsPrintLayout):
    """Set a flag indicating that the layout has been produced
    from a report generation process.

    :param layout: Layout to add the flag as a custom property.
    :type layout: QgsPrintLayout
    """
    layout.setCustomProperty(self.VAR_CPLUS_REPORT_PROPERTY, True)

update_variables

update_variables(layout, context)

Update the values for the CPLUS variables in the layout.

Parameters:

Name	Type	Description	Default
layout	QgsPrintLayout	Layout object whose CPLUS variable values will be updated.	required
context	BaseReportContext	Context object containing the report information that will be used for computing the final value of the variable during the report generation process.	required

Source code in src/cplus_plugin/lib/reports/variables.py

def update_variables(self, layout: QgsPrintLayout, context: BaseReportContext):
    """Update the values for the CPLUS variables in the layout.

    :param layout: Layout object whose CPLUS variable values
    will be updated.
    :type layout: QgsPrintLayout

    :param context: Context object containing the report information that
    will be used for computing the final value of the variable during
    the report generation process.
    :type context: ReportContext
    """
    exp_scope = QgsExpressionContextUtils.layoutScope(layout)
    var_names = exp_scope.variableNames()
    var_values = []
    vn = list(self._var_infos.keys())
    for name in var_names:
        if name in self._var_infos:
            var_info = self._var_infos[name]
            var_info.update_final_value(context)
            var_values.append(var_info.final_value)
        else:
            if not exp_scope.hasVariable(name):
                continue
            value = exp_scope.variable(name)
            var_values.append(value)

    layout.setCustomProperty(self.VAR_NAMES_PROPERTY, var_names)
    layout.setCustomProperty(self.VAR_VALUES_PROPERTY, var_values)
    layout.refresh()

NoneValueSettingsVariableInfo dataclass

NoneValueSettingsVariableInfo(name, init_value, default_value, final_value, settings_type)

Bases: SettingsVariableInfo

Sets final value as "N/A" if there is no text specified in the settings.

update_final_value

update_final_value(context)

Computes the final value of the variable to be used in the layout.

Fetches the latest settings value.

Parameters:

Name	Type	Description	Default
context	BaseReportContext	Report context object used to compute the final variable value.	required

Source code in src/cplus_plugin/lib/reports/variables.py

def update_final_value(self, context: BaseReportContext):
    """Computes the final value of the variable to be used
    in the layout.

    Fetches the latest settings value.

    :param context: Report context object used to compute the
    final variable value.
    :type context: ReportContext
    """
    settings_value = self._get_setting_value()
    self.final_value = settings_value if settings_value else tr("N/A")

ScenarioDescriptionVariableInfo dataclass

ScenarioDescriptionVariableInfo(name, init_value, default_value, final_value)

Bases: CplusVariableInfo

Metadata for a scenario description variable.

update_final_value

update_final_value(context)

Set the scenario description.

Source code in src/cplus_plugin/lib/reports/variables.py

def update_final_value(self, context: BaseReportContext):
    """Set the scenario description."""
    if hasattr(context, "scenario"):
        self.final_value = context.scenario.name

ScenarioNameVariableInfo dataclass

ScenarioNameVariableInfo(name, init_value, default_value, final_value)

Bases: CplusVariableInfo

Metadata for a scenario name variable.

update_final_value

update_final_value(context)

Set the scenario name.

Source code in src/cplus_plugin/lib/reports/variables.py

def update_final_value(self, context: BaseReportContext):
    """Set the scenario name."""
    if hasattr(context, "scenario"):
        self.final_value = context.scenario.name

SettingsVariableInfo dataclass

SettingsVariableInfo(name, init_value, default_value, final_value, settings_type)

Bases: CplusVariableInfo

Metadata for a settings-related variable.

update_final_value

update_final_value(context)

Computes the final value of the variable to be used in the layout.

Fetches the latest settings value.

Parameters:

Name	Type	Description	Default
context	BaseReportContext	Report context object used to compute the final variable value.	required

Source code in src/cplus_plugin/lib/reports/variables.py

def update_final_value(self, context: BaseReportContext):
    """Computes the final value of the variable to be used
    in the layout.

    Fetches the latest settings value.

    :param context: Report context object used to compute the
    final variable value.
    :type context: ReportContext
    """
    self.final_value = self._get_setting_value()

create_bulleted_text

create_bulleted_text(main_text, bulleted_items)

Returns string containing text and bulleted/dashed text below it.

Parameters:

Name	Type	Description	Default
main_text	str	Primary non-bulleted text.	required
bulleted_items	List[str]	List containing bulleted items that will be rendered below the main text.	required

Returns:

Type	Description
str	Text containing primary text with bulleted items below it.

Source code in src/cplus_plugin/lib/reports/variables.py

def create_bulleted_text(main_text: str, bulleted_items: typing.List[str]) -> str:
    """Returns string containing text and bulleted/dashed text
    below it.

    :param main_text: Primary non-bulleted text.
    :type main_text: str

    :param bulleted_items: List containing bulleted items that will
    be rendered below the main text.
    :type bulleted_items: list

    :returns: Text containing primary text with bulleted items
    below it.
    :rtype: str
    """
    bulleted_items = "\n- ".join(bulleted_items)

    if not main_text:
        return f"- {bulleted_items}"

    return f"{main_text}\n- {bulleted_items}"

---

Last update: October 2, 2024