Hướng dẫn python db-api 2.0 tutorial - hướng dẫn python db-api 2.0

Giới thiệu về giao diện tiêu chuẩn cho các tương tác cơ sở dữ liệu Pythonic.

Lịch sử¶

Mặc dù các tiêu chuẩn của SQL, cơ sở dữ liệu riêng lẻ có rất nhiều sự khác biệt.

Các lập trình viên không muốn phải suy nghĩ về chi tiết triển khai cho các hệ thống cơ bản.

Thật tuyệt khi có một API duy nhất để ẩn những chi tiết này.

Bất kỳ gói nào thực hiện API này sau đó sẽ có thể hoán đổi cho nhau.

Hoàn thành vào năm 1996, PEP 248 được chỉ định DB-API phiên bản 1.0 để thực hiện mục tiêu này:

API này đã được xác định để khuyến khích sự tương đồng giữa các mô -đun Python được sử dụng để truy cập cơ sở dữ liệu. Bằng cách này, chúng tôi hy vọng sẽ đạt được tính nhất quán dẫn đến các mô -đun dễ hiểu hơn, mã thường có khả năng di động hơn trên cơ sở dữ liệu và khả năng kết nối cơ sở dữ liệu rộng hơn từ Python.

Nguồn: http://www.python.org/dev/peps/pep-0248/

Đến năm 2001, PEP 249 đã mang đến phiên bản 2.0 của đặc tả DB-API, với các cải tiến:

• Các loại cột mới đã được thêm vào để hỗ trợ tất cả các loại dữ liệu cơ bản trong SQL hiện đại
• Hằng số API mới đã được thêm vào để giúp phát hiện sự khác biệt giữa các triển khai
• Các ngữ nghĩa để gọi các thủ tục được lưu trữ đã được làm rõ.
• Các trường hợp ngoại lệ dựa trên lớp học đã được thêm vào để cải thiện khả năng xử lý lỗi

Các cuộc thảo luận hiện đang được tiến hành để đẩy DB-API v3.0, đặc biệt là trong những thay đổi trong Python 3.0

Nguồn: http://www.python.org/dev/peps/pep-0249/

Đặc điểm kỹ thuật, không thực hiện công

Điều quan trọng cần nhớ là PEP 249 chỉ là một đặc điểm kỹ thuật.only a specification.

Không có mã hoặc gói cho DB-API 2.0 trên chính nó.

Kể từ 2.5, thư viện tiêu chuẩn Python đã cung cấp triển khai tham chiếu của API dựa trên SQLite3 RDBMS.

Trước phiên bản 2.5, gói này đã có sẵn dưới dạng pysqlite (và nó vẫn còn).pysqlite (and it still is).

Cài đặt triển khai Jo

Để sử dụng API DB với bất kỳ cơ sở dữ liệu nào khác ngoài SQLite3, bạn phải có sẵn gói API cơ bản.

Việc triển khai có sẵn cho:

• PostgreSQL (psycopg2, txpostgres, ...)psycopg2, txpostgres, ...)
• Mysql (mysql-python, pymysql, ...)mysql-python, PyMySQL, ...)
• MS SQL Server (Adodbapi, PyMSSQL, MXODBC, PYODBC, ...)adodbapi, pymssql, mxODBC, pyodbc, ...)
• Oracle (cx_oracle, mxodbc, pyodbc, ...)cx_Oracle, mxODBC, pyodbc, ...)
• và nhiều cái khác...

Nguồn: http://wiki.python.org/moin/databaseinterfaces

Hầu hết các gói API DB có thể được cài đặt bằng các phương thức Pythonic điển hình:

$ pip install psycopg2
$ pip install mysql-python
...

Yêu cầu một số lắp ráp¶

Hầu hết các gói API sẽ yêu cầu các tiêu đề phát triển cho hệ thống cơ sở dữ liệu cơ bản có sẵn. Không có những thứ này, các ký hiệu C cần thiết để liên lạc với DB không có mặt và trình bao bọc không thể hoạt động.

Hơn thế nữa

Một số giấy gói API DB có yêu cầu cài đặt đặc biệt.

Gói MS SQL chỉ chạy trên Windows và yêu cầu PYWIN32. Nó được bao gồm trong các phiên bản của PYWIN32 kể từ V211.pywin32. It is included in versions of pywin32 since v211.

Gói CX_Oracle có trình cài đặt nhị phân hoặc có thể được cài đặt từ nguồn bằng cách sử dụng distutils:cx_Oracle package has binary installers, or can be installed from source using distutils:

