mstrio > object_management > translation

class mstrio.object_management.translation.Translation(translation_target_id, translation_target_name, translation_values)

Bases: Dictable

Translation class represents a translation for an Object. It also contains methods to create, alter and delete translations for all Object types including ones not yet supported by mstrio-py

Parameters:

  • translation_target_id (str) –

  • translation_target_name (str) –

  • translation_values (list[TranslationValue]) –

translation_target_id

ID of the part of the Object the translations are for

Type:

str

translation_target_name

name of the part of the Object the translations are for

Type:

str

translation_values

list of translation values for the part of the Object

Type:

list[Translation.TranslationValues]

class OperationData(target_language, target_id, value=None)

Bases: object

Object that specifies data for a single Operation on a Translation.

Parameters:

  • target_language (Language | str | int) –

  • target_id (str) –

  • value (str | None) –

target_language

one of the following: - lcid attribute of the language - ID of the language - Language class object

Type:

Language | str | int

target_id

ID of the specific part of the Object to be translated

Type:

str

value

value of the change, not necessary when deleting a translation

Type:

str, optional

class Language(connection, id=None, name=None)

Bases: Entity, DeleteMixin

Python representation of a Strategy One Language object.

Parameters:

  • connection (Connection) –

  • id (str | None) –

  • name (str | None) –

id

language’s ID

Type:

str

name

language’s name

Type:

str

base_language_lcid

LC ID of the language serving as a base for the language

Type:

int

lcid

LC ID of the language

Type:

int

owner

owner of the language

Type:

User

last_modified

date of when language was last modified

Type:

datetime

formatting_settings

formatting settings of the language

Type:

TimeInterval

interface_language

details of the language’s interface language

Type:

InterfaceLanguage

hidden

whether the language is hidden

Type:

bool

is_language_supported

whether the language is supported

Type:

bool

class InterfaceLanguage(name, id, sub_type=None)

Bases: Dictable

Object that stores the interface language of the Language.

Parameters:
name

name of the interface language

Type:

str

id

id of the interface language

Type:

str

sub_type

subtype of the interface language, defaults to None

Type:

ObjectSubTypes

classmethod bulk_from_dict(source_list, connection=None, to_snake_case=True, with_missing_value=False)

Creates multiple objects from a list of dictionaries. For each dictionary provided the keys in camel case are changed to object’s attribute names (by default in snake case) and dict values are composed to their proper data types such as Enums, list of Enums etc. as specified in the object’s _FROM_DICT_MAP.

Parameters:

  • cls (T) – Class (type) of the objects that should be created.

  • source_list (List[Dict[str, Any]]) – A list of dictionaries from which the objects will be constructed.

  • connection (Connection, optional) – A MSTR Connection object. Defaults to None.

  • to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case. Defaults to True.

  • with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

A list of objects of type T.

Return type:

T

classmethod from_dict(source, connection=None, to_snake_case=True, with_missing_value=False)

Creates an object from a dictionary. The dictionary’s keys in camel case are changed to object’s attribute names (by default in snake case) and dict values are composed to their proper data types such as Enums, list of Enums etc. as specified in _FROM_DICT_MAP.

Parameters:

  • cls (T) – Class (type) of an object that should be created.

  • source (Dict[str, Any]) – A dictionary from which an object will be constructed.

  • connection (Connection, optional) – A MSTR Connection object. Defaults to None.

  • to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case. Defaults to True.

  • with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

An object of type T.

Return type:

T

to_dict(camel_case=True)

Converts an object to a dictionary excluding object’s private properties. When converting the object to a dictionary, the object’s attributes become the dictionary’s keys and are in camel case by default Attribute values stored as objects are automatically converted to non-/ primitive data structures.

Parameters:

camel_case (bool, optional) – Set to True if attribute names should be converted from snake case to camel case. Defaults to True.

Returns:

A dictionary representation of object’s attributes and values.

By default, the dictionary keys are in camel case.

Return type:

dict

id: str
name: str
sub_type: ObjectSubTypes | None = None
class TimeInterval(minutes15, minutes30, hour, day, week, hour_of_day, month, quarter, year)

Bases: Dictable

Object that stores formatting settings of the Language.

Parameters:

  • minutes15 (str) –

  • minutes30 (str) –

  • hour (str) –

  • day (str) –

  • week (str) –

  • hour_of_day (str) –

  • month (str) –

  • quarter (str) –

  • year (str) –

minutes15

formatting settings for 15 minutes

Type:

str

minutes30

formatting settings for 30 minutes

Type:

str

hour

formatting settings for an hour

Type:

str

day

formatting settings for a day

Type:

str

week

formatting settings for a week

Type:

str

hour_of_day

formatting settings for the hour of the day

Type:

str

month

formatting settings for a month

Type:

str

quarter

formatting settings for a quarter

Type:

str

year

formatting settings for a year

Type:

str

Formatting settings instructions:
To specify formatting for:

hours: use the letter h minutes: use the letter m days: use the letter d months: use the capital letter M quarters: use the letter q years: use the letter y

To specify 12 hour clock use AM/PM afterwards, example: h:mm AM/PM

