Granta MI Scripting Toolkit 4.2

Attribute values

Last update: 16.07.2025

class AttributeValue

Stores and provides access to attribute data values.

NOTE

Do not create new instances of this class; it represents a pre-existing database structure, and empty instances are provided when needed.

The attributes in a Record are represented in the MI Scripting Toolkit by AttributeDefinition objects, with an associated AttributeValue object containing the attribute’s data. AttributeValue is the base class, and each attribute type has a specialised class that inherits from it.

NOTE

The ‘Notes’ meta-attribute, common to all attributes, is not accessible through the MI Scripting Toolkit.

__init__(attr_def, _mi, record)

property value

Current value of the attribute. Can be modified.

  • Returns: Union[List[str], List[float], str, Dict[str, float], int, float, bool, bytes]

property record

Record in which the attribute value is defined. Would be None if the AttributeValue has been created outside a Record context, e.g. with Table.create_empty_attribute_value.

  • Returns: Record object or None

is_empty()

Checks whether the attribute value is populated.

  • Returns: bool

property definition

AttributeDefinition associated with this AttributeValue.

property id

Attribute identifier.

  • Returns: int

property is_meta

Whether the attribute is a meta-attribute.

  • Returns: bool

property is_meta_for

Name of the parent attribute, if a meta-attribute. Returns None if not.

  • Returns: str or None

property meta_attributes

Meta-attributes associated with this attribute. Does not make calls to the Service Layer.

property name

Attribute name.

  • Returns: str

property type

Attribute data type, as a four-character string. Possible attribute types are:

POIN = point,
RNGE = range,
FUNC = float functional,
INPT = integer,
LOGI = logical,
DISC = discrete,
STXT = short text,
LTXT = long text,
DTTM = date time,
HLNK = hyperlink,
PICT = picture,
FILE = file,
DSFN = discrete functional,
MAFN = maths functional (equations and logic),
TABL = tabular.

DSFN and MAFN are not supported by the MI Scripting Toolkit, and appear as UNSUPPORTED DATA TYPE.

  • Returns: str

property unit

Unit symbol.

  • Returns: str

property is_applicable

Whether the attribute is applicable to the current record. Setting this to False will clear any data values on the attribute.

  • Returns: bool

class AttributeBinary

Extended AttributeValue class to handle BinaryType objects as attribute data values.

Provides access to BinaryType object methods and properties.

__init__(attr_def, _mi, record)

property url

URL of the hosted file. Returns None if not populated.

The data can be retrieved by using a Python HTTP library (e.g. Requests, HTTPX) and by supplying the appropriate authentication for your Granta MI server.

To populate this property, the Table.bulk_fetch() method must be used with include_binary_data = False (default). If include_binary_data = True is specified, or if the attribute is fetched on-demand by accessing the attributes dictionary without performing a bulk fetch, this property will always return None.

  • Returns: str or None

property mime_file_type

MIME (Multipurpose Internet Mail Extensions) file type, if populated.

When exporting, this property is populated with the value of the MIME file type as determined by Granta MI.

When importing, this property is populated automatically by the load() method:

  • For Picture attributes, the MIME file type is determined by the image data.
  • For File attributes, this property is not used and is set to None.

Some commonly-used extensions are:

image/png - .png
image/gif - .gif
image/bmp - .bmp
image/tiff - .tif, .tiff
text/plain - .txt
application/zip - .zip
application/pdf - .pdf
application/vnd.ms-excel - .xls
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet - .xlsx
application/vnd.ms-powerpoint - .ppt
application/vnd.openxmlformats-officedocument.presentationml.presentation - .pptx
application/msword - .doc
application/vnd.openxmlformats-officedocument.wordprocessingml.document - .docx

  • Returns: str

is_empty()

Checks if the BinaryType object is populated by checking if it contains any binary data.

  • Returns: bool

property value

Returns the file as a bytes object, or None if unset.

  • Returns: bytes or None.

class AttributePicture

Extended AttributeBinary class for handling Picture objects.

Provides access to Picture save/load methods.

