10.2.2 Creating Extension Objects

To create a new extension object to provide one or more functions, data types, or further extension objects, use the built-in shell.createExtensionObject() function in JavaScript or shell.create_extension_object() in Python:

shell.createExtensionObject()

To add members to the extension object, use the built-in shell.addExtensionObjectMember() function in JavaScript or shell.add_extension_object_member() in Python:

shell.addExtensionObjectMember(object, name, member[, definition])

Where:

• object is the extension object where the new member is to be added.

• name is the name of the new member. The name must be a valid scripting identifier, so the first character must be a letter or underscore character, followed by any number of letters, numbers, or underscore characters. The name must be unique among the members that have already been added to the same extension object, and if the member is a function, the name does not have to match the name of the defined function. The name should preferably be specified in camel case, even if you are using Python to define and add the member. Specifying the member name in camel case enables MySQL Shell to automatically enforce naming conventions. MySQL Shell makes the member available in JavaScript mode using camel case, and in Python mode using snake case.

• member is the value of the new member, which can be any of the following:

  • A supported basic data type. The supported data types are “none” or “null”, “bool”, “number” (integer or floating point), “string”, “array”, and “dictionary”.

  • A JavaScript or Python function. You can use native code in the body of functions that are added as members to an extension object, provided that the interface (parameters and return values) is limited to the supported data types in Table 10.1, “Supported data type pairs for extension objects”. The use of other data types in the interface can lead to undefined behavior.

  • Another extension object.

• definition is an optional dictionary that can contain help information for the member, and also if the member is a function, a list of parameters that the function receives. Help information is defined using the following attributes:

  • brief is a brief description of the member.

  • details is a detailed description of the member, provided as a list of strings. This is provided when you use the MySQL Shell \help command.

  Parameters for a function are defined using the following attribute:

  • parameters is a list of dictionaries describing each parameter that the function receives. Each dictionary describes one parameter, and can contain the following keys:

    • name (string, required): The name of the parameter.

    • type (string, required): The data type of the parameter, one of “string”, “integer”, “bool”, “float”, “array”, “dictionary”, or “object”. If the type is “object”, the class or classes key can also be used. If the type is “string”, the values key can also be used. If the type is “dictionary”, the options key can also be used.

    • class (string, optional, allowed when data type is “object”): Defines the object type that is allowed as a parameter.

    • classes (list of strings, optional, allowed when data type is “object”): A list of classes defining the object types that are allowed as a parameter. The supported object types for class and classes are those that are exposed by the MySQL Shell APIs, for example Session, ClassicSession, Table, or Collection. An error is raised if an object type is passed to the function that is not in this list.

    • values (list of strings, optional, allowed when data type is “string”): A list of values that are valid for the parameter. An error is raised if a value is passed to the function that is not in this list.

    • options (list of options, optional, allowed when data type is “dictionary”): A list of options that are allowed for the parameter. Options use the same definition structure as the parameters, with the exception that if required is not specified for an option, it defaults to false. MySQL Shell validates the options specified by the end user and raises an error if an option is passed to the function that is not in this list. In MySQL Shell 8.0.17 through 8.0.19, this parameter is required when the data type is “dictionary”, but from MySQL Shell 8.0.20 it is optional. If you create a dictionary with no list of options, any options that the end user specifies for the dictionary are passed directly through to the function by MySQL Shell with no validation.

    • required (bool, optional): Whether the parameter is required. If required is not specified for a parameter, it defaults to true.

    • brief (string, optional): A short description of the parameter to be provided as help information.

    • details (list of strings, optional): A detailed description of the parameter to be provided as help information.

An extension object is considered to be under construction until it has been registered as a MySQL Shell global object, or added as a member to another extension object that is registered as a MySQL Shell global object. An error is returned if you attempt to use an extension object in MySQL Shell when it has not yet been registered.

Cross Language Considerations

An extension object can contain a mix of members defined in Python and members defined in JavaScript. MySQL Shell manages the transfer of data from one language to the other as parameters and return values. Table 10.1, “Supported data type pairs for extension objects” shows the data types that MySQL Shell supports when transferring data between languages, and the pairs that are used as representations of each other:

Table 10.1 Supported data type pairs for extension objects

JavaScript	Python
Boolean	Boolean
String	String
Integer	Long
Number	Float
Null	None
Array	List
Map	Dictionary

An extension object is literally the same object in both languages.