Default formatting settings examples:

minutes15: h:mm AM/PM -> 9:44 AM minutes30: h:mm AM/PM -> 9:44 AM hour: h:mm AM/PM -> 9:44 AM day: M/d -> 7/26 week: M/d -> 7/26 hour_of_day: h:mm AM/PM -> 9:44 AM month: MMM -> Jul quarter: qqq -> Q3 year: yyyy -> 2023

classmethod bulk_from_dict(source_list, connection=None, to_snake_case=True, with_missing_value=False)

Creates multiple objects from a list of dictionaries. For each dictionary provided the keys in camel case are changed to object’s attribute names (by default in snake case) and dict values are composed to their proper data types such as Enums, list of Enums etc. as specified in the object’s _FROM_DICT_MAP.

Parameters:

  • cls (T) – Class (type) of the objects that should be created.

  • source_list (List[Dict[str, Any]]) – A list of dictionaries from which the objects will be constructed.

  • connection (Connection, optional) – A MSTR Connection object. Defaults to None.

  • to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case. Defaults to True.

  • with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

A list of objects of type T.

Return type:

T

classmethod from_dict(source, connection=None, to_snake_case=True, with_missing_value=False)

Creates an object from a dictionary. The dictionary’s keys in camel case are changed to object’s attribute names (by default in snake case) and dict values are composed to their proper data types such as Enums, list of Enums etc. as specified in _FROM_DICT_MAP.

Parameters:

  • cls (T) – Class (type) of an object that should be created.

  • source (Dict[str, Any]) – A dictionary from which an object will be constructed.

  • connection (Connection, optional) – A MSTR Connection object. Defaults to None.

  • to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case. Defaults to True.

  • with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

An object of type T.

Return type:

T

to_dict(camel_case=True)

Converts an object to a dictionary excluding object’s private properties. When converting the object to a dictionary, the object’s attributes become the dictionary’s keys and are in camel case by default Attribute values stored as objects are automatically converted to non-/ primitive data structures.

Parameters:

camel_case (bool, optional) – Set to True if attribute names should be converted from snake case to camel case. Defaults to True.

Returns:

A dictionary representation of object’s attributes and values.

By default, the dictionary keys are in camel case.

Return type:

dict

day: str
hour: str
hour_of_day: str
minutes15: str
minutes30: str
month: str
quarter: str
week: str
year: str
acl_add(rights, trustees, denied=False, inheritable=None, propagate_to_children=None, propagation_behavior=None)

Add Access Control Element (ACE) to the object ACL.

Note

To add rights for the Root Folder and the Freeform Objects, apply the required rights for these folders:

  • Root Folder: D43364C684E34A5F9B2F9AD7108F7828

  • Freeform Objects: 93D8CF3849C1F85DC1A48E8B9E4271F1

Argument propagate_to_children is used only for objects with type ObjectTypes.FOLDER.

Parameters:

  • rights (int | Rights | AggregatedRights) – The degree to which the user or group is granted or denied access to the object. The available permissions are defined in Rights and AggregatedRights Enums

  • trustees (list[UserOrGroup] | UserOrGroup) – list of trustees (User or UserGroup objects or ids) to update the ACE for

  • denied (bool) – flag to indicate granted or denied access to the object

  • inheritable (bool | None) – Applies only to folders. If set, any objects placed in the folder inherit the folder’s entry in the ACL.

  • propagate_to_children (bool | None) – used for folder objects only, default value is None, if set to True/False adds propagateACLToChildren keyword to the request body and sets its value accordingly

  • propagation_behavior (PropagationBehavior | str | None) – Behavior of ACL propagation to children.

  • self (Entity) –

Return type:

None

Examples

>>> obj.acl_add(rights=Rights.BROWSE | Rights.EXECUTE,
>>>             trustees=user_obj, denied=True)
acl_alter(rights, trustees, denied=False, inheritable=None, propagate_to_children=None, propagation_behavior=None)

Alter an existing Access Control Element (ACE) of the object ACL.

Note

To alter rights for the Root Folder and the Freeform Objects, change the required rights for these folders:

  • Root Folder: D43364C684E34A5F9B2F9AD7108F7828

  • Freeform Objects: 93D8CF3849C1F85DC1A48E8B9E4271F1

Argument propagate_to_children is used only for objects with type ObjectTypes.FOLDER.

Parameters:

  • rights (int | Rights | AggregatedRights) – The degree to which the user or group is granted or denied access to the object. The available permissions are defined in Rights and AggregatedRights Enums

  • trustees (list[UserOrGroup] | UserOrGroup) – list of trustees (User or UserGroup objects or ids) to update the ACE for

  • denied (bool) – flag to indicate granted or denied access to the object

  • inheritable (bool | None) – Applies only to folders. If set, any objects placed in the folder inherit the folder’s entry in the ACL.

  • propagate_to_children (bool | None) – used for folder objects only, default value is None, if set to True/False adds propagateACLToChildren keyword to the request body and sets its value accordingly

  • propagation_behavior (PropagationBehavior | str | None) – Behavior of ACL propagation to children.

  • self (Entity) –