Pictures of up to 500 MB in size may be stored in Granta MI. To upload pictures larger than 20 Mb using Scripting Toolkit:

  • Granta MI Service Layer must be configured to allow large requests. If this is not configured, Session.update() will raise a GRANTA_ServiceLayerError for a “413 Request Entity Too Large” HTTP response. For more information, contact your Ansys technical representative.
  • The Python client environment must have sufficient system resources to load and Base64-encode the binary data. If there are insufficient system resources, unhandled Python exceptions may be raised.

__init__(attr_def, _mi, record)

save(path)

Wraps the Picture.save() method.

  • Parameters: path (Union [str , pathlib.Path ]) – Path where the image should be saved. Takes the form C:\\Users\\yourname\\Pictures\\image.jpg or /home/username/Pictures/image.jpg.
  • Returns: None

load(path)

Wraps the Picture.load() method (populates the Picture object with the specified image file).

  • Parameters: path (Union [str , pathlib.Path ]) – Path to the image file to load. Takes the form C:\\Users\\yourname\\Pictures\\image.jpg or /home/username/Pictures/image.jpg.
  • Returns: None

class AttributeFile

Extended AttributeBinary class to handle File objects.

Provides access to File object save/load methods, file name, and description.

Files of up to 500 MB in size may be stored in Granta MI. To upload files larger than 20 Mb using Scripting Toolkit:

  • Granta MI Service Layer must be configured to allow large requests. If this is not configured, Session.update() will raise a GRANTA_ServiceLayerError for a “413 Request Entity Too Large” HTTP response. For more information, contact your Ansys technical representative.
  • The Python client environment must have sufficient system resources to load and Base64-encode the binary data. If there are insufficient system resources, unhandled Python exceptions may be raised.

__init__(attr_def, _mi, record)

save(path)

Wraps the File.save() method.

  • Parameters: path (Union [str , pathlib.Path ]) – Path where the file should be saved. Takes the form C:\\Users\\yourname\\Documents\\file.pdf or /home/username/Documents/file.pdf.
  • Returns: None

load(path)

