Домой Edit me on GitHub

2020-12-05

Каналы передачи данных | Сетевое программирование | Базы данных | Основы Веб-программирования

DB-API 2.0

См.также

Несмотря на стандарт SQL (ISO/IEC 9075), отдельные СУБД имеют много различий. Чтобы программистам не вникать в реализацию каждой из них, придумали общее API (PEP 249) скрывающее эти детали. Любой Python пакет реализующий это API взаимозаменяем.

PEP 249 это только спецификация, реализацию которой вам придется выполнить самостоятельно или воспользоваться уже готовой, например для sqlite3.

Также существуют реализации для других СУБД:

  • PostgreSQL (psycopg2, txpostgres, …)
  • FireBird (fdb)
  • MySQL (mysql-python, PyMySQL, …)
  • MS SQL Server (adodbapi, pymssql, mxODBC, pyodbc, …)
  • Oracle (cx_Oracle, mxODBC, pyodbc, …)
  • и другие http://wiki.python.org/moin/DatabaseInterfaces

Большинство из них могут быть установлены стандартным способом:

$ pip install psycopg2
$ pip install mysql-python

Константы

  • 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» ).

Конструктор соединения

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

  • dsn - Название источника данных в виде строки
  • user - Имя пользователя
  • password - Пароль
  • host - Адрес хоста, на котором работает СУБД
  • database - Имя базы данных.

Connection

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

  • .close() - Закрывает соединение с базой данных.
  • .commit() - Завершает транзакцию.
  • .rollback() - Откатывает начатую транзакцию (восстанавливает исходное состояние). Закрытие соединения при незавершенной транзакции автоматически производит откат транзакции.
  • .cursor() - Возвращает объект-курсор, использующий данное соединение. Если база данных не поддерживает курсоры, модуль сопряжения должен их имитировать.

Cursor

См.также

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

Наcтройки

  • arraysize - Атрибут, равный количеству записей, возвращаемых методом fetchmany(). По умолчанию равен 1.
  • setinputsizes(sizes) - Предопределяет области памяти для параметров, используемых в операциях. Аргумент sizes задает последовательность, где каждый элемент соответствует одному входному параметру. Элемент может быть объектом-типом соответствующего параметра или целым числом, задающим длину строки. Он также может иметь значение None, если о размере входного параметра ничего нельзя сказать заранее или он предполагается очень большим. Метод должен быть вызван до execute-методов.
  • setoutputsize(size[, column]) - Устанавливает размер буфера для выходного параметра из столбца с номером column. Если column не задан, метод устанавливает размер для всех больших выходных параметров. Может использоваться, например, для получения больших бинарных объектов ( B inary L arge O bject, BLOB ).

Операции

  • execute(operation[, parameters]) - Исполняет запрос к базе данных или команду СУБД. Параметры (parameters) могут быть представлены в принятой в базе данных нотации в соответствии с атрибутом paramstyle, описанным выше.
  • executemany(operation, seq_of_parameters) - Выполняет серию запросов или команд, подставляя параметры в заданный шаблон. Параметр seq_of_parameters задает последовательность наборов параметров.
  • callproc(procname[, params]) - Вызывает хранимую процедуру procname с параметрами из изменчивой последовательности params. Хранимая процедура может изменить значения некоторых параметров последовательности. Метод может возвратить результат, доступ к которому осуществляется через fetch - методы.

Атрибуты

  • rowcount - Количество записей, полученных или затронутых в результате выполнения последнего запроса. В случае отсутствия execute-запросов или невозможности указать количество записей равен -1.

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

    • name
    • type_code
    • display_size (optional)
    • internal_size (optional)
    • precision (optional)
    • scale (optional)
    • null_ok (optional)

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

Результат

  • fetchone() - Возвращает следующую запись (в виде последовательности) из результата запроса или None при отсутствии данных.
  • fetchall() - Возвращает все (или все оставшиеся) записи результата запроса.
  • fetchmany([size]) - Возвращает следующие несколько записей из результатов запроса в виде последовательности последовательностей. Пустая последовательность означает отсутствие данных. Необязательный параметр size указывает количество возвращаемых записей (реально возвращаемых записей может быть меньше). По умолчанию size равен атрибуту arraysize объекта-курсора.

Типы дынных

DB-API 2.0 предусматривает названия для объектов-типов, используемых для описания полей базы данных:

Объект Тип
STRING Строка и символ
BINARY Бинарный объект
NUMBER Число
DATETIME Дата и время
ROWID Идентификатор записи
None NULL-значение (отсутствующее значение)

С каждым типом данных (в реальности это - классы) связан конструктор. Совместимый с DB-API модуль должен определять следующие конструкторы:

  • Date (год, месяц, день) Дата.
  • Time (час, минута, секунда) Время.
  • Timestamp (год, месяц, день, час, минута, секунда) Дата-время.
  • DateFromTicks (secs) Дата в виде числа секунд secs от начала эпохи (1 января 1970 года).
  • TimeFromTicks (secs) Время, то же.
  • TimestampFromTicks (secs) Дата-время, то же.
  • Binary (string) Большой бинарный объект на основании строки string.

Исключения

DB API спецификация требует реализацию классов исключений следующей структуры:

StandardError
├──Warning
└──Error
   ├──InterfaceError (a problem with the db api)
   └──DatabaseError (a problem with the database)
      ├──DataError (bad data, values out of range, etc.)
      ├──OperationalError (the db has an issue out of our control)
      ├──IntegrityError
      ├──InternalError
      ├──ProgrammingError (something wrong with the operation)
      └──NotSupportedError (the operation is not supported)
Previous: Базы данных Next: SQLite