Return type:

None

Examples

>>> obj.acl_alter(rights=Rights.BROWSE | Rights.EXECUTE,
>>>               trustees=user_obj, denied=True)
acl_remove(rights, trustees, denied=False, inheritable=None, propagate_to_children=None, propagation_behavior=None)

Remove Access Control Element (ACE) from the object ACL.

Note

To remove rights from the Root Folder and the Freeform Objects, remove them from these folders:

  • Root Folder: D43364C684E34A5F9B2F9AD7108F7828

  • Freeform Objects: 93D8CF3849C1F85DC1A48E8B9E4271F1

Argument propagate_to_children is used only for objects with type ObjectTypes.FOLDER.

Parameters:

  • rights (int | Rights | AggregatedRights) – The degree to which the user or group is granted or denied access to the object. The available permissions are defined in Rights and AggregatedRights Enums

  • trustees (list[UserOrGroup] | UserOrGroup) – list of trustees (User or UserGroup objects or ids) to update the ACE for

  • denied (bool) – flag to indicate granted or denied access to the object

  • inheritable (bool | None) – Applies only to folders. If set, any objects placed in the folder inherit the folder’s entry in the ACL.

  • propagate_to_children (bool | None) – used for folder objects only, default value is None, if set to True/False adds propagateACLToChildren keyword to the request body and sets its value accordingly

  • propagation_behavior (PropagationBehavior | str | None) – Behavior of ACL propagation to children.

  • self (Entity) –

Return type:

None

Examples

>>> obj.acl_remove(rights=Rights.BROWSE | Rights.EXECUTE,
>>>                trustees=user_obj, denied=True)
add_translation(translations)

Adds translations to the Object.

Parameters:

  • translations (list[OperationData]) – list of translations to be added to the Object

  • self (Entity) –

Returns:

A list of translations for the Object.

Return type:

list[’Translation’]

alter(name=None, comments=None, owner=None, formatting_settings=None)

Alter the language’s specified properties.

Parameters:

  • connection (Connection) – Strategy One connection object returned by connection.Connection()

  • name (str, Optional) – new name for the Language

  • comments (str, optional) – long description of the Language

  • owner (str | User | None) – (str, User, optional): owner of the Language object

  • formatting_settings (TimeInverval, Optional) – new formatting settings for the Language

Return type:

None

alter_translation(translations)

Alters translations of the Object.

Parameters:

  • translations (list[OperationData]) – list of translations to be added to the Object

  • self (Entity) –

Return type:

None

classmethod bulk_from_dict(source_list, connection=None, to_snake_case=True, with_missing_value=False)

Creates multiple objects from a list of dictionaries. For each dictionary provided the keys in camel case are changed to object’s attribute names (by default in snake case) and dict values are composed to their proper data types such as Enums, list of Enums etc. as specified in the object’s _FROM_DICT_MAP.

Parameters:

  • cls (T) – Class (type) of the objects that should be created.

  • source_list (List[Dict[str, Any]]) – A list of dictionaries from which the objects will be constructed.

  • connection (Connection, optional) – A MSTR Connection object. Defaults to None.

  • to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case. Defaults to True.

  • with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

A list of objects of type T.

Return type:

T

classmethod create(connection, name, base_language, interface_language_id=None, formatting_settings=None)

Create a new language with specified properties.

Parameters:

  • connection (Connection) – Strategy One connection object returned by connection.Connection()

  • name (str) – the name for the new Language

  • base_language (Language | str | int) –

    one of the following: - lcid attribute of the language that will be used as a base

    language for the new Language

    • ID of the language that will be used as a base language for

      the new Language

    • Language class object that will be used as a base language for

      the new Language

  • interface_language_id (str, Optional) – id of the new Language’s interface language

  • formatting_settings (TimeInterval, Optional) – formatting settings for the new Language

Returns:

Language class object.

Return type:

Language

create_shortcut(target_folder_id=None, target_folder_path=None, target_folder=None, project_id=None, project_name=None, project=None, to_dictionary=False)

Create a shortcut to the object.

Parameters:

  • target_folder_id (str, optional) – ID of the target folder. Target folder must be specified, but target_folder_id may be substituted with target_folder_path or target_folder.

  • target_folder_path (str, optional) – Path to the target folder, e.g. ‘/MicroStrategy Tutorial/Public Objects’. May be used instead of target_folder_id.

  • target_folder (Folder, optional) – Target folder object. May be used instead of target_folder_id.

  • project_id (str, optional) – ID of the target project of the new shortcut. The project may be specified by either project_id, project_name or project. If the project is not specified in either way, the project from the connection object is used.

  • project_name (str, optional) – Name of the target project. May be used instead of project_id.

  • project (Project, optional) – Project object specifying the target project. May be used instead of project_id.

  • to_dictionary (bool, optional) – If True, the method will return a dictionary with the shortcut’s properties instead of a Shortcut object. Defaults to False.

Return type:

Shortcut

delete(force=False)

Delete object.

Parameters:

  • force (bool) – If True, then no additional prompt will be shown before deleting object.

  • self (Entity) –

