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

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

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

"xml.sax" パッケージは、Simple API for XML (SAX) インターフェースを
Python 向けに実装する複数のモジュールを提供します。 パッケージ自体は、
SAX の例外と、SAX API の利用者がよく使う便利な関数を提供します。

注釈:

  信頼できないデータや、認証されていないデータを解析する場合は、XML の
  セキュリティ を参照してください。

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

以下の便利な関数とデータがあります。

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, errorHandler=handler.ErrorHandler())

   SAX パーサーを作成し、それを使って文書を解析します。
   *filename_or_stream* に渡す文書は、システム識別子 (入力元を識別する
   文字列で、通常はファイル名か URL)、 *パス類似* オブジェクト、または
   ファイルオブジェクトで指定できます。 システム識別子が既存のファイル
   を指していない場合は、"urllib.request.urlopen()" で開きます。
   *handler* 引数には SAX の "ContentHandler" インスタンスが必要です。
   *errorHandler* を指定する場合は SAX の "ErrorHandler" インスタンス
   でなければなりません。 省略すると、すべてのエラーで
   "SAXParseException" を送出します。 戻り値はありません。 すべての処
   理は、渡した *handler* で行う必要があります。

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

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

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

xml.sax.default_parser_list

   "make_parser()" が *parser_list* 引数に指定されたモジュールの後に試
   す、モジュール名のリストです。 通常は "'xml.sax.expatreader'" を含
   みますが、"PY_SAX_PARSER" 環境変数が設定されていて環境変数が無視さ
   れない場合は、 そこから取得したカンマ区切りのモジュール名のリストに
   なります。

典型的な 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 アプリケーションや拡張でも、
   同様の目的にこのクラスを使えます。

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

   利用できるパーサーがないときに送出する "SAXNotSupportedException"
   のサブクラスです。 パーサーモジュールは、提供するパーサーを利用でき
   ない場合、インポート時または解析中にこの例外を送出します。 また、
   "make_parser()" は、試したどのモジュールも利用可能なパーサーを提供
   しなかった場合にこの例外を送出します。

参考:

  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" を返します。
