TI:WTBD/PythonDBAPI

Spis treści
1 TI:WTBD/PythonDBAPI
1.1 Connection
1.2 Cursor
1.3 Atrybuty modułu
1.4 Sposoby wiązania parametrów
TI:WTBD/PythonDBAPI
Podjęto próbę pewnej standaryzacji interfejsu programistycznego (API) pozwalającego na
korzystanie z relacyjnych (SQL-owych) baz danych z poziomu programów w Pythonie. Oczywistym
celem jest ułatwienie tworzenia programów, które minimalnym wysiłkiem programisty dałoby się
zaadaptować do współpracy z różnymi systemami bazodanowymi. Nie ma co się łudzić, że da się to
osiągnąć w ogóle bez trudu -- standaryzacja API jest tylko jednym z warunków. Trzeba brać pod
uwagę choćby różnice w dialektach SQL.
Zadania, jakie spełnia DB API to:
nawiązanie komunikacji z bazą
w przypadku SQLite to po prostu podanie nazwy pliku do otwarcia, i ewent. opcjonalnych
parametrów ,,połączenia"
dla systemów klient-serwer jest to nawiązanie połączenia sieciowego i dokonanie
autoryzacji (w sposób specyficzny dla danego systemu)
umożliwienie przekazywania poleceń SQL do silnika bazy
odbiór wyników zapytań ewent. informacji o wykonaniu poleceń DDL i DML
różne inne zadania np. sterowanie transakcjami, pobieranie metadanych
takie zadania ,,różne" bywają różnie zrealizowane w różnych systemach
Specyfikacja DB API jest przedmiotem dokumentu PEP (Python Enhancement Proposal) nr 249: [1].
Główne klasy definiowane w DB API to:
połączenie (Connection)
kursor (Cursor)
DB API definiuje również hierarchię typów wyjątków, które służą przekazywaniu informacji o zajściu
błędów oraz ostrzeżeń. Najczęstszy to ProgrammingError, powstający w wyniku np. błędnej składni
polecenia SQL, przekazania niewłaściwej liczby parametrów polecenia, itp. Jest to podklasa
DatabaseError, która z kolei dziedziczy od Error. Ostrzeżenia tworzą osobną klasę Warning i
powstają np. w sytuacji niepełnego zapisu danych wynikającego z właściwości danego systemu BD.
Connection
Obiekt klasy Connection otrzymuje się jako wynik wywołania funkcji connect(...), której argumenty
(parametry połączenia) zależą od specyfiki danego systemu (ścieżka do pliku dla SQLite; adres
sieciowy, ew. nr portu, dane autoryzacyjne -- dla systemów klient-serwer). Metody połączenia to:
.close()
po zamknięciu połączenia nie da się go dalej wykorzystywać ani wznowić, należy w razie
potrzeby utworzyć nowe, wywołując konstruktor connect(). Nieważne są również wszystkie
kursory związane z zamkniętym połączeniem. Jeżeli w momencie wywołania .close() była
otwarta transakcja, nastąpi jej wycofanie (ROLLBACK).
.commit()
zatwierdzenie aktualnej transakcji. Jeśli baza nie wspiera transakcji, metoda ta nie zgłasza
błędu, tylko nic nie robi.
.rollback()
wycofanie aktualnej transakcji. Jeśli operacja ta jest niewspierana, powinien zostać rzucony
wyjątek. Dla modułów nie wspierających transakcji w ogóle, może to być AttributeError
(metoda nie istnieje).
.cursor()
konstruktor obiektu klasy Cursor.
Cursor
Obiekt klasy Cursor jest przede wszystkim ,,pojemnikiem" na wyniki zapytania lub innego polecenia i
związane z nimi metadane. Atrybuty i metody:
.description
atrybut (tylko do odczytu) opisujący kolumny zbioru wynikowego, w postaci sekwencji, której
elementami są sekwencje 7-elementowe. Najważniejsze z tych 7 elementów to dwa pierwsze:
nazwa i kod typu danych. Jeśli kursor nie ,,zawiera" żadnego zbioru wynikowego, atrybut ten
ma wartość None.
.rowcount
atrybut (tylko do odczytu) którego wartością jest liczba wierszy zbioru wynikowego, lub
wierszy tabeli zmienionych o ile ostatnią operacją było polecenie DML. Jeśli liczba ta nie jest
możliwa do ustalenia, wartością jest -1.
.callproc(nazwa, parametry ...)
wywołanie procedury składowanej (metoda opcjonalna)
.close()
zamknięcie kursora (nie połączenia), zwolnienie zajmowanych zasobów
.execute(polecenie[, parametry])
przesłanie polecenia SQL, ewent. sparametryzowanego. Parametry podaje się w postaci
sekwencji lub słownika (mapowania), w zależności od dostępnego mechanizmu wiązania
parametrów. Jest 'zdecydowanie' rekomendowane wykorzystanie poleceń
sparametryzowanych, a nie -- każdorazowe konstruowanie pełnego tekstu polecenia SQL (wraz
z wartościami parametrów) za pomocą operacji na napisach. Daje to korzyści zarówno na
poziomie optymalizacji, jak i bezpieczeństwa. Ma to zwłaszcza znaczenie przy operacjach
wielokrotnie powtarzanych z różnymi zestawami parametrów (np. masowe wstawianie danych
do tabeli). Należy wówczas wielokrotnie korzystać z tego samego kursora. Wartość zwracana
przez tę metodę jest nieokreślona.
.executemany(polecenie, sekwencja_z_parametrami)
wielokrotnie to samo polecenie SQL z różnymi zestawami parametrów. Jeśli poleceniem jest
zapytanie zwracające zbiór wynikowy, wynik jest nieokreślony -- może nim być rzucenie
wyjątku.
.fetchone()
pobrać kolejny wiersz aktualnego zbioru wynikowego, zwraca None jeśli nie ma już nic do
pobrania (zbiór wynikowy został wyczerpany). Rzuci wyjątkiem Error, jeśli poprzednio
wywołane polecenie nie zwróciło zbioru wynikowego (a w szczególności, gdy aktualnym
kursorem nie wywołano jeszcze żadnego polecenia).
.fetchmany([size=cursor.arraysize])
pobrać max. size kolejnych wierszy aktualnego zbioru wynikowego, jako sekwencję. Poza tym
uwagi jw.
.fetchall()
pobrać wszystkie (pozostałe) wiersze aktualnego zbioru wynikowego, jako sekwencję.
.nextset()
niektóre systemy BD implementują kursory będące uchwytami do wielu zbiorów wynikowych
równocześnie, ta metoda (opcjonalna) powoduje przejście do kolejnego zbioru wynikowego,
zwracając None jeśli zbiory wynikowe zostały wyczerpane.
.arraysize
atrybut modyfikowalny, ustalający domyślną liczbę wierszy pobieranych przez .fetchmany().
.setinputsizes(sizes), .setoutputsize(size[, nr_kolumny])
(często puste) metody związane z ,,tuningowaniem" zarządzania pamięcią przez moduł, rzadko
wykorzystywane.
.next(), .__iter__()
metody pozwalające traktować kursor jako iterator (po wierszach zbioru wynikowego). W
specyfikacji wymienione jako opcjonalne rozszerzenia, ale w zasadzie już standardowe.
Atrybuty modułu
connect(...)
konstruktor połączenia
apilevel
wersja specyfikacji DP API, możliwe wartości: "1.0" (przestarzała), "2.0"
threadsafety
poziom wielowątkowości, wartości z range(4)
paramstyle
sposób wiązania parametrów w polecenia sparametryzowanych
Sposoby wiązania parametrów
"qmark"
każdy "?" w poleceniu jest zastępowany przez kolejny element sekwencji parametrów
"numeric"
każde ":n" gdzie n jest liczbą naturalną zastępowany jest przez element o indeksie n w
sekwencji parametrów
"named"
każde :nazwa zastępowane jest przez element odpowiadający kluczowi nazwa w słowniku
parametrów
"format"
kody jak z printf czy pythonowej operacji formatowania "%" zastępowane są kolejnymi
elementami sekwencji parametrów
"pyformat"
,,rozszerzone" kody formatowania jak w pythonowej operacji "%", tzn postaci "%(nazwa)s"
Moduł sqlite3 ma paramstyle == "qmark", ale takk naprawdę wspiera również styl "named".