Skip to content

Migrate parameter

When a PythonPart is extended by renaming, adding, or deleting of parameters, it's possible to migrate the parameter data from an older PythonPart version to the new parameter structure.

To do this, the function migrate_parameter() must be implemented in the script. It will then be called every time a PythonPart is run in modification mode (e.g., when modifying an existing PythonPart with a double click). The implementation must be done as follows:

def migrate_parameter(parameter_list: List[str],
                      version       : float):
    """ migrate the parameter

    Args:
        parameter_list: parameter list
        version:        PythonPart version
    """

Version check

As the PythonPart version is passed as a float in the argument version, a check if the migration is necessary can be done in the script like this:

if version < 1.9:
    return

Parameter conversion

With the argument parameter_list all the arguments are passed to the function as a list, where in each entry a parameter is represented with a string (regardless its value type, e.g., like this: Radius=500.0\n). The conversion of the parameters can be done using the functions provided in the BuildingElementMigrationUtil or by a custom migration implementation.

Example

Let's say with the version 2.0 we did following changes in our PythonPart:

  • the parameter Minor was renamed to MinorRadius
  • the parameter Major was renamed to MajorDiameter
  • the value of the new parameter MajorDiameter must be doubled, as it now represents a diameter instead of radius

Here is how the migration can be implemented:

def migrate_parameter(parameter_list: List[str],
                      version       : float):
    if version < 1.9:
        return

    BuildingElementMigrationUtil.\
        transfer_parameter_value(parameter_list =  parameter_list,
                                 old_element_id =  "",#(1)!
                                 old_value_name =  "Minor",
                                 new_element_id =  "",
                                 new_value_name =  "MinorRadius")

    BuildingElementMigrationUtil.\
        transfer_parameter_value(parameter_list =      parameter_list,
                                 old_element_id =      "",
                                 old_value_name =      "Major",
                                 new_element_id =      "",
                                 new_value_name =      "MajorDiameter",
                                 converter_function =  lambda value: str(float(value) * 2)) #(2)!
  1. In case of operating with more than one BuildingElement objects (more than one .pyp file for palette and PythonPart creation), a parameter can be migrated from one BuildingElement object to another. In this case (and in 99% of other) there is only one .pyp file, so we provide an empty string here.
  2. As a conversion of a parameter value was necessary, conversion function must be provided as an argument. This conversion function must be defined as conversion_function(value: str) -> str, meaning the input as well as output value must always be a string, regardless of what type of parameter value is converted.

The complete implementation of the parameter migration is shown in the example Cone:

  • ..\etc\Examples\GeometryExamples\Cone.pyp
  • ..\etc\PythonPartsExampleScripts\GeometryExamples\Cone.py