Returns:

True on success. False otherwise.

Return type:

bool

fetch(attr=None)

Fetch the latest object’s state from the I-Server.

Note

This method can overwrite local changes made to the object.

Parameters:

  • attr (Optional[str]) – Attribute name to be fetched. If not specified

  • dictionary. (it will use all getters specified in _API_GETTERS) –

  • None. (Defaults to) –

Raises:

ValueError – If attr cannot be fetched.

Return type:

None

classmethod from_dict(source, connection, to_snake_case=True, with_missing_value=False)
Overrides Dictable.from_dict() to instantiate an object from

a dictionary without calling any additional getters.

Parameters:

  • cls (T) – Class (type) of an object that should be created.

  • source (dict[str, Any]) – a dictionary from which an object will be constructed.

  • connection (Connection) – A Strategy One Connection object.

  • to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case, default True.

  • with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

An object of type T.

Return type:

T

get(name)

Get object’s attribute by its name.

list_acl(to_dataframe=False, to_dictionary=False, **filters)

Get Access Control List (ACL) for this object. Optionally filter ACLs by specifying filters.

Parameters:

  • to_dataframe (bool, optional) – if True, return datasets as pandas DataFrame

  • to_dictionary (bool, optional) – if True, return datasets as dicts

  • **filters – Available filter parameters: [deny, type, rights, trustee_id, trustee_name, trustee_type, trustee_subtype, inheritable]

Return type:

DataFrame | list[dict | mstrio.utils.acl.ACE]

Examples

>>> list_acl(deny=True, trustee_name="John")
list_dependencies(project=None, name=None, pattern=4, domain=2, object_types=None, used_by_recursive=False, root=None, root_path=None, limit=None, offset=None, results_format='LIST', to_dictionary=True, **filters)

List list_dependencies of an object.

Parameters:

  • project (string) – Project object or ID

  • name (string) – Value the search pattern is set to, which will be applied to the names of object types being searched. For example, search for all report objects (type) whose name begins with (pattern) B (name).

  • pattern (integer or enum class object) – Pattern to search for, such as Begin With or Exactly. Possible values are available in ENUM mstrio.object_management.SearchPattern. Default value is CONTAINS (4).

  • domain (integer or enum class object) – Domain where the search will be performed, such as Local or Project. Possible values are available in ENUM mstrio.object_management.SearchDomain. Default value is PROJECT (2).

  • root (string, optional) – Folder ID of the root folder where the search will be performed.

  • root_path (str, optional) –

    Path of the root folder in which the search will be performed. Can be provided as an alternative to root parameter. If both are provided, root is used.

    the path has to be provided in the following format:
    if it’s inside of a project, example:

    /MicroStrategy Tutorial/Public Objects/Metrics

    if it’s a root folder, example:

    /CASTOR_SERVER_CONFIGURATION/Users

  • class (object_types(enum class object or integer or list of enum) – objects or integers): Type(s) of object(s) to be searched, such as Folder, Attribute or User. Possible values available in ENUMs mstrio.types.ObjectTypes and mstrio.types.ObjectSubTypes

  • used_by_recursive (boolean, optional) – Control the Intelligence server to also find objects that are used by the given objects indirectly. Default value is false.

  • results_format (SearchResultsFormat) – either a list or a tree format

  • to_dictionary (bool) – If False returns objects, by default (True) returns dictionaries.

  • limit (int) – limit the number of elements returned. If None (default), all objects are returned.

  • offset (int) – Starting point within the collection of returned results. Used to control paging behavior. Default is 0.

  • **filters – Available filter parameters: [‘id’, ‘name’, ‘description’ ,’date_created’, ‘date_modified’, ‘acg’]

  • self (Entity) –

  • object_types (TypeOrSubtype | None) –

Returns:

list of objects or list of dictionaries

list_dependents(project=None, name=None, pattern=4, domain=2, object_types=None, uses_recursive=False, root=None, root_path=None, limit=None, offset=None, results_format='LIST', to_dictionary=True, **filters)

List dependents of an object.

Parameters:

  • project (string) – Project object or ID

  • name (string) – Value the search pattern is set to, which will be applied to the names of object types being searched. For example, search for all report objects (type) whose name begins with (pattern) B (name).

  • pattern (integer or enum class object) – Pattern to search for, such as Begin With or Exactly. Possible values are available in ENUM mstrio.object_management.SearchPattern. Default value is CONTAINS (4).

  • domain (integer or enum class object) – Domain where the search will be performed, such as Local or Project. Possible values are available in ENUM mstrio.object_management.SearchDomain. Default value is PROJECT (2).

  • root (string, optional) – Folder ID of the root folder where the search will be performed.

  • root_path (str, optional) –

    Path of the root folder in which the search will be performed. Can be provided as an alternative to root parameter. If both are provided, root is used.

    the path has to be provided in the following format:
    if it’s inside of a project, example:

    /MicroStrategy Tutorial/Public Objects/Metrics

    if it’s a root folder, example:

    /CASTOR_SERVER_CONFIGURATION/Users

  • class (object_types(enum class object or integer or list of enum) – objects or integers): Type(s) of object(s) to be searched, such as Folder, Attribute or User. Possible values available in ENUMs mstrio.types.ObjectTypes and mstrio.types.ObjectSubTypes

  • uses_recursive (boolean) – Control the Intelligence server to also find objects that use the given objects indirectly. Default value is false.

  • results_format (SearchResultsFormat) – either a list or a tree format

  • to_dictionary (bool) – If False returns objects, by default (True) returns dictionaries.

  • limit (int) – limit the number of elements returned. If None (default), all objects are returned.

  • offset (int) – Starting point within the collection of returned results. Used to control paging behavior. Default is 0.

  • **filters – Available filter parameters: [‘id’, ‘name’, ‘description’ ,’date_created’, ‘date_modified’, ‘acg’]

  • self (Entity) –

  • object_types (TypeOrSubtype | None) –

