10.2.2 Creating Extension Objects — MySQL Shell 8.4

10.2.2 Создание объектов расширения

Для создания нового объекта расширения, предоставляющего одну или несколько функций, типов данных или дополнительных объектов расширения, используйте встроенную функцию shell.createExtensionObject() в JavaScript или shell.create_extension_object() в Python:

shell.createExtensionObject()

Для добавления членов в объект расширения используйте встроенную функцию shell.addExtensionObjectMember() в JavaScript или shell.add_extension_object_member() в Python:

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

Где:

object — это объект расширения, в который необходимо добавить новый член.
name — имя нового члена. Имя должно быть допустимым идентификатором скрипта, поэтому первый символ должен быть буквой или символом подчеркивания, за которым следуют любые количество букв, цифр или символов подчеркивания. Имя должно быть уникальным среди членов, которые уже были добавлены в тот же объект расширения, а если член является функцией, имя не обязательно должно совпадать с именем определенной функции. Имя предпочтительно задавать в стиле camel case, даже если вы используете Python для определения и добавления члена. Указание имени члена в стиле camel case позволяет MySQL Shell автоматически применять соглашения об именовании. MySQL Shell делает член доступным в режиме JavaScript с использованием camel case, а в режиме Python — с использованием snake case.
member — значение нового члена, которое может быть одним из следующих:
- Поддерживаемый базовый тип данных. Поддерживаемые типы данных — “none” или “null”, “bool”, “number” (целое или с плавающей точкой), “string”, “array” и “dictionary”.
- Функция JavaScript или Python. Вы можете использовать собственный код в теле функций, которые добавляются в качестве членов в объект расширения, при условии, что интерфейс (параметры и возвращаемые значения) ограничен поддерживаемыми типами данных в таблице 10.1 «Поддерживаемые пары типов данных для объектов расширения». Использование других типов данных в интерфейсе может привести к неопределенному поведению.
- Другой объект расширения.
definition — необязательный словарь, который может содержать справочную информацию о члене, а также, если член является функцией, список параметров, которые получает функция. Справочная информация определяется с помощью следующих атрибутов:
- brief — краткое описание члена.
- details — подробное описание члена, представленное в виде списка строк. Это предоставляется при использовании команды MySQL Shell \help.
Параметры функции определяются с помощью следующего атрибута:
- parameters — список словарей, описывающих каждый параметр, получаемый функцией. Каждый словарь описывает один параметр и может содержать следующие ключи:
  - name (строка, обязательный): имя параметра.
  - type (строка, обязательный): тип данных параметра, один из “string”, “integer”, “bool”, “float”, “array”, “dictionary” или “object”. Если тип — “object”, также можно использовать ключи class или classes. Если тип — “string”, также можно использовать ключ values. Если тип — “dictionary”, также можно использовать ключ options.
  - class (строка, необязательный, разрешенный, когда тип данных — “object”): определяет тип объекта, который разрешен в качестве параметра.
  - classes (список строк, необязательный, разрешенный, когда тип данных — “object”): список классов, определяющих типы объектов, которые разрешены в качестве параметра. Поддерживаемые типы объектов для class и classes — те, которые доступны через API MySQL Shell, например, Session, ClassicSession, Table или Collection. Возникает ошибка, если в функцию передается тип объекта, который не входит в этот список.
  - values (список строк, необязательный, разрешенный, когда тип данных — “string”): список допустимых значений для параметра. Возникает ошибка, если в функцию передается значение, которое не входит в этот список.
  - options (список опций, необязательный, разрешенный, когда тип данных — “dictionary”): список опций, которые разрешены для параметра. Опции используют ту же структуру определения, что и параметры, за исключением того, что если required не указан для опции, он по умолчанию равен false. MySQL Shell проверяет опции, указанные конечным пользователем, и выдает ошибку, если в функцию передается опция, которая не входит в этот список. Если вы создаете словарь без списка опций, любые опции, указанные конечным пользователем для словаря, передаются непосредственно в функцию MySQL Shell без проверки.
  - required (булево, необязательно): указывает, является ли параметр обязательным. Если required не указан для параметра, он по умолчанию равен true.
  - brief (строка, необязательно): краткое описание параметра, которое должно быть предоставлено в качестве справочной информации.
  - details (список строк, необязательно): подробное описание параметра, которое должно быть предоставлено в качестве справочной информации.

Объект расширения считается находящимся в процессе создания до тех пор, пока он не будет зарегистрирован как глобальный объект MySQL Shell или добавлен в качестве члена к другому объекту расширения, зарегистрированному как глобальный объект MySQL Shell. Возвращается ошибка, если вы пытаетесь использовать объект расширения в MySQL Shell, когда он еще не был зарегистрирован.

Учет особенностей разных языков

Объект расширения может содержать смесь членов, определенных на Python, и членов, определенных на JavaScript. MySQL Shell управляет передачей данных из одного языка в другой в качестве параметров и возвращаемых значений. Таблица 10.1 «Поддерживаемые пары типов данных для объектов расширения» отображает типы данных, которые поддерживает MySQL Shell при передаче данных между языками, и пары, которые используются как представления друг друга:

Таблица 10.1 Поддерживаемые пары типов данных для объектов расширения

Таблица 10.1 Поддерживаемые пары типов данных для объектов расширения
JavaScript	Python
Булево	Булево
Строка	Строка
Целое	Целое
Число	Число с плавающей точкой
Null	None
Массив	Список
Карта	Словарь

Объект расширения фактически является одним и тем же объектом на обоих языках.