Чтение онлайн

Интерфейс модуля

Здесь необходимо сказать о том, что должен предоставлять модуль для удовлетворения требований DB–API 2.0.

Доступ к базе данных осуществляется с помощью объекта–соединения (connection object). DB–API–совместимый модуль должен предоставлять функцию–конструктор connect для класса объектов–соединений. Конструктор должен иметь следующие именованные параметры:

dsn Название источника данных в виде строки

user Имя пользователя

password Пароль

host Адрес хоста, на котором работает СУБД

database Имя базы данных.

Методы объекта–соединения будут рассмотрены чуть позже.

Модуль определяет константы, содержащие его основные характеристики:

apilevel Версия DB–API («1.0» или «2.0»).

threadsafety Целочисленная константа, описывающая возможности модуля при использовании потоков управления:

0 Модуль не поддерживает потоки.

1 Потоки могут совместно использовать модуль, но не соединения.

2 Потоки могут совместно использовать модуль и соединения.

3 Потоки могут совместно использовать модуль, соединения и курсоры. (Под совместным использованием здесь понимается возможность использования упомянутых ресурсов без применения семафоров).

paramstyle Тип используемых пометок при подстановке параметров. Возможны следующие значения этой константы:

«format» Форматирование в стиле языка ANSI C (например, "%s», "%i»).

«pyformat» Использование именованных спецификаторов формата в стиле Python ("%(item)s»)

«qmark» Использование знаков "?» для пометки мест подстановки параметров.

«numeric» Использование номеров позиций (":1»).

«named» Использование имен подставляемых параметров (":name»).

Модуль должен определять ряд исключений для обозначения типичных исключительных ситуаций: Warning (предупреждение), Error (ошибка), InterfaceError (ошибка интерфейса), DatabaseError (ошибка, относящаяся к базе данных). А также подклассы этого последнего исключения: DataError (ошибка обработки данных), OperationalError (ошибка в работе или сбой соединения с базой данных), IntegrityError (ошибка целостности базы данных), InternalError (внутренняя ошибка базы данных), ProgrammingError (программная ошибка, например, ошибка в синтаксисе SQL–запроса), NotSupportedError (при отсутствии поддержки запрошенного свойства).

Объект–соединение

Объект–соединение, получаемый в результате успешного вызова функции connect, должен иметь следующие методы:

close Закрывает соединение с базой данных.

commit Завершает транзакцию.

rollback Откатывает начатую транзакцию (восстанавливает исходное состояние). Закрытие соединения при незавершенной транзакции автоматически производит откат транзакции.

cursor Возвращает объект–курсор, использующий данное соединение. Если база данных не поддерживает курсоры, модуль сопряжения должен их имитировать.

Под транзакцией понимается группа из одной или нескольких операций, которые изменяют базу данных. Транзакция соответствует логически неделимой операции над базой данных, а частичное выполнение транзакции приводит к нарушению целостности БД. Например, при переводе денег с одного счета на другой операции по уменьшению первого счета и увеличению второго являются транзакцией. Методы commit и rollback обозначают начало и конец транзакции в явном виде. Кстати, не все базы данных поддерживают механизм транзакций.

Следует отметить, что в зависимости от реализации DB–API 2.0 модуля, необходимо сохранять ссылку на объект–соединение в продолжение работы курсоров этого соединения. В частности, это означает, что нельзя сразу же получать объект–курсор, не привязывая объект–соединение к некоторому имени. Также нельзя оставлять объект–соединение в локальной переменной, возвращая из функции или метода объект–курсор.

Объект–курсор

Курсор (от англ. cursor — CURrrent Set Of Records, текущий набор записей) служит для работы с результатом запроса. Результатом запроса обычно является одна или несколько прямоугольных таблиц со столбцами–полями и строками–записями. Приложение может читать и обрабатывать полученные таблицы и записи в таблице по одной, поэтому в курсоре хранится информация о текущей таблице и записи. Конкретный курсор в любой момент времени связан с выполнением одной SQL–инструкции.

Атрибуты объекта–курсора тоже определены DB–API:

arraysize Атрибут, равный количеству записей, возвращаемых методом fetchmany. По умолчанию равен 1.

callproc(procname[, params]) Вызывает хранимую процедуру procname с параметрами из изменчивой последовательности params. Хранимая процедура может изменить значения некоторых параметров последовательности. Метод может возвратить результат, доступ к которому осуществляется через fetch–методы.

close Закрывает объект–курсор.

description Этот доступный только для чтения атрибут является последовательностью из семиэлементных последовательностей. Каждая из этих последовательностей содержит информацию, описывающую один столбец результата:

(name, type_code, display_size, internal_size, precision, scale, null_ok) Первые два элемента (имя и тип) обязательны, а вместо остальных (размер для вывода, внутренний размер, точность, масштаб, возможность задания пустого значения) может быть значение None. Этот атрибут может быть равным None для операций, не возвращающих значения.

execute(operation[, parameters]) Исполняет запрос к базе данных или команду СУБД. Параметры (parameters) могут быть представлены в принятой в базе данных нотации в соответствии с атрибутом paramstyle, описанным выше.

executemany(operation, seq_of_parameters) Выполняет серию запросов или команд, подставляя параметры в заданный шаблон. Параметр seq_of_parameters задает последовательность наборов параметров.

fetchall Возвращает все (или все оставшиеся) записи результата запроса.