WebMoney:  WMZ Z294115950220  WMR R409981405661  WME E134003968233	Visa  4274 3200 2453 6495

Глава 10. Connector/Python API Эта глава содержит описание API для Connector/Python. Примеры нужно рассмотреть, работая на Python 2.7 или Python 3.1 и выше. Они могли бы также работать на более старых версиях (таких как Python 2.4), если они не используют функции, введенные в более новых версиях Python. Например, обработка исключений используя ключевое слово as была введена в Python 2.6 и не будет работать в Python 2.4. Следующий обзор показывает пакет mysql.connector с его модулями. В настоящее время только самые полезные модули, классы и методы для конечных пользователей описаны. mysql.connector errorcode errors connection constants conversion cursor dbapi locales eng client_error protocol utils 10.1. Модуль mysql.connector Модуль mysql.connector предоставляет методы и свойства верхнего уровня. 10.1.1. Метод mysql.connector.connect() Этот метод настраивает связь, устанавливая сессию связи с сервером MySQL. Если никакие аргументы не даны, это использует уже заданные или значения по умолчанию. Для полного списка возможных аргументов посмотрите раздел 7.1. Связь с сервером MySQL может быть установлена, используя метод mysql.connector.connect() или класс mysql.connector.MySQLConnection(): cnx = mysql.connector.connect(user='joe', database='test') cnx = MySQLConnection(user='joe', database='test') Для описаний методов связи и свойств, посмотрите раздел 10.2. 10.1.2. Свойство mysql.connector.apilevel Это свойство последовательность, которая указывает на поддержанный уровень API DB. >>> mysql.connector.apilevel '2.0' 10.1.3. Свойство mysql.connector.paramstyle Это свойство последовательность, которая указывает на стиль параметра Connector/Python по умолчанию. >>> mysql.connector.paramstyle 'pyformat' 10.1.4. Свойство mysql.connector.threadsafety Это свойство целое число, которое указывает на поддержанный уровень потокобезопасности, обеспеченной Connector/Python. >>> mysql.connector.threadsafety 1 10.1.5. Свойство mysql.connector.__version__ Это свойство указывает версию Connector/Python как строку. Это доступно с Connector/Python 1.1.0. >>> mysql.connector.__version__ '1.1.0' 10.1.6. Свойство mysql.connector.__version_info__ Это свойство указывает версию Connector/Python как множество компонентов версии. Это доступно с Connector/Python 1.1.0. >>> mysql.connector.__version_info__ (1, 1, 0, 'a', 0) 10.2. Класс connection.MySQLConnection Класс MySQLConnection используется, чтобы открыть и управлять связью с сервером MySQL. Это также раньше посылало команды и SQL-операторы и читало результаты. 10.2.1. Конструктор connection.MySQLConnection() Синтаксис: cnx = MySQLConnection(**kwargs) Конструктор MySQLConnection инициализирует атрибуты и когда по крайней мере один аргумент передается, он пытается соединиться с сервером MySQL. Для полного списка аргументов посмотрите раздел 7.1. 10.2.2. Метод MySQLConnection.close() Синтаксис: cnx.close() close() синоним disconnect(). См. раздел 10.2.20. Для связи, полученной из пула связи, close() на самом деле не закрывает ее, а возвращает в пул и делает доступной для последующих запросов связи. Посмотрите раздел 9.1. 10.2.3. Метод MySQLConnection.commit() Этот метод посылает COMMIT серверу MySQL, передавая текущую транзакцию. Connector/Python по умолчанию не делает autocommit, поэтому важно вызвать этот метод после каждой транзакции, которая изменяет данные для таблиц с транзакционным механизмом хранения. >>> cursor.execute("INSERT INTO employees (first_name) VALUES (%s)", ('Jane')) >>> cnx.commit() Чтобы откатиться назад вместо этого и отказаться от модификаций, посмотрите метод rollback(). 10.2.4. Метод MySQLConnection.config() Синтаксис: cnx.config(**kwargs) Формирует экземпляр MySQLConnection после того, как это создано. Для полного списка возможных аргументов посмотрите раздел 7.1. Параметры: kwargs: Аргументы соединения. Вы могли использовать метод config(), чтобы изменить (например), имя пользователя, а затем вызвать reconnect(). Пример: cnx = mysql.connector.connect(user='joe', database='test') # Connected as 'joe' cnx.config(user='jane') cnx.reconnect() # Now connected as 'jane' Для связи, полученной из пула связи, config() поднимает исключение. Посмотрите раздел 9.1. 10.2.5. Метод MySQLConnection.connect() Синтаксис: MySQLConnection.connect(**kwargs) Этот метод настраивает связь, устанавливая сессию с сервером MySQL. Если никакие аргументы не даны, это использует уже настроенные или значения по умолчанию. Для полного списка возможных аргументов посмотрите раздел 7.1. Параметры: kwargs: Аргументы соединения. Пример: cnx = MySQLConnection(user='joe', database='test') Для связи, полученной из пула связи, класс объекта связи PooledMySQLConnection. Объединенная связь отличается от необъединенной связи, как описано в разделе 9.1. 10.2.6. Метод MySQLConnection.cursor() Синтаксис: cursor = cnx.cursor([arg=value[, arg=value]...]) Этот метод возвращает объект MySQLCursor() или его подкласс в зависимости от передаваемых аргументов. Возвращенный объект это экземпляр cursor.CursorBase. Для получения дополнительной информации об объектах курсора, посмотрите разделы 10.5 и 10.6. Аргументы могут быть переданы методу cursor(), чтобы контролировать, какой курсор создать: Если buffered = True, курсор приносит все строки от сервера после того, как операция будет выполнена. Это полезно, когда запросы возвращают небольшие наборы результатов. buffered может использоваться один или в сочетании с параметром dictionary или named_tuple. buffered может также быть передан connect(), чтобы установить способ буферизации по умолчанию для всех курсоров, созданных из объекта связи. Посмотрите раздел 7.1. Для получения информации о о последствиях буферизования посмотрите раздел 10.6.1 . Если raw = True, курсор пропускает преобразование от типов данных MySQL в типы Python. Сырой курсор обычно используется, чтобы получить лучшую производительность или когда вы хотите сделать преобразование сами. raw может также быть передан connect(), чтобы установить режим без предварительной обработки по умолчанию для всех курсоров, созданных из объекта связи. Посмотрите раздел 7.1. Если dictionary = True, курсор возвращает строки как словари. Этот аргумент доступен с Connector/Python 2.0.0. Если named_tuple = True, курсор возвращает строки как названные кортежами. Этот аргумент доступен с Connector/Python 2.0.0. Если prepared = True, курсор используется для выполнения подготовленных запросов. Этот аргумент доступен с Connector/Python 1.1.2. Расширение C поддерживает это с Connector/Python 8.0.17. Параметр cursor_class может использоваться, чтобы передать класс для того, чтобы создать новый курсор. Это должен быть подкласс cursor.CursorBase. Возвращенный объект зависит от комбинации аргументов. Примеры: Если not buffered and not raw: MySQLCursor. Если buffered and not raw: MySQLCursorBuffered. Если not buffered and raw: MySQLCursorRaw . Если buffered and raw: MySQLCursorBufferedRaw. 10.2.7. Метод MySQLConnection.cmd_change_user() Изменяет пользователя, использующего username и password. Это также назначит указанную database базой данных по умолчанию. Также возможно изменить набор символов, используя параметр charset. Синтаксис: cnx.cmd_change_user(username='', password='', database='', charset=33) Возвращает словарь, содержащий OK информацию о пакете. 10.2.8. Метод MySQLConnection.cmd_debug() Приказывает серверу писать отладочную информацию в журнал ошибок. Подключенный пользователь должен иметь привилегию SUPER. Возвращает словарь, содержащий OK информацию о пакете. 10.2.9. Метод MySQLConnection.cmd_init_db() Синтаксис: cnx.cmd_init_db(db_name) Этот метод делает определенную базу данных базой данных по умолчанию. В последующих запросах эта база данных будет умолчанием для ссылок на таблицу, которые не включают явного определителя базы данных. Возвращает словарь, содержащий OK информацию о пакете. 10.2.10. Метод MySQLConnection.cmd_ping() Проверка, работает ли связь с сервером. Этот метод не должен использоваться непосредственно. Используйте ping() или is_connected(). Возвращает словарь, содержащий OK информацию о пакете. 10.2.11. Метод MySQLConnection.cmd_process_info() Этот метод поднимает исключение NotSupportedError. Вместо этого используйте SHOW PROCESSLIST или запрос таблицы в базе данных INFORMATION_SCHEMA. Эта функциональность MySQL Server устарела. 10.2.12. Метод MySQLConnection.cmd_process_kill() Синтаксис: cnx.cmd_process_kill(mysql_pid) Эта функциональность MySQL Server устарела. Просит сервер убить поток mysql_pid. Хотя все еще доступно, лучше использовать SQL-оператор KILL. Возвращает словарь, содержащий OK информацию о пакете. Следующие две строки имеют тот же самый эффект: >>> cnx.cmd_process_kill(123) >>> cnx.cmd_query('KILL 123') 10.2.13. Метод MySQLConnection.cmd_query() Синтаксис: cnx.cmd_query(statement) Этот метод посылает данный statement серверу MySQL и получает результат. Чтобы послать многочисленные запросы, используйте cmd_query_iter(). Возвращенный словарь содержит информацию в зависимости от того, какой запрос был выполнен. Если запрос SELECT, результат содержит информацию о столбцах. Другие запросы возвращают словарь, содержащий OK или EOF. Ошибки, полученные от сервера MySQL, подняты как исключения. InterfaceError поднято, когда многократные результаты найдены. Возвращает словарь. 10.2.14. Метод MySQLConnection.cmd_query_iter() Синтаксис: cnx.cmd_query_iter(statement) Аналог cmd_query(), но вернет объект генератора для итерации результата. Используйте cmd_query_iter() посылая многочисленные запросы и отделяете запросы точками с запятой. Следующий пример показывает, как работать с результатами после отправки многочисленных запросов: statement = 'SELECT 1; INSERT INTO t1 VALUES (); SELECT 2' for result in cnx.cmd_query_iter(statement): if 'columns' in result: columns = result['columns'] rows = cnx.get_rows() else: # do something useful with INSERT result Возвращает объект генератора. 10.2.15. Метод MySQLConnection.cmd_quit() Этот метод посылает QUIT серверу MySQL, закрывая текущую связь. С тех пор от сервера MySQL нет никакого ответа, пакет, который послали, возвращен. 10.2.16. Метод MySQLConnection.cmd_refresh() Синтаксис: cnx.cmd_refresh(options) Эта функциональность MySQL Server устарела. Этот метод сбрасывает таблицы или кэши или информацию о сервере репликации. Подключенный пользователь должен иметь привилегию RELOAD. options должен быть значением битовой маски, построенной, используя константы из класса constants.RefreshOption. Для списка вариантов посмотрите раздел 10.11. Пример: >>> from mysql.connector import RefreshOption >>> refresh = RefreshOption.LOG | RefreshOption.THREADS >>> cnx.cmd_refresh(refresh) 10.2.17. Метод MySQLConnection.cmd_reset_connection() Синтаксис: cnx.cmd_reset_connection() Перезагружает связь, посылая COM_RESET_CONNECTION серверу, чтобы очистить состояние сеанса. Этот метод разрешает состоянию сеанса быть очищенным без переподтверждения. Для серверов MySQL, более старых, чем 5.7.3 (когда был введен COM_RESET_CONNECTION), должен использоваться метод reset_session(). Этот метод перезагружает состояние сеанса, повторно подтверждая подлинность, что является более дорогим. Этот метод добавлен в Connector/Python 1.2.1. 10.2.18. Метод MySQLConnection.cmd_shutdown() Эта функциональность MySQL Server устарела. Просит сервер базы данных завершиться. Подключенный пользователь должен иметь привилегию SHUTDOWN. Возвращает словарь, содержащий OK информацию о пакете. 10.2.19. Метод MySQLConnection.cmd_statistics() Возвращает словарь, содержащий информацию о сервере MySQL включая продолжительность работы в секундах и количество работающих потоков, запросов, перезагрузок и открытых таблиц. 10.2.20. Метод MySQLConnection.disconnect() Этот метод пытается послать QUIT и закрыть сокет. Это не поднимает исключений. MySQLConnection.close() синоним этого метода и чаще всего используемый. Чтобы закрыть связь, не посылая QUIT, используйте shutdown(). 10.2.21. Метод MySQLConnection.get_row() Этот метод восстанавливает следующую строку набора результата запроса, возвращая кортеж. Кортеж, возвращенный get_row() состоит из: Строка как кортеж, содержащий объекты байта или None, когда больше строк недоступно. EOF как словарь, содержащий status_flag и warning_count или None, когда возвращенная строка не является последней. Метод get_row() используется MySQLCursor, чтобы получить строки. 10.2.22. Метод MySQLConnection.get_rows() Синтаксис: cnx.get_rows(count=None) Этот метод получает все или остающиеся строки набора результата запроса, возвращая кортеж, содержащий строки как последовательности и EOF. Аргумент количества может использоваться, чтобы получить заданное количество строк. Если количество не определяется или None, все строки возвращаются. Кортеж, возвращенный get_rows() состоит из: Список кортежей, содержащих данные о строке как байт-объекты или пустой список, когда никакие строки недоступны. EOF как словарь, содержащий status_flag и warning_count. InterfaceError поднято, когда все строки были получены. MySQLCursor использует метод get_rows(), чтобы получить строки. Возвращает кортеж. 10.2.23. Метод MySQLConnection.get_server_info() Этот метод возвращает информацию о сервере MySQL дословно как последовательность, например, '5.6.11-log' или None, если не связан. 10.2.24. Метод MySQLConnection.get_server_version() Этот метод возвращает версию сервера MySQL как кортеж или None, если не связан. 10.2.25. Метод MySQLConnection.is_connected() Сообщает, доступна ли связь с MySQL Server. Этот метод проверяет, является ли связь с MySQL доступной, используя метод ping() , но в отличие от этого ping(), is_connected() вернет True, когда связь доступна, False иначе. 10.2.26. Метод MySQLConnection.isset_client_flag() Синтаксис: cnx.isset_client_flag(flag) Этот метод вернет True, если флаг клиента был установлен, False иначе. 10.2.27. Метод MySQLConnection.ping() Синтаксис: cnx.ping(reconnect=False, attempts=1, delay=0) Проверяет, доступна ли связь с сервером MySQL. Когда reconnect = True, сделано attempts попыток снова соединиться с сервером MySQL, и эти опции отправлены методу reconnect(). Используйте метод delay (секунды), если вы хотите ждать перед каждой повторной попыткой. Когда связь недоступна, InterfaceError поднято. Используйте метод is_connected(), чтобы проверить связь, не поднимая ошибку. Поднимает на ошибках InterfaceError. 10.2.28. Метод MySQLConnection.reconnect() Синтаксис: cnx.reconnect(attempts=1, delay=0) Попытка снова соединиться с сервером MySQL. Аргумент attempts определяет число раз, которое надо попробовать снова соединиться. Аргумент delay это число секунд, которое ждать перед каждой повторной попыткой. Вы могли бы определить число попыток выше и использовать более длинную задержку, когда вы ожидаете, что сервер MySQL остановлен для обслуживания, или когда вы будете ожидать, что сеть будет временно недоступна. 10.2.29. Метод MySQLConnection.reset_session() Синтаксис: cnx.reset_session(user_variables = None, session_variables = None) Перезагружает связь, повторно подтверждая подлинность, чтобы очистить состояние сеанса. user_variables, если задан, это словарь имен и значений пользовательских переменных. session_variables, если задан, это словарь словарь имен и значений системных переменных. Метод устанавливает каждую переменную в данное значение. Пример: user_variables = {'var1': '1', 'var2': '10'} session_variables = {'wait_timeout': 100000, 'sql_mode': 'TRADITIONAL'} self.cnx.reset_session(user_variables, session_variables) Этот метод перезагружает состояние сеанса, повторно подтверждая подлинность. Для серверов MySQL 5.7 или выше cmd_reset_connection() более легкая альтернатива. Этот метод добавлен в Connector/Python 1.2.1. 10.2.30. Метод MySQLConnection.rollback() Этот метод посылает серверу MySQL запрос ROLLBACK, отменяя все изменения данных от текущей транзакции. По умолчанию Connector/Python не делает autocommit, таким образом, возможно отменить транзакции, используя механизмы хранения транзакций, например, InnoDB. >>> cursor.execute("INSERT INTO employees (first_name) VALUES (%s)", ('Jane')) >>> cnx.rollback() Чтобы передать модификации, посмотрите метод commit(). 10.2.31. Метод MySQLConnection.set_charset_collation() Синтаксис: cnx.set_charset_collation(charset=None, collation=None) Этот метод устанавливает набор символов и сопоставление для текущей связи. Параметр charset может быть названием набора символов или числовым эквивалентом, как определено в constants.CharacterSet. Когда collation = None, используется сопоставление по умолчанию для набора символов. В следующем примере мы устанавливаем набор символов в latin1 и сопоставление в latin1_swedish_ci (сопоставление по умолчанию для latin1): >>> cnx = mysql.connector.connect(user='scott') >>> cnx.set_charset_collation('latin1') Определите данное сопоставление следующим образом: >>> cnx = mysql.connector.connect(user='scott') >>> cnx.set_charset_collation('latin1', 'latin1_general_ci') 10.2.32. Метод MySQLConnection.set_client_flags() Синтаксис: cnx.set_client_flags(flags) Этот метод устанавливает флаги клиента, соединяясь с сервером MySQL и возвращает новое значение как целое число. Параметр flags может быть целым числом или последовательностью действительных флаговых значений клиента (см. раздел 10.7). Если flags последовательность, каждый пункт в последовательности устанавливает флаг, когда значение положительно или сбрасывает его, когда отрицательно. Например, чтобы сбросить LONG_FLAG и установить FOUND_ROWS: >>> from mysql.connector.constants import ClientFlag >>> cnx.set_client_flags([ClientFlag.FOUND_ROWS, -ClientFlag.LONG_FLAG]) >>> cnx.reconnect() Флаги клиента устанавливаются или используются только соединяясь с сервером MySQL. Поэтому необходимо снова соединиться после внесения изменений. 10.2.33. Метод MySQLConnection.shutdown() Этот метод закрывает сокет. Это не поднимает исключений. В отличие от этого, disconnect(), shutdown() закрывает связь клиента, не пытаясь сначала послать QUIT серверу. Таким образом это не заблокирует, если связь будет разрушена по некоторым причинам, например, из-за отказа сети. shutdown() добавлен в Connector/Python 2.0.1. 10.2.34. Метод MySQLConnection.start_transaction() Этот метод начинает транзакцию. Это принимает аргументы, указывающие, использовать ли последовательный снимок, который уровень изоляции транзакции нужен и операционный режим доступа: cnx.start_transaction(consistent_snapshot=bool, isolation_level=level, readonly=access_mode) По умолчанию consistent_snapshot = False. Если значение True, Connector/Python посылает WITH CONSISTENT SNAPSHOT с запросом. MySQL игнорирует это для уровней изоляции, для которых не применяется этот вариант. По умолчанию isolation_level = None, разрешенные значения: 'READ UNCOMMITTED', 'READ COMMITTED', 'REPEATABLE READ' и 'SERIALIZABLE'. Если isolation_level = None, никакой уровень изоляции не посылают, таким образом, применяется уровень по умолчанию. Параметр readonly может быть True, чтобы начать транзакцию в режиме READ ONLY или False для режима READ WRITE. Если readonly пропущен, режим доступа сервера по умолчанию используется. Для получения дополнительной информации об операционном режиме доступа см. описание для START TRANSACTION в START TRANSACTION, COMMIT, and ROLLBACK Statements. Если сервер более старый, чем MySQL 5.6.5, он не поддерживает настройку режима доступа, и Connector/Python поднимает исключение ValueError. Вызов start_transaction() поднимает исключение ProgrammingError, если вызван в то время, как происходит транзакция. Это отличается от выполнения SQL-запроса START TRANSACTION в то время как происходит транзакция: запрос неявно передает текущую транзакцию. Чтобы определить, активна ли транзакция для связи, используйте свойство in_transaction. start_transaction() добавлен в MySQL Connector/Python 1.1.0. Параметр readonly добавлен в Connector/Python 1.1.5. 10.2.35. Свойство MySQLConnection.autocommit Этому свойству можно назначить значение True или False, чтобы позволить или отключить autocommit в MySQL. Свойство может быть вызвано, чтобы узнать значение autocommit. Autocommit отключен по умолчанию, соединяясь через Connector/Python. Это может быть позволено, используя параметр соединения autocommit. Когда autocommit выключен, необходимо передавать транзакции, используя механизмы системы хранения транзакций, например, InnoDB или NDBCluster. >>> cnx.autocommit False >>> cnx.autocommit = True >>> cnx.autocommit True 10.2.36. Свойство MySQLConnection.unread_results Указывает, есть ли непрочитанный результат. Это установлено в False, если нет непрочитанного результата, иначе True. Это используется курсорами, чтобы проверить, должен ли другой курсор все еще получить свой набор результатов. Не устанавливайте значение этому свойству, поскольку только соединитель должен изменить значение. Другими словами, рассматривайте это как свойство только для чтения. 10.2.37. Свойство MySQLConnection.can_consume_results Это свойство указывает на значение параметра связи consume_results, который управляет, прочитаны ли наборы результатов, произведенные запросами автоматически. См. раздел 7.1. Это добавлено в Connector/Python 2.1.1. 10.2.38. Свойство MySQLConnection.charset Это свойство возвращает последовательность, указывающую, какой набор символов используется для связи. 10.2.39. Свойство MySQLConnection.collation Это свойство возвращает последовательность, указывающую, какое сопоставление используется для связи. 10.2.40. Свойство MySQLConnection.connection_id Это свойство возвращает ID связи (ID потока или сессии) для текущей связи (целое число) или None, если нет связи. 10.2.41. Свойство MySQLConnection.database Это свойство устанавливает текущую базу данных, выполняя запрос USE. Свойство может также использоваться, чтобы узнать текущее имя базы данных. >>> cnx.database = 'test' >>> cnx.database = 'mysql' >>> cnx.database u'mysql' Возвращает последовательность. 10.2.42. Свойство MySQLConnection.get_warnings Этому свойству можно назначить значение True или False, чтобы позволить или отключить автоматическое получение предупреждений. Умолчание False. Свойство может быть применено, чтобы узнать текущее состояние предупреждений. Получение предупреждений автоматически может быть полезным, отлаживая запросы. Курсоры делают предупреждения доступными через метод MySQLCursor.fetchwarnings(). >>> cnx.get_warnings = True >>> cursor.execute('SELECT "a"+1') >>> cursor.fetchall() [(1.0,)] >>> cursor.fetchwarnings() [(u'Warning', 1292, u"Truncated incorrect DOUBLE value: 'a'")] Возвращает True или False. 10.2.43. Свойство MySQLConnection.in_transaction Это свойство вернет True или False, чтобы указать, активна ли транзакция для связи. Значение True независимо от того, начинаете ли вы транзакцию, используя вызов API start_transaction() или непосредственно выполняя SQL-оператор START TRANSACTION или BEGIN. >>> cnx.start_transaction() >>> cnx.in_transaction True >>> cnx.commit() >>> cnx.in_transaction False in_transaction добавлено в MySQL Connector/Python 1.1.0. 10.2.44. Свойство MySQLConnection.raise_on_warnings Этому свойству можно назначить значение True или False, чтобы позволить или отключить, должны ли предупреждения поднять исключения. Умолчание False. Свойство может быть использовано, чтобы узнать текущий режим исключений. Определение raise_on_warnings также установит get_warnings потому что предупреждения должны быть получены, чтобы они могли быть подняты как исключения. Вы могли бы всегда хотеть установить режим SQL, если требуется иметь сервер MySQL, непосредственно сообщающий о предупреждениях как об ошибках (см. раздел 10.2.47). Также хорошо использовать транзакционные механизмы, таким образом транзакции могут быть отменены, ловя исключение. Наборы результатов должны быть получены полностью, прежде чем любое исключение может быть поднято. Следующий пример показывает выполнение запроса, который производит предупреждение: >>> cnx.raise_on_warnings = True >>> cursor.execute('SELECT "a"+1') >>> cursor.fetchall() .. mysql.connector.errors.DataError: 1292: Truncated incorrect DOUBLE value: 'a' Вернет True или False. 10.2.45. Свойство MySQLConnection.server_host Это свойство только для чтения возвращает имя хоста или IP-адрес, используемый для соединения с сервером MySQL. Возвращает последовательность. 10.2.46. Свойство MySQLConnection.server_port Это свойство только для чтения возвращает порт TCP/IP, используемый для соединения с сервером MySQL. Возвращает целое число. 10.2.47. Свойство MySQLConnection.sql_mode Это свойство используется, чтобы получить и установить режимы SQL для текущей связи. Значение должно быть списком различных режимов, отделенных запятой (","), или последовательностью режимов, предпочтительно используя класс constants.SQLMode. Чтобы сбросить все режимы, передайте пустую строку или пустую последовательность. >>> cnx.sql_mode = 'TRADITIONAL,NO_ENGINE_SUBSTITUTION' >>> cnx.sql_mode.split(',') [u'STRICT_TRANS_TABLES', u'STRICT_ALL_TABLES', u'NO_ZERO_IN_DATE', u'NO_ZERO_DATE', u'ERROR_FOR_DIVISION_BY_ZERO', u'TRADITIONAL', u'NO_AUTO_CREATE_USER', u'NO_ENGINE_SUBSTITUTION'] >>> from mysql.connector.constants import SQLMode >>> cnx.sql_mode = [ SQLMode.NO_ZERO_DATE, SQLMode.REAL_AS_FLOAT] >>> cnx.sql_mode u'REAL_AS_FLOAT,NO_ZERO_DATE' Возвращает последовательность. 10.2.48. Свойство MySQLConnection.time_zone Это свойство используется, чтобы установить или узнать переменную сеанса часового пояса для текущей связи. >>> cnx.time_zone = '+00:00' >>> cursor = cnx.cursor() >>> cursor.execute('SELECT NOW()') ; cursor.fetchone() (datetime.datetime(2012, 6, 15, 11, 24, 36),) >>> cnx.time_zone = '-09:00' >>> cursor.execute('SELECT NOW()') ; cursor.fetchone() (datetime.datetime(2012, 6, 15, 2, 24, 44),) >>> cnx.time_zone u'-09:00' Возвращает последовательность. 10.2.49. Свойство MySQLConnection.unix_socket Это свойство только для чтения возвращает файл сокета Unix для соединения с сервером MySQL. Возвращает последовательность. 10.2.50. Свойство MySQLConnection.user Это свойство только для чтения возвращает имя пользователя, используемое для соединения с сервером MySQL. Возвращает строку. 10.3 pooling.MySQLConnectionPool Этот класс предоставляет экземпляр и управление пулами связи. 10.3.1. Конструктор pooling.MySQLConnectionPool Синтаксис: MySQLConnectionPool(pool_name=None, pool_size=5, pool_reset_session=True, **kwargs) Конструктор создает объект, который управляет пулом связи. Параметры: pool_name: Название пула. Если этот аргумент не дан, Connector/Python автоматически производит имя, составленное из значений host, port, user и database в kwargs, именно в этом порядке. Если несколько пулов имеют одинаковое имя, это не ошибка. Приложение, которое должно отличить пулы по их pool_name, должно создать каждый пул с отличным именем. pool_size: Размер пула. Если этот аргумент не дан, умолчание равняется 5. pool_reset_session: Перезагрузить ли переменные сеанса, когда связь возвращена в пул. Этот аргумент был добавлен в Connector/Python 1.1.5. До 1.1.5 переменные сеанса не перезагружаются. kwargs: Дополнительные аргументы соединения, как описано в разделе 7.1. Пример: dbconfig = { "database": "test", "user": "joe", } cnxpool = mysql.connector.pooling.MySQLConnectionPool(pool_name = "mypool", pool_size = 3, **dbconfig) 10.3.2. Метод MySQLConnectionPool.add_connection() Синтаксис: cnxpool.add_connection(cnx = None) Этот метод добавляет новое или существующее соединение MySQLConnection в пул или поднимает исключение PoolError, если пул полон. Параметры: cnx: Объект MySQLConnection, который будет добавлен к пулу. Если этот аргумент отсутствует, пул создает новую связь и добавляет его. Пример: cnxpool.add_connection()# add new connection to pool cnxpool.add_connection(cnx) # add existing connection to pool 10.3.3. Метод MySQLConnectionPool.get_connection() Синтаксис: cnxpool.get_connection() Этот метод возвращает связь из пула или поднимает исключение PoolError, если никакие связи недоступны. Пример: cnx = cnxpool.get_connection() 10.3.4. Метод MySQLConnectionPool.set_config() Синтаксис: cnxpool.set_config(**kwargs) Этот метод устанавливает параметры конфигурации для связей в пуле. Связи, получаемые из пула после использования изменения конфигурации, имеют новые параметры. Связи, полученные перед изменением, остаются незатронутыми, но когда они закрываются (возвращены в пул), будут вновь открыты с новыми параметрами прежде, чем возвращены пулом для последующих запросов связи. Параметры: kwargs: Аргументы соединения. Пример: dbconfig = { "database": "performance_schema", "user": "admin", "password": "password", } cnxpool.set_config(**dbconfig) 10.3.5. Свойство MySQLConnectionPool.pool_name Синтаксис: cnxpool.pool_name Это свойство возвращает название пула связи. Пример: name = cnxpool.pool_name 10.4. pooling.PooledMySQLConnection Этот класс используется MySQLConnectionPool, чтобы возвратить объединенный экземпляр связи. Это также класс, используемый для связей, полученных вызовом метода connect(), который вызывает пул связи (см. раздел 9.1). Объекты связи PooledMySQLConnection подобны необъединенным объектам связи MySQLConnection с этими различиями: Чтобы освбодить объединенную связь, полученную из пула связи, вызовите close() так же, как для любой необъединенной связи. Однако для объединенной связи close() на самом деле не закрывает связь, а возвращает ее в пул и делает доступной для последующих запросов связи. Объединенная связь не может повторно формироваться, используя config(). Изменения связи должны быть сделаны через сам объект пула, как описано в разделе 9.1. У объединенной связи есть свойство pool_name, которое возвращает название пула. 10.4.1. Конструктор pooling.PooledMySQLConnection Синтаксис: PooledMySQLConnection(cnxpool, cnx) Конструктор конструктор берет пул связи и аргументы соединения и возвращает объединенную связь. Это используется классом MySQLConnectionPool. Параметры: cnxpool: Экземпляр MySQLConnectionPool. cnx: Экземпляр MySQLConnection. Пример: pcnx = mysql.connector.pooling.PooledMySQLConnection(cnxpool, cnx) 10.4.2. Метод PooledMySQLConnection.close() Синтаксис: cnx.close() Возвращает объединенную связь в ее пул связи. Для объединенной связи close() на самом деле не закрывает ее, а возвращает ее в пул и делает доступной для последующих запросов связи. Если параметры конфигурации пула изменяются, возвращенная связь закрыта и вновь открыта с новой конфигурацией прежде, чем быть возвращенной из пула снова в ответ на запрос связи. 10.4.3. Метод PooledMySQLConnection.config() Для объединенных связей config() поднимает исключение PoolError. Конфигурация для объединенных связей должна быть реализована, используя объект пула. 10.4.4. Свойство PooledMySQLConnection.pool_name Синтаксис: cnx.pool_name Это свойство возвращает название пула связи, которому принадлежит связь. Пример: cnx = cnxpool.get_connection() name = cnx.pool_name 10.5. cursor.MySQLCursor Класс MySQLCursor порождает объекты, которые могут выполнить операции, такие как SQL-операторы. Объекты курсора взаимодействуют с сервером MySQL, используя объект MySQLConnection. Чтобы создать курсор, используйте метод cursor() объекта связи: import mysql.connector cnx = mysql.connector.connect(database='world') cursor = cnx.cursor() Несколько связанных классов наследуют MySQLCursor. Чтобы создать курсор одного из этих типов, передайте соответствующие аргументы cursor(): MySQLCursorBuffered создает буферизированный курсор. Посмотрите раздел 10.6.1 . cursor = cnx.cursor(buffered=True) MySQLCursorRaw создает сырой курсор. Посмотрите раздел 10.6.2. cursor = cnx.cursor(raw=True) MySQLCursorBufferedRaw создает буферизированный сырой курсор. Посмотрите раздел 10.6.3 . cursor = cnx.cursor(raw=True, buffered=True) MySQLCursorDict создает курсор, который возвращает строки как словари. Посмотрите раздел 10.6.4. cursor = cnx.cursor(dictionary=True) MySQLCursorBufferedDict создает буферизированный курсор, который возвращает строки как словари. Посмотрите раздел 10.6.5. cursor = cnx.cursor(dictionary=True, buffered=True) MySQLCursorNamedTuple создает курсор, который возвращает строки как названные кортежами. Посмотрите раздел 10.6.6 . cursor = cnx.cursor(named_tuple=True) MySQLCursorBufferedNamedTuple создает буферизированный курсор, который возвращает строки как названные кортежами. Посмотрите раздел 10.6.7. cursor = cnx.cursor(named_tuple=True, buffered=True) MySQLCursorPrepared создает курсор для выполнения подготовленных запросов. Посмотрите раздел 10.6.8 . cursor = cnx.cursor(prepared=True) 10.5.1. Конструктор cursor.MySQLCursor В большинстве случаев метод MySQLConnection cursor() используется, чтобы создать объект MySQLCursor: import mysql.connector cnx = mysql.connector.connect(database='world') cursor = cnx.cursor() Также возможно создать курсор, передавая объект MySQLConnection к MySQLCursor: import mysql.connector from mysql.connector.cursor import MySQLCursor cnx = mysql.connector.connect(database='world') cursor = MySQLCursor(cnx) Аргумент соединения дополнительный. Если опущен, курсор создается, но метод execute() поднимает исключение. 10.5.2. Метод MySQLCursor.callproc() Синтаксис: result_args = cursor.callproc(proc_name, args=()) Этот метод вызывает хранимую процедуру, указанную параметром proc_name. Последовательность параметров args должна содержать одну запись для каждого аргумента, который процедура ожидает. callproc() возвращает измененную копию входной последовательности. Входные параметры оставляют нетронутыми. Вывод и параметры ввода/вывода могут быть заменены новыми значениями. Наборы результатов, произведенные хранимой процедурой, автоматически получены и сохранены как экземпляры MySQLCursorBuffered. Для получения дополнительной информации об использовании этих наборов результатов посмотрите stored_results(). Предположим, что хранимая процедура берет два параметра, умножает значения и возвращает результат: CREATE PROCEDURE multiply(IN pFac1 INT, IN pFac2 INT, OUT pProd INT) BEGIN SET pProd := pFac1 * pFac2; END; Следующий пример показывает, как выполнить multiply(): >>> args = (5, 6, 0) # 0 is to hold value of the OUT parameter pProd >>> cursor.callproc('multiply', args) ('5', '6', 30L) Connector/Python 1.2.1 и выше разрешает типам параметра быть определенными. Чтобы сделать это, определите параметр как кортеж с двумя пунктами, состоящий из значения параметра и типа. Предположим, что процедура sp1() имеет это определение: CREATE PROCEDURE sp1(IN pStr1 VARCHAR(20), IN pStr2 VARCHAR(20), OUT pConCat VARCHAR(100)) BEGIN SET pConCat := CONCAT(pStr1, pStr2); END; Чтобы выполнять эту процедуру от Connector/Python, определяя тип для параметра OUT: args = ('ham', 'eggs', (0, 'CHAR')) result_args = cursor.callproc('sp1', args) print(result_args[2]) 10.5.3. Метод MySQLCursor.close() Синтаксис: cursor.close() Этот метод закрывает курсор, перезагружает все результаты и гарантирует, что у объекта курсора нет ссылки на оригинальный объект связи. 10.5.4. Метод MySQLCursor.execute() Синтаксис: cursor.execute(operation, params=None, multi=False) iterator = cursor.execute(operation, params=None, multi=True) Этот метод выполняет данное действие operation с базой данных. Параметры найдены в кортеже или словаре params и связаны с переменными в операции. Определите использование переменных в стиле параметров %s или %(name)s (то есть, используя стиль format или pyformat). execute() возвращает итератор, если multi = True. В Python кортеж, содержащий единственную значение, должен включать запятую. Например, ('abc') оценено как скаляр, в то время как ('abc',) оценено как кортеж. Этот пример вставляет информацию о новом сотруднике, затем выбирает данные для того человека. Запросы выполняются как отдельные действия execute(): insert_stmt = ( "INSERT INTO employees (emp_no, first_name, last_name, hire_date) " "VALUES (%s, %s, %s, %s)" ) data = (2, 'Jane', 'Doe', datetime.date(2012, 3, 23)) cursor.execute(insert_stmt, data) select_stmt = "SELECT * FROM employees WHERE emp_no = %(emp_no)s" cursor.execute(select_stmt, { 'emp_no': 2 }) Значения данных преобразовываются по мере необходимости от объектов Python до чего-то, что MySQL понимает. В предыдущем примере экземпляр datetime.date() преобразовывается в '2012-03-23'. Если multi = True, execute() в состоянии выполнить многочисленные запросы, определенные в operation. Это возвращает итератор, который позволяет обработать результат каждого запроса. Однако использование параметров не работает хорошо в этом случае, и обычно хорошая идея выполнить каждый запрос самостоятельно. Следующий пример выбирает и вставляет данные в одной операции execute() и показывает результат каждого запроса: operation = 'SELECT 1; INSERT INTO t1 VALUES (); SELECT 2' for result in cursor.execute(operation, multi=True): if result.with_rows: print("Rows produced by statement '{}':".format( result.statement)) print(result.fetchall()) else: print("Number of rows affected by statement '{}': {}".format( result.statement, result.rowcount)) Если связь формируется, чтобы получить предупреждения, то все предупреждения, произведенные операцией, доступны через метод MySQLCursor.fetchwarnings(). 10.5.5. Метод MySQLCursor.executemany() Синтаксис: cursor.executemany(operation, seq_of_params) Этот метод готовит operation для базы данных и выполняет его для всех последовательностей параметра или отображений, найденных в последовательности seq_of_params. В Python кортеж, содержащий единственную значение, должен включать запятую. Например, ('abc') оценено как скаляр, в то время как ('abc',) оценено как кортеж. В большинстве случаев метод executemany() повторяет последовательность параметров, каждый раз передавая текущие параметры к методу execute(). Оптимизация применяется для вставок: значения данных, данные последовательностями параметра, скомплектованы, используя синтаксис многократной строки. Следующий пример вставляет три записи: data = [ ('Jane', date(2005, 2, 12)), ('Joe', date(2006, 5, 23)), ('John', date(2010, 10, 3)), ] stmt = "INSERT INTO employees (first_name, hire_date) VALUES (%s, %s)" cursor.executemany(stmt, data) Для предыдущего примера в MySQL послан такой INSERT: INSERT INTO employees (first_name, hire_date) VALUES ('Jane', '2005-02-12'), ('Joe', '2006-05-23'), ('John', '2010-10-03') С методом executemany() невозможно определить многочисленные запросы, чтобы выполнить в параметре operation. Выполнение этого поднимает исключение InternalError. Рассмотрите использование execute() с multi=True. 10.5.6. Метод MySQLCursor.fetchall() Синтаксис: rows = cursor.fetchall() Метод приносит все (или все остающиеся) строки набора результата запроса и возвращает список кортежей. Если больше строк недоступно, это возвращает пустой список. Следующий пример показывает, как получить первые два строки набора результатов, а затем любые остающиеся строки: >>> cursor.execute("SELECT * FROM employees ORDER BY emp_no") >>> head_rows = cursor.fetchmany(size=2) >>> remaining_rows = cursor.fetchall() Необходимо принести все строки для текущего запроса прежде, чем выполнить новые запросы, используя ту же самую связь. 10.5.7. Метод MySQLCursor.fetchmany() Синтаксис: rows = cursor.fetchmany(size=1) Этот метод приносит следующий набор строк результата запроса и возвращает список кортежей. Если больше строк недоступно, это возвращает пустой список. Количество возвращенных строк может быть определено, используя параметр size, который по умолчанию 1. Меньше строк возвращено, если меньше строк доступно, чем указано. Необходимо принести все строки для текущего запроса прежде, чем выполнить новые запросы, используя ту же самую связь. 10.5.8. Метод MySQLCursor.fetchone() Синтаксис: row = cursor.fetchone() Этот метод следующую строку набора результата запроса и возвращает единственную последовательность или None, если больше строк недоступно. По умолчанию возвращенный кортеж состоит из данных, возвращенных сервером MySQL, преобразованных в объекты Python. Если курсор сырой, никакое преобразование не происходит, посмотрите раздел 10.6.2. Метод fetchone() используется fetchall() и fetchmany() . Это также используется, когда курсор используется в качестве итератора. Следующий пример показывает два эквивалентных способа обработать результат запроса. Первое использование fetchone() в цикле while, второе использование курсора как итератора: # Using a while loop cursor.execute("SELECT * FROM employees") row = cursor.fetchone() while row is not None: print(row) row = cursor.fetchone() # Using the cursor as iterator cursor.execute("SELECT * FROM employees") for row in cursor: print(row) Необходимо принести все строки для текущего запроса прежде, чем выполнить новые запросы, используя ту же самую связь. 10.5.9. Метод MySQLCursor.fetchwarnings() Синтаксис: tuples = cursor.fetchwarnings() Этот метод возвращает список кортежей, содержащих предупреждения, произведенные ранее выполненной операцией. Чтобы установить, получать ли предупреждения, используйте свойство соединения get_warnings. Следующий пример показывает SELECT, который производит предупреждение: >>> cnx.get_warnings = True >>> cursor.execute("SELECT 'a'+1") >>> cursor.fetchall() [(1.0,)] >>> cursor.fetchwarnings() [(u'Warning', 1292, u"Truncated incorrect DOUBLE value: 'a'")] Когда предупреждения произведены, возможно поднять ошибки вместо этого, используя свойство соединения raise_on_warnings. 10.5.10. Метод MySQLCursor.stored_results() Синтаксис: iterator = cursor.stored_results() Этот метод возвращает список итераторов, который может использоваться, чтобы обработать наборы результатов, произведенные хранимой процедурой, выполненной, используя метод callproc(). Наборы результатов остаются доступными, пока вы не используете курсор, чтобы выполнить другую операцию или вызвать другую хранимую процедуру. Следующий пример выполняет хранимую процедуру, которая производит два набора результатов, затем использует stored_results(), чтобы получить их: >>> cursor.callproc('myproc') () >>> for result in cursor.stored_results(): ... print result.fetchall() ... [(1,)] [(2,)] 10.5.11. Свойство MySQLCursor.column_names Синтаксис: sequence = cursor.column_names Это свойство только для чтения возвращает имена столбцов набора результатов как последовательность строк Unicode. Следующий пример показывает, как создать словарь из кортежа, содержащего данные с использованием ключей column_names: cursor.execute("SELECT last_name, first_name, hire_date " "FROM employees WHERE emp_no = %s", (123,)) row = dict(zip(cursor.column_names, cursor.fetchone())) print("{last_name}, {first_name}: {hire_date}".format(row)) Альтернативно, с Connector/Python 2.0.0 можно принести строки как словари непосредственно, посмотрите раздел 10.6.4. 10.5.12. Свойство MySQLCursor.description Синтаксис: tuples = cursor.description Это свойство только для чтения возвращает список кортежей, описывающих колонки в наборе результатов. Каждый кортеж в списке содержит значения следующим образом: (column_name, type, None, None, None, None, null_ok, column_flags) Следующий пример показывает, как интерпретировать кортежи description: import mysql.connector from mysql.connector import FieldType ... cursor.execute("SELECT emp_no, last_name, hire_date " "FROM employees WHERE emp_no = %s", (123,)) for i in range(len(cursor.description)): print("Column {}:".format(i+1)) desc = cursor.description[i] print("column_name = {}".format(desc[0])) print("type = {} ({})".format(desc[1], FieldType.get_info(desc[1]))) print("null_ok = {}".format(desc[6])) print("column_flags = {}".format(desc[7])) Вывод похож на это: Column 1: column_name = emp_no type = 3 (LONG) null_ok = 0 column_flags = 20483 Column 2: column_name = last_name type = 253 (VAR_STRING) null_ok = 0 column_flags = 4097 Column 3: column_name = hire_date type = 10 (DATE) null_ok = 0 column_flags = 4225 column_flags это экземпляр класса constants.FieldFlag. Чтобы видеть, как интерпретировать его, сделайте это: >>> from mysql.connector import FieldFlag >>> FieldFlag.desc 10.5.13. Свойство MySQLCursor.lastrowid Синтаксис: id = cursor.lastrowid Это свойство только для чтения возвращает значение, произведенное для столбца AUTO_INCREMENT последним INSERT или UPDATE, или None, когда нет такого доступного значения. Например, если вы скомандуете INSERT на таблице, которая содержит столбец AUTO_INCREMENT, lastrowid вернет значение AUTO_INCREMENT для новой строки. Для примера посмотрите раздел 5.3 . Свойство lastrowid похоже на функцию C API mysql_insert_id(), см. mysql_insert_id(). 10.5.14. Свойство MySQLCursor.rowcount Синтаксис: count = cursor.rowcount Это свойство только для чтения возвращает количество строк, возвращенных для SELECT или количество строк, затронутых запросами DML, например, INSERT или UPDATE. Для примера посмотрите раздел 10.5.4 . Для небуферизированных курсоров не может быть известно количество строк прежде, чем строки были принесены. В этом случае количество строк -1 немедленно после выполнения запроса и увеличено, по мере получения строк. Свойство rowcount аналогично функции C API mysql_affected_rows(), см. mysql_affected_rows(). 10.5.15. Свойство MySQLCursor.statement Синтаксис: str = cursor.statement Это свойство только для чтения возвращает последний выполненный запрос как последовательность. Свойство statement может быть полезно для отладки и показа, что послали в сервер MySQL. Последовательность может содержать многочисленные запросы, если последовательность многократных запросов была выполнена. Это происходит для execute() с multi=True. В этом случае свойство statement содержит всю последовательность запросов и вызов execute() вернет итератор, который может использоваться, чтобы обработать следствия отдельных запросов. Свойство statement для этого итератора показывает последовательности запроса для отдельных запросов. 10.5.16. Свойство MySQLCursor.with_rows Синтаксис: boolean = cursor.with_rows Это свойство только для чтения вернет True или False, чтобы указать, произвела ли последний раз выполненная операция строки. Свойство with_rows полезно, когда необходимо определить, производит ли запрос набор результатов и получить строки. Следующий пример получает строки, возвращенные SELECT, но только затронутые строки оцениваются для UPDATE: import mysql.connector cnx = mysql.connector.connect(user='scott', database='test') cursor = cnx.cursor() operation = 'SELECT 1; UPDATE t1 SET c1 = 2; SELECT 2' for result in cursor.execute(operation, multi=True): if result.with_rows: result.fetchall() else: print("Number of affected rows: {}".format(result.rowcount)) 10.6. Субклассы cursor.MySQLCursor Классы курсора, описанные в следующих разделах, наследуют от класса MySQLCursor, который описан в разделе 10.5. 10.6.1. Класс cursor.MySQLCursorBuffered Класс MySQLCursorBuffered наследует от MySQLCursor. После выполнения запроса курсор MySQLCursorBuffered получает весь набор результатов от сервера и буферизует строки. Для запросов, выполненных, используя буферизированный курсор, получающие строки методы, такие как fetchone(), вернут строки из набора буферизированных строк. Для небуферизированных курсоров строки не получены от сервера, пока метод, получающий строки, не вызывают. В этом случае, несомненно, необходимо будет получить все строки набора результатов прежде, чем выполнить любые другие запросы на той же самой связи, или будет поднято исключение InternalError (Unread result found). MySQLCursorBuffered может быть полезным в ситуациях, где многократные запросы с небольшими наборами результатов должны быть объединены или вычислены друг с другом. Чтобы создать буферизированный курсор, используйте аргумент buffered, вызывая метод связи cursor(). Альтернативно, чтобы сделать все курсоры, созданные из связи, буферизованными по умолчанию, используйте параметр связи buffered. Пример: import mysql.connector cnx = mysql.connector.connect() # Only this particular cursor will buffer results cursor = cnx.cursor(buffered=True) # All cursors created from cnx2 will be buffered by default cnx2 = mysql.connector.connect(buffered=True) Для случая практического применения посмотрите раздел 6.1. 10.6.2. Класс cursor.MySQLCursorRaw Класс MySQLCursorRaw унаследован от MySQLCursor. Курсор MySQLCursorRaw пропускает преобразование от типов данных MySQL до типов Python, когда получает строки. Сырой курсор обычно используется, чтобы получить лучшую производительность или когда вы хотите сделать преобразование сами. Чтобы создать сырой курсор, используйте параметр raw, вызывая метод связи cursor(). Альтернативно, чтобы сделать все курсоры, созданные из связи, сырыми по умолчанию, используйте параметр связи raw. Пример: import mysql.connector cnx = mysql.connector.connect() # Only this particular cursor will be raw cursor = cnx.cursor(raw=True) # All cursors created from cnx2 will be raw by default cnx2 = mysql.connector.connect(raw=True) 10.6.3. Класс cursor.MySQLCursorBufferedRaw Класс MySQLCursorBufferedRaw унаследован от MySQLCursor. Курсор MySQLCursorBufferedRaw похож на MySQLCursorRaw, но буферизован: после выполнения запроса это получает весь набор результатов от сервера и буферизует строки. Для получения информации о последствиях буферизования посмотрите раздел 10.6.1. Чтобы создать буферизированный сырой курсор, используйте метод raw и параметр buffered, когда вызываете метод соединения cursor(). Альтернативно, чтобы сделать все курсоры созданными сырыми и буферизованными по умолчанию, используйте параметры соединения raw и buffered. Пример: import mysql.connector cnx = mysql.connector.connect() # Only this particular cursor will be raw and buffered cursor = cnx.cursor(raw=True, buffered=True) # All cursors created from cnx2 will be raw and buffered by default cnx2 = mysql.connector.connect(raw=True, buffered=True) 10.6.4. Класс cursor.MySQLCursorDict Класс MySQLCursorDict унаследован от MySQLCursor. Этот класс доступен с Connector/Python 2.0.0. Курсор MySQLCursorDict возвращает каждую строку как словарь. Ключи для каждого объекта словаря это имена столбцов результата MySQL. Пример: cnx = mysql.connector.connect(database='world') cursor = cnx.cursor(dictionary=True) cursor.execute("SELECT * FROM country WHERE Continent = 'Europe'") print("Countries in Europe:") for row in cursor: print("* {Name}".format(Name=row['Name'] Предыдущий код производит такой вывод: Countries in Europe: * Albania * Andorra * Austria * Belgium * Bulgaria ... Может быть удобно передать словарь в format(): cursor.execute("SELECT Name, Population FROM country WHERE Continent = 'Europe'") print("Countries in Europe with population:") for row in cursor: print("* {Name}: {Population}".format(**row)) 10.6.5. Класс cursor.MySQLCursorBufferedDict Класс MySQLCursorBufferedDict унаследован от MySQLCursor. Этот класс доступен с Connector/Python 2.0.0. Курсор MySQLCursorBufferedDict аналогичен MySQLCursorDict, но буферизован: после выполнения запроса это получает весь набор результатов от сервера и буферизует строки. Для получения информации о последствиях буферизования посмотрите раздел 10.6.1. Чтобы получить буферизированный курсор, который возвращает словари, добавьте параметр buffered, создлавая новый курсор словаря: cursor = cnx.cursor(dictionary=True, buffered=True) 10.6.6. Класс cursor.MySQLCursorNamedTuple Класс MySQLCursorNamedTuple унаследован от MySQLCursor. Этот класс доступен с Connector/Python 2.0.0. Курсор MySQLCursorNamedTuple возвращает каждую строку как названный кортеж. Признаки для каждого объекта названного кортежа это имена столбцов результата MySQL. Пример: cnx = mysql.connector.connect(database='world') cursor = cnx.cursor(named_tuple=True) cursor.execute("SELECT * FROM country WHERE Continent = 'Europe'") print("Countries in Europe with population:") for row in cursor: print("* {Name}: {Population}".format(Name=row.Name, Population=row.Population)) 10.6.7. Класс cursor.MySQLCursorBufferedNamedTuple Класс MySQLCursorBufferedNamedTuple унаследован от MySQLCursor. Этот класс доступен с Connector/Python 2.0.0. Курсор MySQLCursorBufferedNamedTuple аналогичен MySQLCursorNamedTuple, но буферизован: после выполнения запроса это получает весь набор результатов от сервера и буферизует строки. Для получения информации о последствиях буферизования посмотрите раздел 10.6.1. Чтобы получить буферизированный курсор, который возвращает названные кортежи, добавьте параметр buffered при создании нового курсора названного кортежа: cursor = cnx.cursor(named_tuple=True, buffered=True) 10.6.8. Класс cursor.MySQLCursorPrepared Класс MySQLCursorPrepared унаследован от MySQLCursor. Этот класс доступен с Connector/Python 1.1.0. Расширение C поддерживает его с Connector/Python 8.0.17. В MySQL есть два способа выполнить подготовленный запрос: Использовать запросы PREPARE и EXECUTE. Используйте двоичный протокол клиент-сервер, чтобы послать и получить данные. Чтобы неоднократно выполнить тот же самый запрос с различными данными для различного выполнения, это более эффективно, чем использование PREPARE и EXECUTE. Для получения информации о протоколе двоичной синхронной передачи данных см. C API Prepared Statements. В Connector/Python есть два способа создать курсор, который позволяет выполнение подготовленных запросов, используя протокол двоичной синхронной передачи данных. В обоих случаях метод cursor() объекта связи возвращает объект MySQLCursorPrepared: Более простой синтаксис использует параметр prepared=True метода cursor(). Этот синтаксис доступен с Connector/Python 1.1.2. import mysql.connector cnx = mysql.connector.connect(database='employees') cursor = cnx.cursor(prepared=True) Альтернативно, создайте экземпляр класса MySQLCursorPrepared, используя аргумент cursor_class метода cursor(). Этот синтаксис доступен с Connector/Python 1.1.0. import mysql.connector from mysql.connector.cursor import MySQLCursorPrepared cnx = mysql.connector.connect(database='employees') cursor = cnx.cursor(cursor_class=MySQLCursorPrepared) Курсор, порожденный от класса MySQLCursorPrepared, работает так: В первый раз вы передаете запрос методу execute() курсора, это готовит запрос. Для последующих вызовов execute() фаза подготовки пропускается, если запрос тот же самый Метод execute() берет дополнительный второй аргумент, содержащий список значений данных, чтобы связать с маркерами параметра в запросе. Если аргумент списка присутствует, должно быть одно значение на маркер параметра. Пример: cursor = cnx.cursor(prepared=True) stmt = "SELECT fullname FROM employees WHERE id = %s" # (1) cursor.execute(stmt, (5,))# (2) # ... fetch data ... cursor.execute(stmt, (10,)) # (3) # ... fetch data ... %s в рамках запроса это маркер параметра. Не помещайте отметки цитаты вокруг маркеров параметра. Для первого вызова execute() курсор готовит запрос. Если данные даны в том же самом вызове, они также выполняют запрос и необходимо получить данные. Для последующего вызова execute(), который передает тот же самый SQL-оператор, курсор пропускает фазу подготовки. Подготовленные запросы, выполненные с MySQLCursorPrepared, могут использовать стиль параметров format (%s) или qmark (?). Это отличается от неподготовленных запросов, выполненных с MySQLCursor, которые могут использовать стиль параметров format или pyformat. Чтобы использовать многочисленные подготовленные запросы одновременно, создайте многократные курсоры от класса MySQLCursorPrepared. У протокола MySQL клиент-сервер есть опция послать подготовленные параметры операторов через команду COM_STMT_SEND_LONG_DATA. Чтобы использовать это из скрипта Connector/Python, пошлите параметр в запросе, используя интерфейс IOBase. Пример: from io import IOBase ... cur = cnx.cursor(prepared=True) cur.execute("SELECT (%s)", (io.BytesIO(bytes("A", "latin1")), )) 10.7. Класс constants.ClientFlag Этот класс предоставляет определение констант флагов клиента MySQL, которые могут использоваться, когда связь устанавливается, чтобы формировать сессию. Класс ClientFlag доступен, импортируя mysql.connector. >>> import mysql.connector >>> mysql.connector.ClientFlag.FOUND_ROWS 2 См. раздел 10.2.32 и параметры соединения client_flag. ClientFlag не может создавать экземпляры. 10.8. Класс constants.FieldType Этот класс обеспечивает все поддержанные поля MySQL или типы данных. Они могут быть полезными, имея дело с необработанными данными или определяя ваши собственные конвертеры. Тип поля хзранится с курсором в описании для каждого столбца. Следующий пример показывает, как напечатать название типа данных для каждого столбца в наборе результатов. from __future__ import print_function import mysql.connector from mysql.connector import FieldType cnx = mysql.connector.connect(user='scott', database='test') cursor = cnx.cursor() cursor.execute("SELECT DATE(NOW()) AS `c1`, TIME(NOW()) AS `c2`, " "NOW() AS `c3`, 'a string' AS `c4`, 42 AS `c5`") rows = cursor.fetchall() for desc in cursor.description: colname = desc[0] coltype = desc[1] print("Column {} has type {}".format(colname, FieldType.get_info(coltype))) cursor.close() cnx.close() FieldType не может создавать экземпляры. 10.9. Класс constants.SQLMode Этот класс предоставляет все известные режимы SQL. Это главным образом используется, устанавливая режимы SQL во время связи, используя свойство связи sql_mode, см. раздел 10.2.47. Класс SQLMode не может создавать экземпляры. 10.10. Класс constants.CharacterSet Этот класс обеспечивает все известные наборы символов MySQL и их сопоставления по умолчанию. Для примеров посмотрите раздел 10.2.31. Класс CharacterSet не может создавать экземпляры. 10.11. Класс constants.RefreshOption Этот класс выполняет различные операции по сбросу. RefreshOption.GRANT Освежить таблицы привилегий, аналогично FLUSH PRIVILEGES. RefreshOption.LOG Сбросить журналы как FLUSH LOGS. RefreshOption.TABLES Сбросить кэш таблиц как FLUSH TABLES. RefreshOption.HOSTS Сбросить кэш хоста как FLUSH HOSTS. RefreshOption.STATUS Сбросить переменные статуса аналогично FLUSH STATUS. RefreshOption.THREADS Сбросить кэш потоков. RefreshOption.SLAVE На подчиненном сервере репликации сбросить информацию о главном сервере и перезапустить подчиненного аналогично RESET SLAVE. 10.12. Ошибки и исключения Модуль mysql.connector.errors определяет классы исключений для ошибок и предупреждений, поднятых MySQL Connector/Python. Большинство классов, определенных в этом модуле, доступно, когда вы импортируете mysql.connector. Классы исключений, определенные в этом модуле главным образом, следуют спецификации Python Database API Specification v2.0 (PEP 249). Для некоторых клиентов MySQL или ошибок сервера не всегда ясно, которое исключение поднять. Ошибки MySQL Server отображены на исключения Python на основе их значения SQLSTATE (см. Server Error Message Reference). Следующая таблица показывает классы SQLSTATE и исключения поднимаемые Connector/Python. Однако, возможно пересмотреть, какое исключение поднято для каждой ошибки сервера. Исключение по умолчанию DatabaseError. Таблица 10.1. Отображение ошибок сервера к исключениям Python Класс SQLSTATE Исключение Connector/Python 02 DataError 02 DataError 07 DatabaseError 08 OperationalError 0A NotSupportedError 21 DataError 22 DataError 23 IntegrityError 24 ProgrammingError 25 ProgrammingError 26 ProgrammingError 27 ProgrammingError 28 ProgrammingError 2A ProgrammingError 2B DatabaseError 2C ProgrammingError 2D DatabaseError 2E DatabaseError 33 DatabaseError 34 ProgrammingError 35 ProgrammingError 37 ProgrammingError 3C ProgrammingError 3D ProgrammingError 3F ProgrammingError 40 InternalError 42 ProgrammingError 44 InternalError HZ OperationalError XA IntegrityError 0K OperationalError HY DatabaseError 10.12.1. Модуль errorcode Этот модуль содержит коды ошибок клиента и сервера MySQL, определенные как атрибуты модуля с кодом ошибки как значение. Используя коды ошибок вместо номеров ошибок можно сделать чтение исходного кода немного легче. >>> from mysql.connector import errorcode >>> errorcode.ER_BAD_TABLE_ERROR 1051 Для получения дополнительной информации об ошибках MySQL посмотрите Errors, Error Codes, and Common Problems. 10.12.2. Исключение errors.Error Это исключение базовый класс для всех других исключений в модуле errors. Это может использоваться, чтобы зафиксировать все ошибки в одном запросе except. Следующий пример показывает, как мы могли поймать синтаксические ошибки: import mysql.connector try: cnx = mysql.connector.connect(user='scott', database='employees') cursor = cnx.cursor() cursor.execute("SELECT * FORM employees") # Syntax error in query cnx.close() except mysql.connector.Error as err: print("Something went wrong: {}".format(err)) Инициализация исключения поддерживает несколько дополнительных аргументов, а именно msg, errno, values и sqlstate. Все они дополнительные и по умолчанию None. errors.Error внутренне используется Connector/Python, чтобы поднять ошибки клиент-сервера MySQL и не должен использоваться вашим приложением, чтобы поднять исключения. Следующие примеры показывают результат, не используя аргументов или комбинации аргументов: >>> from mysql.connector.errors import Error >>> str(Error()) 'Unknown error' >>> str(Error("Oops! There was an error.")) 'Oops! There was an error.' >>> str(Error(errno=2006)) '2006: MySQL server has gone away' >>> str(Error(errno=2002, values=('/tmp/mysql.sock', 2))) "2002: Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2)" >>> str(Error(errno=1146, sqlstate='42S02', msg="Table 'test.spam' doesn't exist")) "1146 (42S02): Table 'test.spam' doesn't exist" Пример, который использует код ошибки 1146, используется, когда Connector/Python получает ошибочный пакет от сервера MySQL. Информация разобрана и передана к исключению Error. Каждый подкласс исключения от Error может быть инициализирован, используя ранее упомянутые аргументы. Кроме того, у каждого экземпляра есть атрибуты errno, msg и sqlstate, которые могут использоваться в вашем коде. Следующий пример показывает, как обработать ошибки, когда удаляемая таблица не существует (когда DROP TABLE не включает IF EXISTS): import mysql.connector from mysql.connector import errorcode cnx = mysql.connector.connect(user='scott', database='test') cursor = cnx.cursor() try: cursor.execute("DROP TABLE spam") except mysql.connector.Error as err: if err.errno == errorcode.ER_BAD_TABLE_ERROR: print("Creating table spam") else: raise До Connector/Python 1.1.1 исходное сообщение, переданное errors.Error(), не сохранено так, чтобы это могло быть прочитано. Вместо этого атрибут Error.msg был отформатирован со значением SQLSTATE и кодом ошибки. С 1.1.1 только исходное сообщение сохраняется в атрибуте Error.msg. Отформатированное значение вместе с кодом ошибки и значением SQLSTATE может быть получено, печатая или получая строковое представление ошибочного объекта. Пример: try: conn = mysql.connector.connect(database = "baddb") except mysql.connector.Error as e: print "Error code:", e.errno# error number print "SQLSTATE value:", e.sqlstate # SQLSTATE value print "Error message:", e.msg # error message print "Error:", e # errno, sqlstate, msg values s = str(e) print "Error:", s # errno, sqlstate, msg values errors.Error это подкласс Python StandardError. 10.12.3. Исключение errors.DataError Это исключение поднято, когда были проблемы с данными. Примеры: установка столбца в NULL, когда это не может быть NULL, выход значения из диапазона для столбца, деление на нуль, количество столбцов не соответствует количеству значений и т.д. errors.DataError это подкласс errors.DatabaseError. 10.12.4. Исключение errors.DatabaseError Это исключение является умолчанием для любой ошибки MySQL, которая не соответствует другим исключениям. errors.DatabaseError это подкласс errors.Error. 10.12.5. Исключение errors.IntegrityError Это исключение поднято, когда относительная целостность данных затронута. Например, двойной ключ был вставлен или ограничение внешнего ключа неудачно. Следующий пример показывает, что ошибка дублирования ключа подняла IntegrityError: cursor.execute("CREATE TABLE t1 (id int, PRIMARY KEY (id))") try: cursor.execute("INSERT INTO t1 (id) VALUES (1)") cursor.execute("INSERT INTO t1 (id) VALUES (1)") except mysql.connector.IntegrityError as err: print("Error: {}".format(err)) errors.IntegrityError это подкласс errors.DatabaseError. 10.12.6. Исключение errors.InterfaceError Это исключение поднято для ошибок, происходящих из самого Connector/Python, не связанных с сервером MySQL. errors.InterfaceError это подкласс errors.Error. 10.12.7. Исключение errors.InternalError Это исключение поднято, когда сервер MySQL сталкивается с внутренней ошибкой, например, когда мертвая блокировка произошла. errors.InternalError это подкласс errors.DatabaseError. 10.12.8. Исключение errors.NotSupportedError Это исключение поднято, когда была использована некоторая функция, которая не поддерживается версией MySQL, которая возвратила ошибку. Это также поднято, используя функции или запросы, которые не поддерживаются сохраненными подпрограммами. errors.NotSupportedError это подкласс errors.DatabaseError. 10.12.9. errors.OperationalError Это исключение поднято для ошибок, которые связаны с действиями MySQL. Например: слишком много связей, имя хоста не могло быть найдено, плохое рукопожатие, сервер закрывается, ошибки связи. errors.OperationalError это подкласс errors.DatabaseError. 10.12.10. Исключение errors.PoolError Это исключение поднято для ошибок пула связи. errors.PoolError это подкласс errors.Error. 10.12.11. Исключение errors.ProgrammingError Это исключение поднято на программных ошибках, например когда у вас есть синтаксическая ошибка в SQL или таблица не была найдена. Следующий пример показывает, как обращаться с синтаксическими ошибками: try: cursor.execute("CREATE DESK t1 (id int, PRIMARY KEY (id))") except mysql.connector.ProgrammingError as err: if err.errno == errorcode.ER_SYNTAX_ERROR: print("Check your syntax!") else: print("Error: {}".format(err)) errors.ProgrammingError это подкласс errors.DatabaseError. 10.12.12. Исключение errors.Warning Это исключение используется для сообщения о важных предупреждениях, однако, Connector/Python не использует его. Это включено, чтобы быть совместимым с Python Database Specification v2.0 (PEP-249). Рассмотрите использование более строгого режима SQL или параметра соединения raise_on_warnings, чтобы заставить Connector/Python поднять ошибки, когда ваши запросы произведут предупреждения. errors.Warning это подкласс Python StandardError. 10.12.13. Функция errors.custom_error_exception() Синтаксис: errors.custom_error_exception(error=None, exception=None) Этот метод определяет исключения для ошибок сервера MySQL и возвращает текущие настройки. Если error это номер ошибки MySQL Server, необходимо также передать класс exception. Аргумент error может быть словарем, в этом случае ключ это код ошибки сервера, а значение это класс исключения, которое будет поднято. Чтобы перезагрузить настройки, задайте пустой словарь. import mysql.connector from mysql.connector import errorcode # Server error 1028 should raise a DatabaseError mysql.connector.custom_error_exception(1028, mysql.connector.DatabaseError) # Or using a dictionary: mysql.connector.custom_error_exception({ 1028: mysql.connector.DatabaseError, 1029: mysql.connector.OperationalError, }) # To reset, pass an empty dictionary: mysql.connector.custom_error_exception({})

Поиск На сайте В Яндексе

Вы можете направить письмо администратору этой странички, Алексею Паутову.