Returns:

list of objects or list of dictionaries

list_properties(excluded_properties=None)

Fetches all attributes from the server and converts all properties of the object to a dictionary.

Parameters:

excluded_properties (list[str], optional) – A list of object properties that should be excluded from the dict. Defaults to None.

Returns:

A dictionary which keys are object’s attribute names, and

which values are object’s attribute values.

Return type:

dict

list_translations(languages=None, to_dictionary=False)

Lists translations for the Object.

Parameters:

  • languages (list, optional) –

    list of languages to list the translations for, only translations from these languages will be listed. Languages in the list should be one of the following:

    • lcid attribute of the language

    • ID of the language

    • Language class object

  • to_dictionary (bool, optional) – If True returns dict, by default (False) returns Translation objects

  • self (Entity) –

Returns:

A list of dictionaries representing translations for the Object or a list of Translation Objects.

Return type:

list[’Translation’] | list[dict]

print()

Pretty Print all properties of the object.

Return type:

None

remove_translation(translations)

Removes translations from the Object.

Parameters:

  • translations (list[OperationData]) – list of translations to be added to the Object

  • self (Entity) –

Return type:

None

classmethod to_csv(objects, name, path=None, properties=None)

Exports MSTR objects to a csv file.

Optionally, saves only the object properties specified in the properties parameter.

Parameters:

  • objects (T | list[T]) – List of objects of the same type that

  • exported. (will be) –

  • name (str) – The name of the csv file ending with ‘.csv’

  • path (Optional[str], optional) – A path to the directory where the file will be saved. Defaults to None.

  • properties (Optional[list[str]], optional) – A list of object’s attribute names that should be included in the exported file. Defaults to None.

Raises:

  • TypeError – If objects is not of type T or list of type T

  • objects. –

Return type:

None

to_dataframe()

Converts all properties of the object to a dataframe.

Returns:

A DataFrame object containing object properties.

Return type:

DataFrame

to_dict(camel_case=True)

Converts an object to a dictionary excluding object’s private properties. When converting the object to a dictionary, the object’s attributes become the dictionary’s keys and are in camel case by default Attribute values stored as objects are automatically converted to non-/ primitive data structures.

Parameters:

camel_case (bool, optional) – Set to True if attribute names should be converted from snake case to camel case. Defaults to True.

Returns:

A dictionary representation of object’s attributes and values.

By default, the dictionary keys are in camel case.

Return type:

dict

update_properties()

Save compatible local changes of the object attributes to the I-Server. Changes are retrieved from the self._altered_properties dictionary. After the process of update has finished, self._altered_properties is cleared. For this method to work properly, you must override the _alter_properties() method in a subclass.

Raises:

requests.HTTPError – If I-Server raises exception

Return type:

None

target_id: str
target_language: Language | str | int
value: str | None = None
class TranslationValue(value, language_lcid)

Bases: Dictable

Object that specifies a Translation for a single Language

Parameters:

  • value (str) –

  • language_lcid (str) –

value

value of the translation

Type:

str

language_lcid

LCID of the language

Type:

str

classmethod bulk_from_dict(source_list, connection=None, to_snake_case=True, with_missing_value=False)

Creates multiple objects from a list of dictionaries. For each dictionary provided the keys in camel case are changed to object’s attribute names (by default in snake case) and dict values are composed to their proper data types such as Enums, list of Enums etc. as specified in the object’s _FROM_DICT_MAP.

Parameters:

  • cls (T) – Class (type) of the objects that should be created.

  • source_list (List[Dict[str, Any]]) – A list of dictionaries from which the objects will be constructed.

  • connection (Connection, optional) – A MSTR Connection object. Defaults to None.

  • to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case. Defaults to True.

  • with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

A list of objects of type T.

Return type:

T

classmethod from_dict(source, connection=None, to_snake_case=True, with_missing_value=False)

Creates an object from a dictionary. The dictionary’s keys in camel case are changed to object’s attribute names (by default in snake case) and dict values are composed to their proper data types such as Enums, list of Enums etc. as specified in _FROM_DICT_MAP.

