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”, theclass
orclasses
key can also be used. If the type is “string”, thevalues
key can also be used. If the type is “dictionary”, theoptions
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 forclass
andclasses
are those that are exposed by the MySQL Shell APIs, for exampleSession
,ClassicSession
,Table
, orCollection
. 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 ifrequired
is not specified for an option, it defaults tofalse
. 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. Ifrequired
is not specified for a parameter, it defaults totrue
.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.
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.