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

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

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

The "xml.sax" package provides a number of modules which implement the
Simple API for XML (SAX) interface for Python.  The package itself
provides the SAX exceptions and the convenience functions which will
be most used by users of the SAX API.

注釈:

  If you need to parse untrusted or unauthenticated data, see XML
  security.

バージョン 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つのオブジェクトを連携させる必要があります。準備の最終段階では、リ
ーダが呼び出され、入力をパースします。パース中には、入力データからの構
造イベントや構文イベントに基づいて、ハンドラ・オブジェクトのメソッドが
呼び出されます。

For these objects, only the interfaces are relevant; they are normally
not instantiated by the application itself.  Since Python does not
have an explicit notion of interface, they are formally introduced as
classes, but applications may use implementations which do not inherit
from the provided classes.  The "InputSource", "Locator",
"Attributes", "AttributesNS", and "XMLReader" interfaces are defined
in the module "xml.sax.xmlreader".  The handler interfaces are defined
in "xml.sax.handler".  For convenience, "InputSource" (which is often
instantiated directly) and the handler classes are also available from
"xml.sax".  These interfaces are described below.

In addition to these classes, "xml.sax" provides the following
exception classes.

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