Parameters:

  • cls (T) – Class (type) of an object that should be created.

  • source (Dict[str, Any]) – A dictionary from which an object will be constructed.

  • connection (Connection, optional) – A MSTR Connection object. Defaults to None.

  • to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case. Defaults to True.

  • with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

An object of type T.

Return type:

T

to_dict(camel_case=True)

Converts an object to a dictionary excluding object’s private properties. When converting the object to a dictionary, the object’s attributes become the dictionary’s keys and are in camel case by default Attribute values stored as objects are automatically converted to non-/ primitive data structures.

Parameters:

camel_case (bool, optional) – Set to True if attribute names should be converted from snake case to camel case. Defaults to True.

Returns:

A dictionary representation of object’s attributes and values.

By default, the dictionary keys are in camel case.

Return type:

dict

language_lcid: str
value: str
static add_translation(connection, id, object_type, translations, project_id=None)

Adds translations to the Object.

Parameters:

  • connection (Connection) – Strategy One connection object returned by

  • connection.Connection() –

  • id (str) – ID of the Object the translation will be added to

  • object_type (int | ObjectTypes) – type of the Object

  • translations (list[OperationData]) – list of translations to be added to the Object

  • project_id (str, optional) – project ID of the project the Object is located in, if not specified will be taken from the Connection

Returns:

A list of translations for the Object.

Return type:

list[Translation]

static add_translations_from_csv(connection, file_path, separator=';', project_id=None, delete=False, automatch_target_ids=False)

Add translations from a specified CSV file.

Parameters:

  • connection (Connection) – Strategy One connection object returned by connection.Connection()

  • file_path (str) – a path specifying the CSV file

  • separator (str, optional) – specify the separator of the csv file. Defaults to a semicolon ;

  • project_id (str, optional) – ID of the project the Objects are a part of, if not provided will be taken from connection

  • delete (bool, optional) – if True deletes translations for languages that are empty in the CSV file. False by default.

  • automatch_target_ids (bool, optional) – if True tries to match the target IDs from the file that are not found in the Objects on the server by the content of the translation for the project’s default language. False by default.

Return type:

None

To ensure correct import, the columns from the original file cannot be renamed. Columns can be deleted (with the exception of object ID, object type and target ID) but new columns cannot be added. The column order does not matter.

static add_translations_from_database(connection, table_name, datasource, project_id=None, delete=False, automatch_target_ids=False)

Add translations from a specified database table.

Parameters:

  • connection (Connection) – Strategy One connection object returned by connection.Connection()

  • table_name (str) – name of the table to import the data from

  • datasource (DatasourceInstance | str) – DatasourceInstance object or ID of the DatasourceInstance containing the connection to the database to export the data to

  • project_id (str, optional) – ID of the project the Objects are a part of, if not provided will be taken from connection

  • delete (bool, optional) – if True deletes translations for languages that are empty in the database table. False by default.

  • automatch_target_ids (bool, optional) – if True tries to match the target IDs from the file that are not found in the Objects on the server by the content of the translation for the project’s default language. False by default.

Return type:

None

To ensure correct import, the columns originally exported to database cannot be renamed. Columns can be deleted (with the exception of object ID, object type and target ID) but new columns cannot be added.

static add_translations_from_dataframe(connection, dataframe, project_id=None, delete=False, automatch_target_ids=False)

Add translations from a given dataframe.

Parameters:

  • connection (Connection) – Strategy One connection object returned by connection.Connection()

  • dataframe (pd.DataFrame) – dataframe containing the data to be imported

  • project_id (str, optional) – ID of the project the Objects are a part of, if not provided will be taken from connection

  • delete (bool, optional) – if True deletes translations for languages that are empty in the dataframe. False by default.

  • automatch_target_ids (bool, optional) – if True tries to match the target IDs from the file that are not found in the Objects on the server by the content of the translation for the project’s default language. False by default.

Return type:

None

To ensure correct import, the columns from the original dataframe cannot be renamed. Columns can be deleted (with the exception of object ID, object type and target ID) but new columns cannot be added. The column order does not matter.

static add_translations_from_json(connection, file_path, project_id=None, delete=False, automatch_target_ids=False)

Add translations from a specified JSON file.

Parameters:

  • connection (Connection) – Strategy One connection object returned by connection.Connection()

  • file_path (str) – a path specifying the JSON file

  • project_id (str, optional) – ID of the project the Objects are a part of, if not provided will be taken from connection

  • delete (bool, optional) – if True deletes translations for languages that are empty in the JSON file. False by default.

  • automatch_target_ids (bool, optional) – if True tries to match the target IDs from the file that are not found in the Objects on the server by the content of the translation for the project’s default language. False by default.

Return type:

None

To ensure correct import, the columns from the original file cannot be renamed. Columns can be deleted (with the exception of object ID, object type and target ID) but new columns cannot be added. The column order does not matter.

static alter_translation(connection, id, object_type, translations, project_id=None)

Alters translations for the Object.

Parameters:

  • connection (Connection) – Strategy One connection object returned by

  • connection.Connection() –

  • id (str) – ID of the Object the translation will be added to

  • object_type (int | ObjectTypes) – type of the Object

  • translations (list[OperationData]) – list of translations to be added to the Object

  • project_id (str, optional) – project ID of the project the Object is located in, if not specified will be taken from the Connection