Wraps the File.load() method (populates the File object with the specified file).

  • Parameters: path – Union[str, pathlib.Path] (Path to the file to be imported. Takes the form C:\\Users\\yourname\\Documents\\file.pdf or /home/username/Documents/file.pdf.
  • Returns: None

property file_name

Name of the file associated with the File object. Displayed in MI applications.

  • Returns: str

property description

Description of the file displayed in MI applications.

  • Returns: str

class AttributeDate

Extended AttributeValue class for date attributes.

__init__(attr_def, _mi, record)

property value_as_string

Return the value of the date attribute as a string.

  • Returns: str | None

property value

Return the value of the date attribute as a datetime.datetime object.

class AttributeDiscrete

Extended AttributeValue class for discrete attributes.

Provides access to the list of strings that store the attribute’s data values, and their display order.

__init__(attr_def, _mi, record)

property value

Discrete value(s) associated with this attribute.

Versionchanged

Changed in version 4.1: Property value now validates the provided value against the attribute’s allowed discrete values. Check AttributeDefinitionDiscrete.discrete_values for available values. This validation is case-sensitive.

  • Returns: List[str] or str if not multivalued

property order

Display order of the discrete data values (strings) in MI Viewer. Order cannot be edited using the MI Scripting Toolkit.

  • Returns: Optional[List[int]]

property is_multivalued

Whether this attribute allows multiple values to be set.

  • Returns: bool

property possible_discrete_values

List of the attribute’s possible discrete data values.

  • Returns: List[str]

class AttributeFunctional

Extended AttributeValue class for functional data attributes.

Stores and provides access to a data structure, parameters (constraints), specified x-axis, and individual columns and series within the functional data attribute. Series and Gridded data are stored identically in AttributeFunctional objects. However, the two data types are imported into MI differently.

The AttributeFunctional object data structure is as follows:

[[ 'y min', 'y max', 'constraint 1', 'constraint 2', 'Estimated point?'],
 [  0.0,      0.0,      'Test',         0.5,       ,      False,       ],
 [   . ,       . ,         .  ,          . ,       ,        .  ,       ],
 [   . ,       . ,         .  ,          . ,       ,        .  ,       ],
 [   . ,       . ,         .  ,          . ,       ,        .  ,       ]]

The allowed data types are float for x-y data, float, str or None for constraints, and bool for flagging whether the data point is estimated or not.

The functional data type is used to store graphical data in Granta MI. In MI Viewer there are two ways to view the data: Series and Gridded.

  • Series data is grouped according to constraints or parameters placed on x-y data. The x-axis is a constraint that is specified on import. Each group (‘Series’) can have a different linestyle.
  • Gridded data is similar to Series data, except that the x-axis is dynamically chosen within MI Viewer, and all data groups share one linestyle.

__init__(attr_def, _mi, record)

update_header_units()

Updates the unit symbols in the header with the currently selected units.

  • Returns: None

property unit

Unit symbol for the y-axis.

To access the unit for the x-axis parameter or constraint parameters, use the unit property on the object returned by the xaxis_parameter or ParameterDefinition respectively.

  • Returns: str

clear()

Deletes all data stored in the AttributeFunctional object.

  • Returns: None

is_empty()

Checks whether any of the data values in the attribute are populated.

  • Returns: bool

add_point(columns)

Adds a point value to the AttributeFunctional object. Requires a dictionary with keys for the y-value, each constraint, and whether the value is estimated (optional):

  • Dictionary keys for the y-value can be either ‘y’, ‘Y’, the attribute name, or the attribute name prefixed with ‘Y ‘ and suffixed with the unit symbol in square brackets, i.e. formatted as in column_headers.
  • Constraint keys can be either the parameter name, or the parameter name with units.
  • Constraints are optional and can either be omitted entirely or set to None.
  • The key for whether the value is estimated must be ‘Estimated?’.

NOTE

The Estimated? flag can currently only be set for Gridded data, not Series.

  • Parameters: columns – Dict[str, Union[str, float, bool, int]]
  • Returns: None

add_range(columns)

Adds a range value to the AttributeFunctional object. Requires a dictionary with keys for the two y-values (ymin and ymax), each constraint, and whether the value is estimated (optional).

  • Dictionary keys for the y-value can be either ‘ymin’, ‘ymax’, or the attribute name with units and ‘Y min’ or ‘Y max’ appended.
  • Constraint keys can either be the parameter name, or the parameter name with units.
  • Constraints are optional and can either be omitted entirely or set to None.
  • The key for whether the value is estimated must be ‘Estimated?’.

NOTE

The Estimated? flag can currently only be set for Gridded data, not Series.

  • Parameters: columns – dict
  • Returns: None

property xaxis_parameter

AttributeParameter for the current x-axis parameter of the functional data attribute.

Modify the ParameterDefinition.unit property on the returned object to specify a different unit for import.

property column_headers

Column headers with units.

  • Returns: List[str]

property constraint_column_index

Mapping of columns to indices for functional data attributes.

  • Returns: Dict[str, int]

data_by_column()

Sorts data into columns (lists of values indexed by column name). Changing a dictionary generated using this method does not affect the underlying data, and data in the dictionary will not be refreshed automatically if the underlying data changes.

  • Returns: Dict[str, List[Any]]

property parameters

Parameters used by the functional data attribute, indexed by name.

Modify the ParameterDefinition.unit property on the returned objects to specify a different unit for import.

class FunctionalSeries

Extended AttributeFunctional class for Series functional data attributes.

Provides access to Series numbers and linestyles, and a method of generating a FunctionalGrid object from a FunctionalSeries object (generate_grid_version()).

__init__(attr_def, _mi, record)

generate_grid_version()

Creates a Gridded version of the FunctionalSeries object and returns a copy of it.

property data_with_series_number

Series number for all data points, returned as an additional column with the data values.

  • Returns: List[List[Union[str, float, bool, int]]]

property series_linestyles

Linestyles for each series (linestyle can be ‘Lines’, ‘Markers’, or ‘Both’).

  • Returns: Dict[int, str]

property log_yaxis

Whether the Y axis is using a logarithmic scale.

  • Returns: bool

class FunctionalGrid

Extended AttributeFunctional class for Gridded functional data attributes.

Provides access to linestyle and a method of generating a FunctionalSeries object from a FunctionalGrid object (generate_series_version()).

__init__(attr_def, _mi, record)

generate_series_version()

Creates a Series version of the FunctionalGrid object and returns a copy of it.

property linestyle

Linestyle for gridded functional data (gridded data can only have one linestyle: ‘Lines’, ‘Markers’, or ‘Both’).

  • Returns: str

Extended AttributeValue class for hyperlink attributes.

Provides access to the hyperlink_description and hyperlink_display text properties.

__init__(attr_def, _mi, record)

property object

Hyperlink attribute object value.

property value

Returns the URL as a string, or None if unset.

  • Returns: str or None.

Indicates how the hyperlink should be opened when clicked on in MI applications. Takes one of the following values:

  • New: Open in a new window or tab.
  • Top: Open in the current window or tab.
  • Content: Open within the current MI application (for example, in a frame or dialog).

Text which displays instead of the URL in MI applications.

  • Returns: str

class AttributeInteger

Extended AttributeValue class for integer attributes.

__init__(attr_def, _mi, record)

property value

Current value of the attribute. Can be modified.

  • Returns: Union[List[str], List[float], str, Dict[str, float], int, float, bool, bytes]

class AttributeLogical

Extended AttributeValue class for logical attributes.

__init__(attr_def, _mi, record)

class AttributePoint

Extended AttributeValue class for point data attributes.

Provides access to lists of point values and their parameters. Points can be multi-valued and are represented in the Streamlined API as lists of floats. They can have multiple parameters.

__init__(attr_def, _mi, record)

property is_multivalued

Whether this attribute allows multiple values to be set.

  • Returns: bool

is_empty()

Checks whether the attribute value is populated. AttributePoint objects are empty if the length of the list AttributePoint.value == 0.

  • Returns: bool

property is_estimated

Whether the value has been estimated.

Defaults to False for new attribute values.

return: bool

property parameter_definitions

Parameter definitions for the parameters associated with the point attribute, indexed by name.

Modify the ParameterDefinition.unit property on the returned objects to specify a different unit for import.

property parameters

Parameters associated with each point in AttributePoint.value. Each point has a dictionary, indexed by parameter name and containing the parameter value for that point.

  • Returns: List[Dict[str, Union[float, str]]]

property value

Point values associated with this attribute.

  • Returns: Union[List[float], float]

class AttributeRange

Extended AttributeValue class for range data attributes. Range attribute values are represented in the MI Scripting Toolkit by dictionaries of the form {'low': float, 'high': float}, and should be entered in this form when editing them.

__init__(attr_def, _mi, record)

property value

Current value of the attribute. Can be modified.

  • Returns: Union[List[str], List[float], str, Dict[str, float], int, float, bool, bytes]

property is_estimated

Whether the value has been estimated.

Defaults to False for new attribute values.

return: bool

property high_value_is_inclusive

Whether the high value is included in the range.

Defaults to True for new attribute values.

return: bool

property low_value_is_inclusive

Whether the low value is included in the range.

Defaults to True for new attribute values.

return: bool

class AttributeTabular

Extended AttributeValue class for tabular data attributes.

Provides access to tabular data and its properties, such as linking attribute and table, and methods for adding, deleting or swapping rows.

Importing a tabular attribute using Granta MI Scripting Toolkit replaces all data in the existing attribute. This can have implications if you use Data Updater to manage this data.

WARNING

Importing an empty tabular attribute is deprecated. To delete all rows in an existing tabular attribute, use the Record.clear_attributes method to delete the attribute value. To mark the attribute as Not Applicable, set the AttributeValue.is_applicable property to False.

Use the AttributeTabular.shape property to determine the current number of rows in the tabular attribute.

__init__(attr_def, _mi, record)

property columns

List of columns in the tabular data.

  • Returns: List[str]

property column_types

Data type in each column. Only populated for local, linked attribute, or linked column tabular columns. The element will be an empty string otherwise.

  • Example: ['STXT', 'POIN', 'DISC', '', '']
  • Returns: List[str]

property linked_columns

Whether each column is linked or not.

  • Returns: List[bool]

property linking_table

Table object which the linking attribute belongs to. Returns None for purely local tabular data.

  • Returns: Table object or None

property linking_attribute

Linking attribute, a short text-type attribute used to link rows in the tabular data attribute to records. Returns None for purely local tabular data.

property value

Raw data for the attribute. Data is organized as a list of lists:

  • The items in the outer list represent a row, and so the length of the outer list corresponds to the number of rows in the tabular attribute.
  • The items in each inner list represent a cell, and so the lengths of the inner lists correspond to the number of columns in the tabular attribute.

When exporting data as a read user, this property may omit rows for the following reasons:

  • If a row is completely empty.
  • If a row contains no local data and has a linking value which does not exist in the target table.
  • If a row contains no local data and has a linking value which exists in the target table, but all linked records are inaccessible to the user because of version control or access control.

When exporting data as a write user or above, this property will include all rows.

When assigning a value using this property, the number of items in the inner and outer lists must match the existing value. To modify the number of existing rows, use the AttributeTabular.add_row() and AttributeTabular.delete_row() methods before assigning a value.

property units

TabularUnits object associated with this AttributeTabular object.

show()

Displays the data as an ascii-art style table.

  • Returns: None

load()

Loads exported tabular data.

Exported data is generally lazily loaded by any property of the tabular that requires it. This method can be used to explicitly load the exported data or to discard staged user modifications and reset the attribute value to the exported data.

  • Returns: None

property linked_records

The records linked to each row, indexed by the linking value of each row at loading.

These links are calculated in Granta MI, and therefore cannot be edited by the user. The dictionary is unaffected by local changes to the tabular data, and the data must be re-imported to reflect local changes.

This property will be empty if the user cannot access the linked table, or if AttributeDefinitionTabular.ignore_linked_records was set to True before data export.

  • Returns: Dict[str, List[Record]]

is_empty()

Checks whether the attribute value is populated.

  • Returns: bool

property shape

Number of columns by number of rows.

  • Returns: Tuple[int, int]

add_row(linking_value='')

Inserts a new unpopulated row, and sets the linking value for that row if one is provided.

  • Parameters: linking_value – str
  • Returns: None

delete_row(index)

Removes the row at the specified index.

  • Example: delete_row(0) deletes the first row.
  • Parameters: index – int
  • Returns: None

swap_rows(row1, row2)

Change the positions of two rows with indices row1 and row2.

  • Example: my_data.swap_rows(0, 4) swaps the first and fifth rows in the Tabular data structure my_data.
  • Parameters:
    • row1 – int
    • row2 – int
  • Returns: None

class AttributeShortText

Extended AttributeValue class for short text attributes.

__init__(attr_def, _mi, record)

property value

Current value of the attribute. Can be modified.

  • Returns: Union[List[str], List[float], str, Dict[str, float], int, float, bool, bytes]

class AttributeLongText

Extended AttributeValue class for long text attributes.

__init__(attr_def, _mi, record)

class AttributeUnsupported

Extended AttributeValue class for attributes with unsupported data types.

Note that unsupported attribute data will not yield any information regarding its value in that record. However, some meta-data is still available through this class (such as the attribute’s name and data type). An unsupported attribute value remains unpopulated, and these objects cannot be edited.

__init__(attr_def, _mi, record)

property object

Gets the underlying UnsupportedType object representing the attribute value or the tabular cell. Does not allow access to the data.

property is_applicable

Whether the attribute is applicable to the current record. Setting this to False will clear any data values on the attribute.

  • Returns: bool

is_empty()

Checks whether the attribute value is populated.

  • Returns: bool

class PseudoAttributeValue

Stores and provides access to pseudo-attribute data values.

__init__(name, record)

  • Parameters:
    • name – str
    • record – Parent Record
  • Returns: None

property record

Parent Record described by the PseudoAttributeValue

property value

Current value of the pseudo-attribute. Cannot be modified. Modification of pseudo-attributes must be done through the Record object properties color, short_name and name.

property id

Attribute identifier (this is always 0 for pseudo-attributes).

  • Returns: int

is_empty()

Checks whether the pseudo-attribute value is populated or not.

  • Returns: bool

property name

Name of the pseudo-attribute.

  • Returns: str

property type

Data type of the pseudo-attribute value (four-character string).

  • Returns: str

Connect with Ansys