$ python setup.py build
$ python setup.py install

Api¶

API DB là gì?

Globals¶

Việc triển khai DB-API2 cung cấp các giá trị toàn cầu sau:

Hằng số ApilevelString chỉ ra phiên bản API (Hồi 1.0, hoặc 2.0 2.0)String constant indicating the api version (“1.0” or “2.0”)threadsafetyInteger constant between 0 and 3 indicating the scope in which threads may safely be usedparamstyle String contstant indicating the style of marker used for parameter substitution in SQL expressions

Chúng có thể được sử dụng để điều chỉnh kỳ vọng của chương trình của bạn.

Một nhà xây dựng

DB API cung cấp kết nối Constructor, trả về đối tượng kết nối:connect, which returns a Connection object:

Điều này có thể được coi là điểm vào cho mô -đun. Khi bạn đã có một kết nối, mọi thứ khác chảy từ đó.

Các tham số được yêu cầu và chấp nhận bởi hàm tạo kết nối sẽ thay đổi từ việc triển khai đến triển khai, vì chúng rất cụ thể đối với cơ sở dữ liệu cơ bản.connect constructor will vary from implementation to implementation, since they are highly specific to the underlying database.

Một kết nối¶

Một số phương thức của kết nối có thể không được hỗ trợ bởi tất cả các triển khai:connection may not be supported by all implementations:

.Close () Đóng kết nối với cơ sở dữ liệu vĩnh viễn. Cố gắng sử dụng kết nối sau khi gọi, điều này sẽ làm tăng lỗi DB-API..Commit () cam kết rõ ràng bất kỳ giao dịch đang chờ xử lý nào vào dữ liệu. Phương thức phải là không có nếu DB cơ bản không hỗ trợ các giao dịch..rollback () Phương thức tùy chọn này khiến giao dịch được chuyển trở lại điểm bắt đầu. Nó có thể không được triển khai ở mọi nơi..cursor () trả về một đối tượng con trỏ sử dụng kết nối này.Closes the connection to the database permanently. Attempts to use the connection after calling this will raise a DB-API Error..commit() explicitly commit any pending transactions to the databse. The method should be a no-op if the underlying db does not support transactions..rollback()This optional method causes a transaction to be rolled back to the starting point. It may not be implemented everywhere..cursor()returns a Cursor object which uses this Connection.

Một con trỏ - Cài đặt

Bạn có thể sử dụng một vài giá trị để kiểm soát các hàng được trả về bởi con trỏ:

Số nguyên .arraysizean điều khiển số lượng hàng được trả về tại một thời điểm bởi .fetchmany (và tùy chọn bao nhiêu để gửi cùng một lúc với .ExecuteMany) mặc định là 1.setInputSizes (kích thước) được sử dụng để đặt các vùng bộ nhớ cho các tham số được truyền đến một hoạt động .SetOutputSize (kích thước [, cột]) được sử dụng để điều khiển kích thước bộ đệm cho các cột lớn được trả về bởi một hoạt động (ví dụ, các loại blob hoặc dài).An integer which controls how many rows are returned at a time by .fetchmany (and optionally how many to send at a time with .executemany) Defaults to 1.setinputsizes(sizes)Used to set aside memory regions for paramters passed to an operation.setoutputsize(size[, column])Used to control buffer size for large columns returned by an operation (BLOB or LONG types, for example).

Hai phương pháp cuối cùng có thể được thực hiện dưới dạng không

Một con trỏ - Hoạt động Ăn

Con trỏ nên được sử dụng để chạy các hoạt động trên cơ sở dữ liệu:

.Execute (Hoạt động [, tham số]) chuẩn bị và sau đó chạy hoạt động cơ sở dữ liệu. Kiểu tham số (SEQ hoặc ánh xạ) và các điểm đánh dấu được triển khai cụ thể (xem tham số) .ExecuteMany (Hoạt động [, SEQ_OF_PARAMS]) chuẩn bị và chạy các hoạt động một lần cho mỗi bộ tham số được cung cấp (điều này thay thế hành vi V1 cũ của việc truyền một SEQ cho SEQ cho một SEQ cho một SEQ cho một SEQ cho một .Execute) .. CallProc (ProcName [, tham số]) gọi quy trình DB được lưu trữ với các tham số được cung cấp. Trả về một phiên bản sửa đổi của các tham số được cung cấp với các tham số đầu ra và đầu vào/đầu ra được thay thếPrepares and then runs a database operation. Parameter style (seq or mapping) and markers are implementation specific (see paramstyle).executemany(operation[, seq_of_params])Prepares and the runs an operations once for each set of parameters provided (this replaces the old v1 behavior of passing a seq to .execute)..callproc(procname[, parameters])Calls a stored DB procedure with the provided parameters. Returns a modified version of the provided parameters with output and input/output parameters replaced

