"xml.sax" --- SAX2 パーサのサポート
***********************************

**ソースコード:** 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" を返します。
