pytho****@googl*****
pytho****@googl*****
2011年 3月 25日 (金) 23:13:25 JST
Revision: c656cc092b93 Author: MATSUI Tetsushi <matsu****@gmail*****> Date: Fri Mar 25 07:12:18 2011 Log: 2.6.6: library/sqlite3 http://code.google.com/p/python-doc-ja/source/detail?r=c656cc092b93 Modified: /library/sqlite3.rst ======================================= --- /library/sqlite3.rst Sat Nov 27 10:59:46 2010 +++ /library/sqlite3.rst Fri Mar 25 07:12:18 2011 @@ -1,5 +1,6 @@ -:mod:`sqlite3` --- SQLite データベースに対する DB-API 2.0 インタフェース -======================================================================== +========================================================================== + :mod:`sqlite3` --- SQLite データベースに対する DB-API 2.0 インタフェース +========================================================================== .. module:: sqlite3 :synopsis: A DB-API 2.0 implementation using SQLite 3.x. @@ -8,21 +9,27 @@ .. versionadded:: 2.5 -SQLite は、別にサーバプロセスは必要とせずデータベースのアクセスに SQL 問い 合わせ言語の非標準的な一種を使える軽量なディスク上のデータベースを -提供する C ライブラリです。ある種のアプリケーションは内部データ保存に SQLite を使えます。また、SQLite を使ってアプリケーションのプロトタイ -プを作りその後そのコードを PostgreSQL や Oracle のような大規模データベース に移植するということも可能です。 - -pysqlite は Gerhard Haring によって書かれ、 :pep:`249` に記述された DB-API 2.0 仕様に準拠したSQL +SQLite は、別にサーバプロセスは必要とせずデータベースのアクセスに SQL +問い合わせ言語の非標準的な一種を使える軽量なディスク上のデータベースを +提供する C ライブラリです。ある種のアプリケーションは内部データ保存に +SQLite を使えます。また、SQLite を使ってアプリケーションのプロトタイプを +作りその後そのコードを PostgreSQL や Oracle のような大規模データベースに +移植するということも可能です。 + +sqlite3 は Gerhard Häring によって書かれ、 +:pep:`249` に記述された DB-API 2.0 仕様に準拠した SQL インタフェースを提供するものです。 -このモジュールを使うには、最初にデータベースを表す :class:`Connection` オブ ジェクトを作ります。ここではデータはファイル +このモジュールを使うには、最初にデータベースを表す :class:`Connection` +オブジェクトを作ります。ここではデータはファイル :file:`/tmp/example` に格納されているものとします。 :: conn = sqlite3.connect('/tmp/example') 特別な名前である ``:memory:`` を使うと RAM 上にデータベースを作ることもでき ます。 -:class:`Connection` があれば、 :class:`Cursor` オブジェクトを作りそ の :meth:`~Cursor.execute` メソッドを呼んで +:class:`Connection` があれば、 :class:`Cursor` オブジェクトを作りその +:meth:`~Cursor.execute` メソッドを呼んで SQL コマンドを実行することができます。 :: c = conn.cursor() @@ -86,11 +93,13 @@ .. seealso:: - http://www.pysqlite.org - pysqlite のウェブページ + http://code.google.com/p/pysqlite/ + pysqlite のウェブページ -- sqlite3 は「pysqlite」という名の下、 + 外部で開発されています。 http://www.sqlite.org - SQLite のウェブページ。ここの文書ではサポートされる SQL 方言の文法と 使えるデータ型を説明しています + SQLite のウェブページ。ここの文書ではサポートされる SQL + 方言の文法と使えるデータ型を説明しています :pep:`249` - Database API Specification 2.0 Marc-Andre Lemburg により書かれた PEP @@ -102,7 +111,7 @@ .. _sqlite3-module-contents: モジュールの関数と定数 ----------------------- +====================== .. data:: PARSE_DECLTYPES @@ -204,7 +213,7 @@ .. _sqlite3-connection-objects: Connection オブジェクト ------------------------ +======================= .. class:: Connection @@ -215,13 +224,15 @@ .. attribute:: Connection.isolation_level - 現在の分離レベルを取得または設定します。:const:`None` で自動コミットモー ドまたは "DEFERRED", "IMMEDIATE", "EXLUSIVE" + 現在の分離レベルを取得または設定します。 + :const:`None` で自動コミットモードまた は "DEFERRED", "IMMEDIATE", "EXLUSIVE" のどれかです。 より詳しい説明は :ref:`sqlite3-controlling-transactions` 節を参照してく ださい。 .. method:: Connection.cursor([cursorClass]) - cursor メソッドはオプション引数 *CursorClass* を受け付けます。これを指定 するならば、指定されたクラスは + cursor メソッドはオプション引数 *cursorClass* を受け付けます。 + これを指定するならば、指定されたクラスは :class:`sqlite3.Cursor` を継承したカーソルクラスでなければなりません。 .. method:: Connection.commit() @@ -256,29 +267,35 @@ .. method:: Connection.execute(sql, [parameters]) - このメソッドは非標準のショートカットで、cursor メソッドを呼び出して中間 的なカーソルオブジェクトを作り、そのカーソルの :meth:`execute` + このメソッドは非標準のショートカットで、cursor メソッドを呼び出して + 中間的なカーソルオブジェクトを作り、そのカーソル の :meth:`execute<Cursor.execute>` メソッドを与えられたパラメータと共に呼び出します。 .. method:: Connection.executemany(sql, [parameters]) - このメソッドは非標準のショートカットで、cursor メソッドを呼び出して中間 的なカーソルオブジェクトを作り、そのカーソルの - :meth:`executemany` メソッドを与えられたパラメータと共に呼び出します。 + このメソッドは非標準のショートカットで、cursor メソッドを呼び出して + 中間的なカーソルオブジェクトを作り、そのカーソルの + :meth:`executemany<Cursor.executemany>` メソッドを + 与えられたパラメータと共に呼び出します。 .. method:: Connection.executescript(sql_script) - このメソッドは非標準のショートカットで、cursor メソッドを呼び出して中間 的なカーソルオブジェクトを作り、そのカーソルの - :meth:`executescript` メソッドを与えられたパラメータと共に呼び出します。 + このメソッドは非標準のショートカットで、cursor メソッドを呼び出して + 中間的なカーソルオブジェクトを作り、そのカーソルの + :meth:`executescript<Cursor.executescript>` メソッドを + 与えられたパラメータと共に呼び出します。 .. method:: Connection.create_function(name, num_params, func) - 後から SQL 文中で *name* という名前の関数として使えるユーザ定義関数を作 成します。 *num_params* は関数が受け付ける引数の数、 + 後から SQL 文中で *name* という名前の関数として使えるユーザ定義関数を作 成します。 + *num_params* は関数が受け付ける引数の数、 *func* は SQL 関数として使われる Python の呼び出し可能オブジェクトです。 - 関数は SQLite でサポートされている任意の型を返すことができます。具体的に は unicode, str, int, long, float, buffer - および None です。 + 関数は SQLite でサポートされている任意の型を返すことができます。 + 具体的には unicode, str, int, long, float, buffer および None です。 例: @@ -289,11 +306,12 @@ ユーザ定義の集計関数を作成します。 - 集計クラスにはパラメータ *num_params* で指定される個数の引数を取る ``step`` メソッドおよび最終的な集計結果を返す + 集計クラスにはパラメータ *num_params* で指定される個数の引数を取る + ``step`` メソッドおよび最終的な集計結果を返す ``finalize`` メソッドを実装しなければなりません。 - ``finalize`` メソッドは SQLite でサポートされている任意の型を返すことが できます。具体的には unicode, str, int, - long, float, buffer および None です。 + ``finalize`` メソッドは SQLite でサポートされている任意の型を返すことが できます。 + 具体的には unicode, str, int, long, float, buffer および None です。 例: @@ -302,25 +320,31 @@ .. method:: Connection.create_collation(name, callable) - *name* と *callable* で指定される照合順序を作成します。呼び出し可能オブ ジェクトには二つの文字列が渡されます。一つめのものが二つめ - のものより低く順序付けられるならば -1 を返し、等しければ 0 を返し、一つ めのものが二つめのものより高く順序付けられるならば 1 を返すようにし - なければなりません。この関数はソート(SQL での ORDER BY)をコントロールす るもので、比較を行なうことは他の SQL 操作には影響を与えないことに注 - 意しましょう。 - - また、呼び出し可能オブジェクトに渡される引数は Python のバイト文字列とし て渡されますが、それは通常 UTF-8 で符号化されたものになります。 + *name* と *callable* で指定される照合順序を作成します。 + 呼び出し可能オブジェクトには二つの文字列が渡されます。 + 一つめのものが二つめのものより低く順序付けられるならば -1 を返し、 + 等しければ 0 を返し、一つめのものが二つめのものより高く順序付けられるな らば + 1 を返すようにしなければなりません。 + この関数はソート(SQL での ORDER BY)をコントロールするもので、 + 比較を行なうことは他の SQL 操作には影響を与えないことに注意しましょう。 + + また、呼び出し可能オブジェクトに渡される引数は Python のバイト文字列とし て + 渡されますが、それは通常 UTF-8 で符号化されたものになります。 以下の例は「間違った方法で」ソートする自作の照合順序です: .. literalinclude:: ../includes/sqlite3/collation_reverse.py - 照合順序を取り除くには ``create_collation`` を callable として None を渡 して呼び出します:: + 照合順序を取り除くには ``create_collation`` を callable として + None を渡して呼び出します:: con.create_collation("reverse", None) .. method:: Connection.interrupt() - このメソッドを別スレッドから呼び出して接続上で現在実行中であろうクエリを 中断させられます。クエリが中断されると呼び出し元は例外を受け取ります。 + このメソッドを別スレッドから呼び出して接続上で現在実行中であろうクエリを + 中断させられます。クエリが中断されると呼び出し元は例外を受け取ります。 .. method:: Connection.set_authorizer(authorizer_callback) @@ -348,43 +372,52 @@ a GUI. このメソッドはコールバックを登録します。 - コールバックはSQLite仮想マシン上の *n* 個の命令を実行するごとに呼び出さ れます。 - これは、GUI更新などのために、長時間かかる処理中にSQLiteからの呼び出しが 欲しい場合に便利です。 + コールバックは SQLite 仮想マシン上の *n* 個の命令を実行するごとに呼び出 されます。 + これは、GUI 更新などのために、長時間かかる処理中に SQLite + からの呼び出しが欲しい場合に便利です。 .. If you want to clear any previously installed progress handler, call the method with :const:`None` for *handler*. - 以前登録した progress handler をクリアしたい場合は、このメソッドを、 *handler* 引数に - :const:`None` を渡して呼び出してください。 + 以前登録した progress handler をクリアしたい場合は、このメソッドを、 + *handler* 引数に :const:`None` を渡して呼び出してください。 .. attribute:: Connection.row_factory - この属性を、カーソルとタプルの形での元の行のデータを受け取り最終的な行を 表すオブジェクトを返す呼び出し可能オブジェクトに、変更することが - できます。これによって、より進んだ結果の返し方を実装することができます。 例えば、カラムの名前で各データにアクセスできるようなオブジェクトを返したりで きます。 + この属性を、カーソルとタプルの形での元の行のデータを受け取り最終的な行を 表す + オブジェクトを返す呼び出し可能オブジェクトに、変更することができます。 + これによって、より進んだ結果の返し方を実装することができます。 + 例えば、カラムの名前で各データにアクセスできるようなオブジェクトを返した りできます。 例: .. literalinclude:: ../includes/sqlite3/row_factory.py - タプルを返すのでは物足りず、名前に基づいたカラムへのアクセスが行ないたい 場合は、高度に最適化された :class:`sqlite3.Row` 型を + タプルを返すのでは物足りず、名前に基づいたカラムへのアクセスが行ないたい 場合は、 + 高度に最適化された :class:`sqlite3.Row` 型を :attr:`row_factory` にセットすることを考えてはいかがでしょう か。 :class:`Row` - クラスでは添字でも大文字小文字を無視した名前でもカラムにアクセスでき、し かもほとんどメモリーを浪費しません。 - おそらく、辞書を使うような独自実装のアプローチよりも、もしかすると db の 行に基づいた解法よりも良いものかもしれません。 + クラスでは添字でも大文字小文字を無視した名前でもカラムにアクセスでき、 + しかもほとんどメモリーを浪費しません。 + おそらく、辞書を使うような独自実装のアプローチよりも、 + もしかすると db の行に基づいた解法よりも良いものかもしれません。 .. XXX what's a db_row-based solution? .. attribute:: Connection.text_factory - この属性を使って ``TEXT`` データ型をどのオブジェクトで返すかを制御できま す。デフォルトではこの属性は :class:`unicode` に設定されており、 - :mod:`sqlite3` モジュールは TEXT を Unicode オブジェクトで返します。もし バイト列で返したいならば、 :class:`str` - に設定してください。 - - 効率の問題を考えて、非ASCIIデータに限って Unicode オブジェクトを返し、そ の他の場合にはバイト列を返す方法もあります。これを有効にしたければ、 + この属性を使って ``TEXT`` データ型をどのオブジェクトで返すかを制御できま す。 + デフォルトではこの属性は :class:`unicode` に設定されており、 + :mod:`sqlite3` モジュールは ``TEXT`` を Unicode オブジェクトで返します。 + もしバイト列で返したいならば、 :class:`str` に設定してください。 + + 効率の問題を考えて、非ASCIIデータに限って Unicode オブジェクトを返し、 + その他の場合にはバイト列を返す方法もあります。これを有効にしたければ、 この属性を :const:`sqlite3.OptimizedUnicode` に設定してください。 - バイト列を受け取って望みの型のオブジェクトを返すような呼び出し可能オブジ ェクトを何でも設定して構いません。 + バイト列を受け取って望みの型のオブジェクトを返すような + 呼び出し可能オブジェクトを何でも設定して構いません。 以下の説明用のコード例を参照してください: @@ -424,7 +457,7 @@ .. _sqlite3-cursor-objects: カーソルオブジェクト --------------------- +==================== .. class: Cursor @@ -567,7 +600,7 @@ .. _sqlite3-row-objects: Row オブジェクト ------------------ +================ .. class:: Row @@ -582,7 +615,7 @@ .. It supports mapping access by column name and index, iteration, representation, equality testing and :func:`len`. - カラム名とインデックスによる要素へのアクセス、イテレーション、 + カラム名とインデックスによる要素へのアクセス, イテレーション, repr(), 同値テスト, :func:`len` をサポートしています。 .. If two :class:`Row` objects have exactly the same columns and their @@ -653,11 +686,11 @@ .. _sqlite3-types: SQLite と Python の型 ---------------------- +===================== 入門編 -^^^^^^ +------ SQLite が最初からサポートしているのは次の型です。 @@ -707,7 +740,7 @@ 追加された Python の型を SQLite データベースに格納するために適合関数を使う -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------------------------------------------------------- 既に述べたように、SQLite が最初からサポートする型は限られたものだけです。そ れ以外の Python の型を SQLite で使うには、その型を :mod:`sqlite3` モジュールがサポートしている型の一つに **適合** させなくては なりません。サポートしている型というのは、NoneType, @@ -720,7 +753,7 @@ オブジェクト自身で適合するようにする -"""""""""""""""""""""""""""""""""""" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 自分でクラスを書いているならばこの方法が良いでしょう。次のようなクラスがあ るとします:: @@ -737,7 +770,7 @@ 適合関数を登録する -"""""""""""""""""" +~~~~~~~~~~~~~~~~~~ もう一つの可能性は型を文字列表現に変換する関数を作 り :meth:`register_adapter` でその関数を登録することです。 @@ -756,7 +789,7 @@ SQLite の値を好きな Python 型に変換する -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------------------- 適合関数を書くことで好きな Python 型を SQLite に送り込めるようになりまし た。しかし、本当に使い物になるようにするには Python から SQLite さらに Python へという往還(roundtrip)の変換ができる必要があります。 @@ -792,7 +825,7 @@ デフォルトの適合関数と変換関数 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------ datetime モジュールの date 型および datetime 型のためのデフォルト適合関数が あります。これらの型は ISO 日付 / ISO タイムスタンプとして SQLite に送られます。 @@ -811,49 +844,60 @@ .. _sqlite3-controlling-transactions: トランザクション制御 --------------------- +==================== デフォルトでは、 :mod:`sqlite3` モジュールはデータ変更言語(DML)文(すなわち -``INSERT``/``UPDATE``/``DELETE``/``REPLACE``)の前に暗黙のうちにトランザクシ ョンを開始し、非DML、非クエリ文(すなわち +``INSERT``/``UPDATE``/``DELETE``/``REPLACE``)の前に暗黙のうちに +トランザクションを開始し、非DML、非クエリ文(すなわち ``SELECT`` や上記のいずれでもないもの。)の前にトランザクションをコミットし ます。 ですから、もしトランザクション中に ``CREATE TABLE ...``, ``VACUUM``, ``PRAGMA`` -といったコマンドを発行すると、 :mod:`sqlite3` モジュールはそのコマンドの実 行前に暗黙のうちにコミットします。このようにする理由は二つあります。 -第一にこうしたコマンドのうちの幾つかはトランザクション中ではうまく動きませ ん。第二に pysqlite -はトランザクションの状態(トランザクションが掛かっているかどうか)を追跡する 必要があるからです。 - -pysqlite が暗黙のうちに実行する ``BEGIN`` 文の種類(またはそういうものを使わ ないこと)を :func:`connect` 呼び出しの +といったコマンドを発行すると、 +:mod:`sqlite3` モジュールはそのコマンドの実行前に暗黙のうちにコミットしま す。 +このようにする理由は二つあります。 +第一にこうしたコマンドのうちの幾つかはトランザクション中ではうまく動きませ ん。 +第二に sqlite3 はトランザクションの状態(トランザクションが掛かっているかど うか) +を追跡する必要があるからです。 + +sqlite3 が暗黙のうちに実行する ``BEGIN`` 文の種類(またはそういうものを使わ ないこと)を +:func:`connect` 呼び出しの *isolation_level* パラメータを通じて、または接続の :attr:`isolation_level` プロパティを通じて、制御することができます。 -もし **自動コミットモード** が使いたければ、 :attr:`isolation_level` は None にしてください。 - -そうでなければデフォルトのまま ``BEGIN`` 文を使い続けるか、SQLite がサポー トする分離レベル "DEFERRED", "IMMEDIATE" または +もし **自動コミットモード** が使いたければ、 +:attr:`isolation_level` は None にしてください。 + +そうでなければデフォルトのまま ``BEGIN`` 文を使い続けるか、 +SQLite がサポートする分離レベル "DEFERRED", "IMMEDIATE" または "EXCLUSIVE" を設定してください。 -pysqlite の効率的な使い方 -------------------------- +:mod:`sqlite3` の効率的な使い方 +=============================== ショートカットメソッドを使う -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:class:`Connection` オブジェクトの非標準的なメソッ ド :meth:`execute`, :meth:`executemany`, -:meth:`executescript` を使うことで、 (しばしば余計な) :class:`Cursor` オブ ジェクトをわざわざ作り出さずに済むので、 +---------------------------- + +:class:`Connection` オブジェクトの非標準的なメソッド :meth:`execute`, +:meth:`executemany`, :meth:`executescript` を使うことで、 +(しばしば余計な) :class:`Cursor` オブジェクトをわざわざ作り出さずに済むの で、 コードをより簡潔に書くことができます。 :class:`Cursor` オブジェクトは暗黙裡 に -生成されショートカットメソッドの戻り値として受け取ることができます。この方 法を使えば、 ``SELECT`` 文を実行してその結果について反復することが、 +生成されショートカットメソッドの戻り値として受け取ることができます。この方 法を使えば、 +``SELECT`` 文を実行してその結果について反復することが、 :class:`Connection` オブジェクトに対する呼び出し一つで行なえます。 .. literalinclude:: ../includes/sqlite3/shortcut_methods.py 位置ではなく名前でカラムにアクセスする -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:mod:`sqlite3` モジュールの有用な機能の一つに、行生成関数として使われるため の :class:`sqlite3.Row` クラスがあります。 - -このクラスでラップされた行は、位置インデクス(タプルのような)でも大文字小文 字を区別しない名前でもアクセスできます: +-------------------------------------- + +:mod:`sqlite3` モジュールの有用な機能の一つに、行生成関数として使われるため の +:class:`sqlite3.Row` クラスがあります。 + +このクラスでラップされた行は、位置インデクス(タプルのような)でも大文字小文 字を +区別しない名前でもアクセスできます: .. literalinclude:: ../includes/sqlite3/rowclass.py @@ -861,7 +905,7 @@ .. Using the connection as a context manager コネクションをコンテキストマネージャーとして利用する -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------------------------------------------- .. versionadded:: 2.6