Return type:

None

classmethod bulk_from_dict(source_list, connection=None, to_snake_case=True, with_missing_value=False)

Creates multiple objects from a list of dictionaries. For each dictionary provided the keys in camel case are changed to object’s attribute names (by default in snake case) and dict values are composed to their proper data types such as Enums, list of Enums etc. as specified in the object’s _FROM_DICT_MAP.

Parameters:

  • cls (T) – Class (type) of the objects that should be created.

  • source_list (List[Dict[str, Any]]) – A list of dictionaries from which the objects will be constructed.

  • connection (Connection, optional) – A MSTR Connection object. Defaults to None.

  • to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case. Defaults to True.

  • with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

A list of objects of type T.

Return type:

T

classmethod from_dict(source, connection=None, to_snake_case=True, with_missing_value=False)

Creates an object from a dictionary. The dictionary’s keys in camel case are changed to object’s attribute names (by default in snake case) and dict values are composed to their proper data types such as Enums, list of Enums etc. as specified in _FROM_DICT_MAP.

Parameters:

  • cls (T) – Class (type) of an object that should be created.

  • source (Dict[str, Any]) – A dictionary from which an object will be constructed.

  • connection (Connection, optional) – A MSTR Connection object. Defaults to None.

  • to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case. Defaults to True.

  • with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

An object of type T.

Return type:

T

static remove_translation(connection, id, object_type, translations, project_id=None)

Removes translations from the Object.

Parameters:

  • connection (Connection) – Strategy One connection object returned by

  • connection.Connection() –

  • id (str) – ID of the Object the translation will be added to

  • object_type (int | ObjectTypes) – type of the Object

  • translations (list[OperationData]) – list of translations to be added to the Object

  • project_id (str, optional) – project ID of the project the Object is located in, if not specified will be taken from the Connection

Return type:

None

static to_csv_from_list(connection, object_list, separator=';', languages=None, file_path=None, project_id=None, denormalized_form=False, add_object_path=False, add_object_description=False, add_object_version=False, add_object_last_modified_date=False, add_object_creation_date=False)

Export translations of the given objects to a CSV file.

Parameters:

  • connection (Connection) – Strategy One connection object returned by connection.Connection()

  • object_list (list[Entity]) – list of Objects to export translations for. Objects have to be provided as class objects such as a Metric or a Document.

  • separator (str, optional) – specify the separator for the csv file. Defaults to a semicolon ;

  • languages (list, optional) –

    list of languages to list translations for, only translations from these languages will be listed. If not specified languages will be taken from the project. Languages in the list should be one of the following:

    • ID of the language

    • Language class object

  • file_path (str, optional) – a path specifying where to save the csv file

  • project_id (str, optional) – ID of the project the Objects are a part of, if not provided will be taken from connection

  • denormalized_form (bool, optional) – if True exports the data in a denormalized form, if False exports the data in a normalized form. False by default. Normalised form means that each row contains a single target_id with translation values for all required languages Denormalised form means each row represents a translation value for one target_id and one language at a time

  • add_object_path (bool, optional) – if True adds a column with the path of the Object

  • add_object_description (bool, optional) – if True adds a column with the description of the Object

  • add_object_version (bool, optional) – if True adds a column with the version of the Object

  • add_object_last_modified_date (bool, optional) – if True adds a column with the last modified date of the Object

  • add_object_creation_date (bool, optional) – if True adds a column with the creation date of the Object

Returns:

String representation of the CSV file if no path was given or None if path was provided.

Return type:

str | None

static to_database_from_list(connection, object_list, table_name, datasource, database_type=None, languages=None, project_id=None, denormalized_form=False, add_object_path=False, add_object_description=False, add_object_version=False, add_object_last_modified_date=False, add_object_creation_date=False, force=False)

Export translations of the given objects to an SQL database table.

Parameters:

  • connection (Connection) – Strategy One connection object returned by connection.Connection()

  • object_list (list[Entity]) – list of Objects to export translations for. Objects have to be provided as class objects such as a Metric or a Document.

  • table_name (str) – name of the table to export the data to If the table with the given name already exists, the existing table will be dropped first, then a new one will be created.

  • datasource (DatasourceInstance | str) – DatasourceInstance object or ID of the DatasourceInstance containing the connection to the database to export the data to

  • database_type (str, optional) –

    type of the database, if not provided standard SQL will be used. Supported database types include:

    • MySQL

    • MSSQL

    • PostgreSQL

    • Oracle

    • Vertica

  • languages (list, optional) –

    list of languages to list translations for, only translations from these languages will be listed. If not specified languages will be taken from the project. Languages in the list should be one of the following:

    • ID of the language

    • Language class object

  • project_id (str, optional) – ID of the project the Objects are a part of, if not provided will be taken from connection

  • denormalized_form (bool, optional) – if True exports the data in a denormalized form, if False exports the data in a normalized form. False by default. Normalised form means that each row contains a single target_id with translation values for all required languages Denormalised form means each row represents a translation value for one target_id and one language at a time

  • add_object_path (bool, optional) – if True adds a column with the path of the Object

  • add_object_description (bool, optional) – if True adds a column with the description of the Object

  • add_object_version (bool, optional) – if True adds a column with the version of the Object

  • add_object_last_modified_date (bool, optional) – if True adds a column with the last modified date of the Object

  • add_object_creation_date (bool, optional) – if True adds a column with the creation date of the Object

  • force (bool, optional) – if True skips the prompt asking for confirmation before dropping the table. False by default.

