Tekst źródłowy strony /PythonDBAPI

= [[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: [http://www.python.org/dev/peps/pep-0249/].

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"''.