# 13.13 `xmllib` -- XML ドキュメントのパーサ

リリース 2.0 以降で撤廃された仕様です。 代わりに `xml.sax` を使ってください。新しい XML パッケージは XML 1.0 をフルにサポートしています。

バージョン1.5.2 以降で変更された 仕様: 名前空間のサポートを追加

このモジュールには XML (Extensible Markup Language) 形式で記述されたテ キストファイルのパースに必要な基本機能を提供する `XMLParser` ク ラスが定義されています。

class `XMLParser`( | )

  `XMLParser` XMLParser クラスのインスタンス生成は引数を指定せずにおこ ないます。 13.1

このクラスは次のインターフェース・メソッドとインスタンス変数を提供して います。

`attributes`
  要素名のマッピングへのマッピング・オブジェクトで、デフォルトは空の辞書 です。このデフォルト変数はすべての `XMLParser` インスタンスで 共有されるため、継承せずにオーバーライドする必要があります。なお、要素 名のマッピングの方は、その要素に妥当な属性名とそのデフォルトの属性値を マッピングしており、デフォルト値がない場合は `None` になります。

`elements`
  要素名からタプルへのマッピングです。タプルには要素の開始タグと終了タグ をそれぞれ処理する関数、または `unknown_starttag()` や `unknown_endtag()` 呼出された場合に使用する `None` が含ま れます。デフォルトは空の辞書になっています。このデフォルト変数はすべての `XMLParser` インスタンスで共有されるため、継承せずにオーバーライ ドする必要があります。

`entitydefs`
  エンティティ名からその値へのマッピングです。デフォルトで `'lt'`、 `'gt'`、 `'amp'`、 `'quot'`、 and `'apos'` の定義 がされています。

`reset`( | )

  インスタンスをリセットします。同時に未処理のデータはすべて失われます。 このメソッドはインスタンス生成時、暗黙裡に呼び出されます。

`setnomoretags`( | )

  タグの処理を中止します。このメソッドの呼び出し以降、すべての入力はリテラ ル(CDATA)として扱われます。

`setliteral`( | )

  リテラルモード(CDATA mode)に入ります。このモードは最後に処理した開始タ グに対応する終了タグが見つかった時点で自動的に終了します。

`feed`( | data)

  テキストをパーサに送ります。完全なタグで構成された部分までを処理し、不 完全なタグは次のデータが来るか `close()` が呼び出されるまでバッ ファリングされます。

`close`( | )

  現在バッファリング中のデータの前に end-of-file ファイルが来たものと強 制的にみなします。このメソッドは派生クラスにおいて、入力終了時におこな う追加処理のために再定義されることもありますが、再定義したメソッドの中 で必ずこの `close()` を呼び出さなければなりません。

`translate_references`( | data)

  data の中にある実体参照と文字参照をすべて変換し、変換後 の文字列を返します。

`getnamespace`( | )

  現在有効な名前空間の短縮名から名前空間 URI へのマッピングを返します。

`handle_xml`( | encoding, standalone)

  このメソッドは "`<?xml ...?>`" タグを処理します。引数はタグ中のエン コーディングの値とスタンドアロン宣言です。エンコーディングとスタンドア ロン属性はともにオプションです。デフォルトはそれぞれ `None` と文 字列 `'no'` になります。

`handle_doctype`( | tag, pubid, syslit, data)

  このメソッドは "`<!DOCTYPE...>`" 宣言を 処理します。引数にはルート要素のタグ名、公式公開識別子(指定されていない場合は `None`)、システム識別 子、および内部 DTD サブセットを処理せずそのまま文字列で指定します(指定 されていない場合は `None`)。

`handle_starttag`( | tag, method, attributes)

  このメソッドはインスタンス変数 `elements` にハンドラが定義され ている開始タグを処理します。tag はタグ名で、method は開始 タグの意味解析サポートに使われる関数(メソッド)です。attributes は `<>` タグ内に記述されている属性名がキー、属性値を値として持つ 辞書になります。文字およびエンティティの参照は解釈されます。たとえば、 開始タグ `<A HREF="http://www.cwi.nl/">` に対するこのメドッドの呼 出しは `handle_starttag('A', self.elements['A'][0], {'HREF': 'http://www.cwi.nl/'})` となります。基本的な実装は単純で、引数に attributes を使い、method を呼び出すだけのものです。

`handle_endtag`( | tag, method)

  このメソッドはインスタンス変数 `elements` にハンドラが定義され ている終了タグを処理します。tag はタグ名で、method は終了 タグの意味解析サポートに使われる関数(メソッド)です。たとえば、終了タグ `</A>` に対するこのメドッドの呼出しは `handle_endtag('A', self.elements['A'][1])` となります。基本的な実装は単純で、method を呼び出すだけのものです。

`handle_data`( | data)

  これは任意のデータを処理するメソッドです。派生クラスでオーバライドして 使います。基底クラスの実装では何もおこないません。