Một con trỏ - thuộc tính

Các thuộc tính của con trỏ có thể giúp bạn tìm hiểu về kết quả hoạt động:Cursor can help you learn about the results of operations:

.RowCounttell có bao nhiêu hàng đã được trả lại hoặc bị ảnh hưởng bởi hoạt động cuối cùng. Số sẽ là -1 nếu không có hoạt động nào được thực hiện..DescriptionRUNNS Một chuỗi gồm 7 phần trình tự mô tả từng cột trong hàng kết quả được trả về (không có hoạt động nào được thực hiện):Tells how many rows have been returned or affected by the last operation. The number will be -1 if no operation has been performed..descriptionReturns a sequence of 7-item sequences describing each of the columns in the result row(s) returned (None if no operation has been performed):

• Tên
• type_code
• display_size (tùy chọn)
• internal_size (tùy chọn)
• Độ chính xác (tùy chọn)
• Tỷ lệ (tùy chọn)
• null_ok (tùy chọn)

Một con trỏ - Kết quả Jo

Giá trị trả về .Execute hoặc .Executemany không được xác định và không nên được sử dụng. Các phương pháp này là cách để có được kết quả sau khi hoạt động:.execute or .executemany is undefined and should not be used. These methods are the way to get results after an operation:

.fetchone () trả về hàng tiếp theo từ một tập kết quả và không có gì khi không còn nữa..fetchMany ([size = con trỏ.arraysize]) trả về một chuỗi các hàng kích thước (hoặc ít hơn) từ một tập kết quả. Một chuỗi trống được trả về khi không có hàng. Mặc định cho Arraysize..fetchall () trả về tất cả (còn lại) hàng từ một tập kết quả. Hành vi này có thể bị ảnh hưởng bởi mảng.Returns the next row from a result set, and None when none remain..fetchmany([size=cursor.arraysize])Returns a sequence of size rows (or fewer) from a result set. An empty sequence is returned when no rows remain. Defaults to arraysize..fetchall()Returns all (remaining) rows from a result set. This behavior may be affected by arraysize.

Lưu ý rằng mỗi phương pháp này sẽ tăng lỗi API DB nếu không có hoạt động nào được thực hiện (hoặc nếu không có tập kết quả nào được tạo ra)Error if no operation has been performed (or if no result set was produced)

Kiểu dữ liệu & Nhà xây dựng

DB-API cung cấp các loại và hàm tạo cho dữ liệu:

• Ngày (năm, tháng, ngày) - Xây dựng một đối tượng giữ giá trị ngày - constructs an object holding a date value
• Thời gian (giờ, phút, giây) - Xây dựng một đối tượng giữ giá trị thời gian - constructs an object holding a time value
• Dấu thời gian (Y, M, D, H, Min, S) - Xây dựng một đối tượng giữ dấu thời gian - constructs an object holding a timestamp

Mỗi cái ở trên có một từ tương ứng (ticks) trả về cùng loại được đưa ra cho một đối số số nguyên duy nhất (giây kể từ kỷ nguyên)FromTicks(ticks) which returns the same type given a single integer argument (seconds since the epoch)

• Nhị phân (chuỗi) - xây dựng một đối tượng để giữ dữ liệu chuỗi nhị phân dài - constructs an object to hold long binary string data
• Chuỗi - một loại để mô tả các cột giữ các giá trị chuỗi (char) - a type to describe columns that hold string values (CHAR)
• Nhị phân - một loại để mô tả các cột nhị phân dài (Blob, RAW) - a type to describe long binary columns (BLOB, RAW)
• Số - một loại để mô tả các cột số - a type to describe numeric columns
• DateTime - một loại để mô tả các cột ngày/giờ/dateTime - a type to describe date/time/datetime columns
• ROWID - một loại để mô tả cột Rowid trong cơ sở dữ liệu - a type to describe the Row ID column in a database

Các giá trị SQL NULL được biểu thị bằng Python không cóNULL values are represented by Python’s None

Ngoại lệ ha

Thông số kỹ thuật API DB yêu cầu các triển khai để tạo phân cấp các lớp ngoại lệ tùy chỉnh sau:

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)

Ngoài một số tiện ích mở rộng tùy chỉnh không được yêu cầu bởi đặc điểm kỹ thuật, đó là nó.