Эта глава содержит общественный API для расширения C Connector/Python,
также известное как модуль
_mysql_connector
Python.
Модуль _mysql_connector
может использоваться
непосредственно без любого другого кода Connector/Python. Одна причина
использовать этот модуль непосредственно по причинам производительности.
Примеры в этом руководстве используют ccnx
,
чтобы представлять объект соединителя, как используется с модуем
_mysql_connector
.
ccnx
это экземпляр класса
_mysql_connector.MySQL()
. Это отлично от
объекта cnx
, используемого в примерах для
модуля mysql.connector
Connector/Python из
главы 10. cnx
это
экземпляр объекта, возвращенного методом
connect()
класса
MySQLConnection
.
Расширение C не часть чистой установки Python. Это дополнительный модуль, который должен быть установлен, используя двоичный дистрибутив Connector/Python, который включает его, или собран с использованием исходного текста, см. главу 4.
Модуль _mysql_connector
обеспечивает классы.
Синтаксис:
ccnx = _mysql_connector.MySQL(args
)
Класс MySQL
используется, чтобы открыть и
управлять связью с сервером MySQL (упомянутом в другом месте в этой главе
как экземпляр MySQL
).
Это также используется, чтобы послать команды и
SQL-операторы и прочитать результаты.
Класс MySQL
обертывает большинство функций,
найденных в MySQL C Client API, и добавляет некоторую
дополнительную удобную функциональность.
import _mysql_connector
ccnx = _mysql_connector.MySQL()
ccnx.connect(user='scott', password='password
',
host='127.0.0.1', database='employees')
ccnx.close()
Разрешенные аргументы класса MySQL
:
auth_plugin
,
buffered
,
charset_name
,
connection_timeout
,
raw
,
use_unicode
.
Эти аргументы соответствуют аргументам для
MySQLConnection.connect()
, как описано в
разделе 7.1,
за исключением того, что charset_name
соответствует charset
.
Синтаксис:
count = ccnx.affected_rows()
Возвращает количество строк, измененных, вставленных или удаленных
последним запросом UPDATE
,
INSERT
или
DELETE
.
Синтаксис:
ccnx.autocommit(bool
)
Устанавливает режим autocommit.
Поднимает исключение ValueError
, если
mode
не True
или
False
.
Синтаксис:
is_buffered = ccnx.buffered() # getter
ccnx.buffered(bool
) # setter
Без аргумента вернет True
или
False
, чтобы указать буферизует ли экземпляр
MySQL
результаты.
С булевым аргументом устанавливает режим буферизации экземпляра
MySQL
.
Для синтаксиса сеттера поднимает исключение
TypeError
, если значение не
True
или False
.
Синтаксис:
ccnx.change_user(user='user_name
, password='password_val
', database='db_name
')
Изменяет пользователя и устанавливает новую базу данных по умолчанию.
Разрешенные аргументы user
,
password
и
database
.
Синтаксис:
charset = ccnx.character_set_name()
Возвращает название набора символов по умолчанию для текущей сессии MySQL.
У некоторых наборов символов MySQL нет эквивалентных имен в Python.
Когда дело обстоит так, имя, применимое Python, возвращено. Например,
имя набора символов MySQL 'utf8mb4'
возвращено как 'utf8'
.
Синтаксис:
ccnx.close()
Закрывает подключение MySQL.
Синтаксис:
ccnx.commit()
Передает текущую транзакцию.
Синтаксис:
ccnx.connect(args
)
Соединяется с сервером MySQL.
import _mysql_connector
ccnx = _mysql_connector.MySQL()
ccnx.connect(user='scott', password='password
',
host='127.0.0.1', database='employees')
ccnx.close()
connect()
понимает следующие аргументы:
host
, user
,
password
, database
,
port
, unix_socket
,
client_flags
,
ssl_ca
, ssl_cert
,
ssl_key
,
ssl_verify_cert
,
compress
. См.
раздел 7.1.
Если ccnx
уже связан,
connect()
сбрасывает любой набор результатов и
завершает связь прежде, чем вновь ее открыть.
Поднимает исключение TypeError
,
если какой-либо аргумент имеет неправильный тип.
Синтаксис:
is_connected = ccnx.connected()
Вернет True
или
False
, чтобы указать, подключен ли экземпляр
MySQL
.
Синтаксис:
ccnx.consume_result()
Потребляет сохраненный набор результатов, если есть для этого экземпляра
MySQL
, получая все строки.
Если запрос, который был выполнен, возвратил много наборов результатов, этот
метод поглощает всех их.
Синтаксис:
converted_obj = ccnx.convert_to_mysql(obj
))
Преобразовывает объект Python в значение MySQL на основе типа объекта Python. Преобразованный объект экранирован и цитирован.
ccnx.query('SELECT CURRENT_USER(), 1 + 3, NOW()') row = ccnx.fetch_row() for col in row: print(ccnx.convert_to_mysql(col)) ccnx.consume_result()
Поднимает исключение MySQLInterfaceError
,
если объект не может быть преобразован.
Синтаксис:
str = ccnx.escape_string(str_to_escape
)
Использует C API-функцию
Uses the mysql_escape_string()
,
чтобы создать строку SQL, которую можно использовать в SQL-операторе.
Поднимает исключение TypeError
, если у
значения нет типа Unicode
,
bytes
или (для Python 2)
string
. Поднимает исключение
MySQLError
, если строку нельзя
было бы экранировать.
Синтаксис:
field_info = ccnx.fetch_fields()
Информация о столбце для активного набора результатов. Возвращает список кортежей, один кортеж для каждого столбца.
Поднимает исключение MySQLInterfaceError
,
для любой ошибки MySQL, возвращенной сервером MySQL.
ccnx.query('SELECT CURRENT_USER(), 1 + 3, NOW()') field_info = ccnx.fetch_fields() for fi in field_info: print(fi) ccnx.consume_result()
Синтаксис:
row = ccnx.fetch_row()
Приносит следующую строку активного набора результатов. Строка возвращена
как кортеж, которая содержит значения, преобразованные в объекты Python, если
не был установлен raw
.
ccnx.query('SELECT CURRENT_USER(), 1 + 3, NOW()') row = ccnx.fetch_row() print(row) ccnx.free_result()
Поднимает исключение MySQLInterfaceError
для любой ошибки MySQL, возвращенной сервером MySQL.
Синтаксис:
count = ccnx.field_count()
Возвращает количество колонок в активном наборе результатов.
Синтаксис:
ccnx.free_result()
Освобождает сохраненный набор результатов, если есть для этого
экземпляра MySQL
.
Если запрос, который был выполнен, возвратил много наборов результатов, этот
метод обработает все.
Синтаксис:
info = ccnx.get_character_set_info()
Вернет данные о наборе символов по умолчанию для текущей сессии MySQL.
У возвращенного словаря есть ключи
number
, name
,
csname
, comment
,
dir
, mbminlen
и
mbmaxlen
.
Синтаксис:
info = ccnx.get_client_info()
Возвращает версию библиотеки клиента MySQL как строку.
Синтаксис:
info = ccnx.get_client_version()
Возвращает версию библиотеки клиента MySQL как кортеж.
Синтаксис:
info = ccnx.get_host_info()
Возвращает описание типа связи как строку.
Синтаксис:
info = ccnx.get_proto_info()
Возвращает версию протокола, используемую текущей сессией.
Синтаксис:
info = ccnx.get_server_info()
Возвращает версию сервера MySQL как строку.
Синтаксис:
info = ccnx.get_server_version()
Возвращает версию сервера MySQL как кортеж.
Синтаксис:
info = ccnx.get_ssl_cipher()
Возвращает шифр SSL, используемый для текущей сессии, или
None
, если SSL не используется.
Синтаксис:
str = ccnx.hex_string(string_to_hexify
)
Кодирует значение в шестнадцатеричном формате и обертывает его в
X''
. Например,
"ham"
становится
X'68616D'
.
Синтаксис:
insert_id = ccnx.insert_id()
Вернет значение AUTO_INCREMENT
, произведенное
последним выполненным запросом, или 0, если такой нет.
Синтаксис:
more = ccnx.more_results()
Вернет True
или
False
, указывая, существуют ли
еще наборы результатов.
Синтаксис:
ccnx.next_result()
Начинает следующий набор результатов для последовательности запроса, которая произвела многократные наборы результатов.
Поднимает исключение MySQLInterfaceError
для любой ошибки MySQL, возвращенной сервером MySQL.
Синтаксис:
count = ccnx.num_fields()
Возвращает количество колонок в активном наборе результатов.
Синтаксис:
count = ccnx.num_rows()
Возвращает количество строк в активном наборе результатов.
Поднимает исключение MySQLError
, если нет
никакого набора результатов.
Синтаксис:
alive = ccnx.ping()
Вернет True
или
False
, указывая, работает
ли связь с сервером MySQL.
Синтаксис:
ccnx.query(args
)
Выполняет SQL-оператор. Разрешенные аргументы:
statement
,
buffered
,
raw
и
raw_as_string
.
ccnx.query('DROP TABLE IF EXISTS t') ccnx.query('CREATE TABLE t (i INT NOT NULL AUTO_INCREMENT PRIMARY KEY)') ccnx.query('INSERT INTO t (i) VALUES (NULL),(NULL),(NULL)') ccnx.query('SELECT LAST_INSERT_ID()') row = ccnx.fetch_row() print('LAST_INSERT_ID(): ', row) ccnx.consume_result()
buffered
и raw
,
если не заданы, берут значения из экземпляра
MySQL
.
raw_as_string
специальный аргумент для Python v2
возвращает str
вместо
bytearray
(совместимый с Connector/Python v1.x).
Чтобы проверить вернул ли запрос строки, проверьте свойство
have_result_set
экземпляра
MySQL
.
query()
вернет
True
, если вопрос выполняется и поднимает
исключение иначе. Это поднимает исключение
TypeError
, если у какого-либо аргумента есть
неправильный тип и MySQLInterfaceError
для любой ошибки MySQL, возвращенной сервером MySQL.
Синтаксис:
is_raw = ccnx.raw() # getter
ccnx.raw(bool
) # setter
Без аргумента вернет True
или
False
указывая, что экземпляр
MySQL
возвращает строки как есть
(без преобразования в объекты Python).
С булевым аргументом установит режим экземпляра
MySQL
.
Синтаксис:
ccnx.refresh(flags
)
Сбрасывает таблицы и кэши, указанные аргументом. Единственным аргументом в настоящее время является целое число.
Поднимает исключение TypeError
, если первый
аргумент не целое число.
Синтаксис:
ccnx.rollback()
Отменяет текущую транзакцию.
Поднимает исключение MySQLInterfaceError
на любых ошибках.
Синтаксис:
ccnx.select_db(db_name
)
Устанавливает текущую базу данных для текущей сессии.
Поднимает исключение MySQLInterfaceError
для любой ошибки MySQL, возвращенной сервером MySQL.
Синтаксис:
ccnx.set_character_set(charset_name
)
Устанавливает набор символов по умолчанию для текущей сессии. Единственным разрешенным аргументом является последовательность, которая содержит имя набора символов.
Поднимает исключение TypeError
, если аргумент
не PyString_type
.
Синтаксис:
ccnx.shutdown(flags
)
Закрывает сервер MySQL. Единственным аргументом в настоящее время является целое число, которое описывает тип закрытия.
Поднимает исключение TypeError
, если первый
аргумент не целое число. Поднимает исключение
MySQLErrorInterface
,
если ошибка возвращена сервером MySQL.
Синтаксис:
info = ccnx.stat()
Возвращает статус сервера как последовательность.
Поднимает исключение MySQLErrorInterface
,
если ошибка возвращена сервером MySQL.
Синтаксис:
thread_id = ccnx.thread_id()
Возвращает ID текущего потока или связи.
Синтаксис:
is_unicode = ccnx.use_unicode() # getter
ccnx.use_unicode(bool
) # setter
Без аргумента вернет True
или
False
указывая, возвращает ли экземпляр
MySQL
недвоичные строки как Unicode.
С булевым аргументом устанавливает, возвращает ли экземпляр
MySQL
недвоичные строки как Unicode.
Синтаксис:
count = ccnx.warning_count()
Возвращает количество ошибок, предупреждений и сообщений, произведенных предыдущим SQL-оператором.
Синтаксис:
has_rows = ccnx.have_result_set
После выполнения метода query()
указывает, возвращает ли запрос строки.