Return type:

None

static to_dataframe_from_list(connection, object_list, languages=None, project_id=None, denormalized_form=False, add_object_path=False, add_object_description=False, add_object_version=False, add_object_last_modified_date=False, add_object_creation_date=False)

Export translations of the given objects to a dataframe.

Parameters:

  • connection (Connection) – Strategy One connection object returned by connection.Connection()

  • object_list (list[Entity]) – list of Objects to export translations for. Objects have to be provided as class objects such as a Metric or a Document.

  • languages (list, optional) –

    list of languages to list translations for, only translations from these languages will be listed. If not specified languages will be taken from the project. Languages in the list should be one of the following:

    • ID of the language

    • Language class object

  • project_id (str, optional) – ID of the project the Objects are a part of, if not provided will be taken from connection

  • denormalized_form (bool, optional) – if True exports the data in a denormalized form, if False exports the data in a normalized form. False by default. Normalised form means that each row contains a single target_id with translation values for all required languages Denormalised form means each row represents a translation value for one target_id and one language at a time

  • add_object_path (bool, optional) – if True adds a column with the path of the Object

  • add_object_description (bool, optional) – if True adds a column with the description of the Object

  • add_object_version (bool, optional) – if True adds a column with the version of the Object

  • add_object_last_modified_date (bool, optional) – if True adds a column with the last modified date of the Object

  • add_object_creation_date (bool, optional) – if True adds a column with the creation date of the Object

Returns:

A pandas Dataframe containing the translation data.

Return type:

DataFrame

to_dict(camel_case=True)

Converts an object to a dictionary excluding object’s private properties. When converting the object to a dictionary, the object’s attributes become the dictionary’s keys and are in camel case by default Attribute values stored as objects are automatically converted to non-/ primitive data structures.

Parameters:

camel_case (bool, optional) – Set to True if attribute names should be converted from snake case to camel case. Defaults to True.

Returns:

A dictionary representation of object’s attributes and values.

By default, the dictionary keys are in camel case.

Return type:

dict

static to_json_from_list(connection, object_list, languages=None, file_path=None, project_id=None, denormalized_form=False, add_object_path=False, add_object_description=False, add_object_version=False, add_object_last_modified_date=False, add_object_creation_date=False)

Export translations of the given objects to a JSON file.

Parameters:

  • connection (Connection) – Strategy One connection object returned by connection.Connection()

  • object_list (list[Entity]) – list of Objects to export translations for. Objects have to be provided as class objects such as a Metric or a Document.

  • languages (list, optional) –

    list of languages to list translations for, only translations from these languages will be listed. If not specified languages will be taken from the project. Languages in the list should be one of the following:

    • ID of the language

    • Language class object

  • file_path (str, optional) – a path specifying where to save the json file

  • project_id (str, optional) – ID of the project the Objects are a part of, if not provided will be taken from connection

  • denormalized_form (bool, optional) – if True exports the data in a denormalized form, if False exports the data in a normalized form. False by default. Normalised form means that each row contains a single target_id with translation values for all required languages Denormalised form means each row represents a translation value for one target_id and one language at a time

  • add_object_path (bool, optional) – if True adds a column with the path of the Object

  • add_object_description (bool, optional) – if True adds a column with the description of the Object

  • add_object_version (bool, optional) – if True adds a column with the version of the Object

  • add_object_last_modified_date (bool, optional) – if True adds a column with the last modified date of the Object

  • add_object_creation_date (bool, optional) – if True adds a column with the creation date of the Object

Returns:

String representation of the JSON file if no path was given or None if path was provided.

Return type:

str | None

translation_target_id: str
translation_target_name: str
translation_values: list[TranslationValue]
mstrio.object_management.translation.list_translations(connection, id, object_type, project_id=None, languages=None, to_dictionary=False)

Lists translations of the given Object.

Parameters:

  • connection (Connection) – Strategy One connection object returned by connection.Connection()

  • id (str) – ID of the Object the translations will be listed for

  • object_type (int | ObjectTypes) – type of the Object the translations will be listed for

  • project_id (str, optional) – project ID of the project the Object is on, if not provided will be taken from connection

  • languages (list, optional) –

    list of languages to list the translations for, only translations from these languages will be listed. Languages in the list should be one of the following:

    • lcid attribute of the language

    • ID of the language

    • Language class object

  • to_dictionary (bool, optional) – If True returns a list of dictionaries, by default (False) returns a list of Translation objects

Returns:

A list of dictionaries representing translations for the Object or a list of Translation Objects.

Return type:

list[Translation] | list[dict]