"xml.sax" --- Support for SAX2 parsers
**************************************

**ソースコード:** Lib/xml/sax/__init__.py

======================================================================

"xml.sax" パッケージは Python 用の Simple API for XML (SAX) インターフ
ェースを実装した数多くのモジュールを提供しています。またパッケージには
SAX 例外と SAX API 利用者が頻繁に利用するであろう有用な関数群も含まれ
ています。

警告:

  "xml.sax" モジュールは悪意を持って作成されたデータに対して安全ではあ
  りません。信頼できないデータや認証されていないデータをパースする必要
  がある場合は XML の脆弱性 を参照してください。

バージョン 3.7.1 で変更: SAXパーサーは、セキュリティーを向上させるため
に、デフォルトで一般的な外部エンティティーを処理しなくなりました。以前
は、パーサーは、DTDおよびエンティティ用にファイルシステムからリモート
ファイルまたはロードされたローカルファイルをフェッチするためのネットワ
ーク接続を作成していました。この機能は parser オブジェクトと(実) 引数
"feature_external_ges" の "setFeature()" メソッドで再度有効にすること
ができます。

その関数群は以下の通りです:

xml.sax.make_parser(parser_list=[])

   SAX "XMLReader" オブジェクトを生成し、返します。最初に見つかったパ
   ーサーが使用されます。*parser_list* を与える場合、それは
   "create_parser()" という名前の関数をもつモジュール名のイテラブルで
   なければなりません。 *parser_list* に列挙されているモジュールは、パ
   ーサーのデフォルトリストにあるモジュールよりも先に使われます。

   バージョン 3.8 で変更: *parser_list* 引数はリストだけでなく、イテラ
   ブルでもよくなりました。

xml.sax.parse(filename_or_stream, handler, error_handler=handler.ErrorHandler())

   SAX パーサを生成し、そのパーサをドキュメントの解析に使用します。
   *filename_or_stream* として与えられるドキュメントは、ファイル名でも
   ファイルオブジェクトでもかまいません。 *handler* 引数は SAX
   "ContentHandler" のインスタントである必要があります。
   *error_handler* が与えられる場合は、 SAX "ErrorHandler"  のインスタ
   ンスである必要があります。この引数を省略した場合、全ての例外に対し
   て "SAXParseException" が発生します。 戻り値はありません。すべての
   操作は渡される *handler* によって行われなければなりません。

xml.sax.parseString(string, handler, error_handler=handler.ErrorHandler())

   "parse()" と同様ですが、こちらは引数で受け取ったバッファ *string*
   をパースします。 *string* は "str" インスタンスか *bytes-like
   object* でなければなりません。

   バージョン 3.5 で変更: "str" インスタンスがサポートされました。

典型的な SAX アプリケーションでは3種類のオブジェクト(リーダ、ハンドラ
、入力元)が用いられます。ここで言うリーダとはパーサを指しています。つ
まり、入力元からバイト列または文字列を読み込み、一連のイベントを発生さ
せるコード片のことです。発生したイベントはハンドラ・オブジェクトに割り
振られます。言い換えると、リーダがハンドラのメソッドを呼び出すわけです
。つまり、 SAX アプリケーションは、リーダ・オブジェクトを作成し、入力
元のオブジェクトを作成するか開き、ハンドラ・オブジェクトを作成し、これ
ら3つのオブジェクトを連携させる必要があります。準備の最終段階では、リ
ーダが呼び出され、入力をパースします。パース中には、入力データからの構
造イベントや構文イベントに基づいて、ハンドラ・オブジェクトのメソッドが
呼び出されます。

これらのオブジェクトでは、インターフェースだけが関係します。通常、これ
らはアプリケーション自体によってはインスタンス化されません。 Python は
明示的なインターフェースの概念を持たないので、インターフェースはクラス
として導入されました。しかし、アプリケーションは、提供されたクラスを継
承せずに実装してもかまいません。インターフェース "InputSource",
"Locator", "Attributes", "AttributesNS", "XMLReader"  はモジュール
"xml.sax.xmlreader" で定義されています。ハンドラインターフェースは
"xml.sax.handler" で定義されています。利便性のため、  "InputSource" (
よく直接インスタンス化されるクラス) とハンドラクラスは "xml.sax" から
もアクセスできます。これらのインターフェースについて下記で説明します。

このほかに "xml.sax" は次の例外クラスも提供しています。

exception xml.sax.SAXException(msg, exception=None)

   XML エラーと警告をカプセル化します。このクラスには XML パーサとアプ
   リケーションで発生するエラーおよび警告の基本的な情報を持たせること
   ができます。また機能追加や地域化のためにサブクラス化することも可能
   です。なお "ErrorHandler" で定義されているハンドラがこの例外のイン
   スタンスを受け取ることに注意してください。実際に例外を発生させるこ
   とは必須でなく、情報のコンテナとして利用されることもあるからです。

   インスタンスを作成する際 *msg* はエラー内容を示す可読データにしてく
   ださい。オプションの *exception* 引数は "None" にするか、パース用コ
   ードで捕捉されて情報として渡される例外にしてください。

   このクラスはSAX 例外の基底クラスになります。

exception xml.sax.SAXParseException(msg, exception, locator)

   パースエラー時に発生する "SAXException" のサブクラスです。パースエ
   ラーに関する情報として、このクラスのインスタンスが SAX
   "ErrorHandler" インターフェースのメソッドに渡されます。このクラスは
   "SAXException" 同様 SAX "Locator" インターフェースもサポートしてい
   ます。

exception xml.sax.SAXNotRecognizedException(msg, exception=None)

   SAX "XMLReader" が認識できない機能やプロパティに遭遇したとき発生さ
   せる "SAXException" のサブクラスです。 SAX アプリケーションや拡張モ
   ジュールにおいて同様の目的にこのクラスを利用することもできます。

exception xml.sax.SAXNotSupportedException(msg, exception=None)

   SAX "XMLReader" が要求された機能をサポートしていないとき発生させる
   "SAXException" のサブクラスです。 SAX アプリケーションや拡張モジュ
   ールにおいて同様の目的にこのクラスを利用することもできます。

参考:

  SAX: The Simple API for XML
     SAX API 定義に関し中心となっているサイトです。Java による実装とオ
     ンライン・ドキュメントが提供されています。実装と SAX API の歴史に
     関する情報のリンクも掲載されています。

  "xml.sax.handler" モジュール
     アプリケーションが提供するオブジェクトのインターフェース定義。

  "xml.sax.saxutils" モジュール
     SAX アプリケーション向けの有用な関数群。

  "xml.sax.xmlreader" モジュール
     パーサが提供するオブジェクトのインターフェース定義。


SAXException オブジェクト
=========================

"SAXException" 例外クラスは以下のメソッドをサポートしています:

SAXException.getMessage()

   エラー状態を示す可読メッセージを返します。

SAXException.getException()

   カプセル化した例外オブジェクトまたは "None" を返します。
