11.2.2 Creating Extension Objects — MySQL Shell 9.2

11.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 — это имя нового члена. Имя должно быть допустимым идентификатором сценария, поэтому первый символ должен быть буквой или символом подчеркивания, за которым следует любое количество букв, цифр или символов подчеркивания. Имя должно быть уникальным среди членов, которые уже были добавлены в тот же объект расширения, и если член является функцией, имя не обязательно должно совпадать с именем определенной функции. Имя предпочтительно должно быть указано в формате camelCase, даже если вы используете Python для определения и добавления члена. Указание имени члена в формате camelCase позволяет MySQL Shell автоматически применять соглашения об именовании. MySQL Shell делает член доступным в режиме JavaScript с использованием camelCase, а в режиме Python — с использованием snake_case.
member — это значение нового члена, которое может быть одним из следующих:
- Поддерживаемый базовый тип данных. Поддерживаемые типы данных: “none” или “null”, “bool”, “number” (целое или с плавающей точкой), “string”, “array” и “dictionary”.
- Функция JavaScript или Python. Вы можете использовать код на родном языке в теле функций, которые добавляются как члены в объект расширения, при условии, что интерфейс (параметры и возвращаемые значения) ограничен поддерживаемыми типами данных в таблице 11.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 управляет передачей данных из одного языка в другой в качестве параметров и возвращаемых значений. Таблица 11.1 «Поддерживаемые пары типов данных для объектов расширения» показывает типы данных, которые MySQL Shell поддерживает при передаче данных между языками, и пары, используемые для представления друг друга:

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

Таблица 11.1 Поддерживаемые пары типов данных для объектов расширения
JavaScript	Python
Boolean	Boolean
String	String
Integer	Long
Number	Float
Null	None
Array	List
Map	Dictionary

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