`handle_charref`( | ref)

  このメソッドは "`&#ref;`" 形式の文字参照を処理します。 ref は10進数または頭に"`x`"を付けた16進数のどちらでもか まいません。基本実装おいて ref の値として許される範囲は0から255 までに限定されています。この値が ASCII に変換された後、その文字列を 引数にしてメソッド `handle_data()` が呼び出されます。ref の値が許容範囲外のときは、エラーハンドリングのために `unknown_charref(ref)` が呼び出されます。ASCII 範囲外の 文字をサポートするには、サブクラスでこのメソッドをオーバーライドする必 要があります。

`handle_comment`( | comment)

  コメントを検出すると、このメソッドが呼び出されます。引数 comment は、デリミタ "`<!-`-``" から "`-`-`>`" の間にある文字列であり、 デリミタ自体は含まれません。たとえばコメント "`<!-`-`text-`-`>`" を処理する 場合、引数は `'text'` でこのメソッドが呼び出されます。このメソッドは デフォルトでは何もしません。

`handle_cdata`( | data)

  CDATA 要素を検出すると、このメソッドが呼び出されます。引数 data は、デリミタ "`<![CDATA[`" と "`]]>`" の間にある文字列であり、デリ ミタ自体は含まれません。たとえばエンティティ "`<![CDATA[text]]>`" を処理する 場合、引数は `'text'` でこのメソッドが呼び出されます。このメソッドは デフォルトでは何もしないため、オーバーライドして使用します。

`handle_proc`( | name, data)

  処理命令 (PI) を検出すると、このメソッドが呼び出されます。引数 name は処理命令のターゲット、data は、処理命令ターゲットと 終了デリミタの間にある文字列であり、デリミタ自体は含まれません。たとえ ば命令 "`<?XML text?>`" を処理する場合、引数は `'XML'` と `'text'` の2つでこのメソッドが呼び出されます。このメソッドはデフォ ルトでは何もしません。なおドキュメントの冒頭に現れる "`<?xml ..?>`" は `handle_xml()` で処理されます。

`handle_special`( | data)

  宣言を検出すると、このメソッドが呼び出されます。引数 data は、デ リミタ "`<!`" と "`>`" の間にある文字列であり、デリミタ自体は含 まれません。たとえばエンティティ宣言 "`<!ENTITY text>`" を処理する場合、引数は `'ENTITY text'` でこの メソッドが呼び出されます。このメソッドはデフォルトでは何もしないため、 オーバーライドして使用します。なおドキュメントの冒頭に現れる "`<!DOCTYPE ...>`" は別途処理しなければなりません。

`syntax_error`( | message)

  シンタックスエラーが発生すると、このメソッドが呼び出されます。引数 message はエラー内容を知らせるテキストです。このメソッドはデフォ ルトで `RuntimeError` 例外を発生させます。メソッドをオーバラ イドして、return するように変えることも可能です。なお、このメソッドが 呼び出されるのは回復可能なエラーの場合だけです。回復不能なエラー発生し たときは、`syntax_error()` を呼び出すことなく `RuntimeError` が発生します。

`unknown_starttag`( | tag, attributes)

  未知の開始タグを検出すると、このメドッドが呼び出されます。派生クラスで オーバライドして使います。基底クラスの実装では何もおこないません。

`unknown_endtag`( | tag)

  未知の終了タグを検出すると、このメドッドが呼び出されます。派生クラスで オーバライドして使います。基底クラスの実装では何もおこないません。

`unknown_charref`( | ref)

  解決できない文字参照を検出すると、このメドッドが呼び出されます。派 生クラスでオーバライドして使います。基底クラスの実装では何もおこないま せん。

`unknown_entityref`( | ref)

  解決できない実体参照を検出すると、このメドッドが呼び出されます。派生ク ラスでオーバライドして使います。基底クラスの実装では `syntax_error()` でエラーを通知するようになっています。

参考資料:

Extensible Markup Language (XML) 1.0
  World Wide Web Consortium (W3C) が送出した XML の仕様書で、XML のシンタックスと処理に必要な内容が定義され ています。仕様書の翻訳など、そのほかの文献は http://www.w3.org/XML/ で参照できます。

Python and XML Processing
  Python XML トピックガイドは Python で XML を扱 うための情報と XML 関連情報源へのリンクを数多く提供してい ます。

SIG for XML Processing in Python
  Python XML Special Interest Group は Python で XML を扱うための開発に多大な貢献をしています。

... ないます。13.1
  実際には、パーサに非標準的な形式のドキュメントを許容す るための、いくつかのキーワード引数を指定できるようになっており、その 内容は次の通りです。これらのデフォルト値はすべて `0` (false) で すが、最後のキーワード引数だけは `1` (true)になっています。 accept_unquoted_attributes (特定の属性がクォートされていなくても 受け入れるようにする)、 accept_missing_endtag_name (`</>` のようなタグ名なしの終了タグを許容する)、map_case (タグや属性 名が大文字で書かれていても、小文字で解釈する)、 accept_utf8 (UTF-8 文字列の入力を許容する。これは XML 標準規格で必須とされている内容ですが、 Python は今のところ UTF-8 を適切に処理できないため、デフォルトでは無 効になっています。)、 translate_attribute_references (属性値と して使われている文字列や実体参照はそれ以上解釈しない。)