xml.sax.handler --- کلاس‌های پایه برای هندلرهای SAX

کد منبع: Lib/xml/sax/handler.py

API مربوط به SAX پنج نوع هندلر را تعریف می‌کند: هندلرهای محتوا، هندلرهای DTD، هندلرهای خطا، حل‌کننده‌های موجودیت و هندلرهای واژگانی. برنامه‌ها معمولاً فقط نیاز دارند آن رابط‌هایی را پیاده‌سازی کنند که به رویدادهای آن‌ها علاقه‌مند هستند؛ آن‌ها می‌توانند رابط‌ها را در یک شیء یا در چند شیء پیاده‌سازی کنند. پیاده‌سازی‌های هندلر باید از کلاس‌های پایه ارائه‌شده در ماژول xml.sax.handler ارث‌بری کنند، تا همه‌ی متدها پیاده‌سازی‌های پیش‌فرض داشته باشند.

class xml.sax.handler.ContentHandler

این رابط کال‌بک اصلی در SAX و مهم‌ترین رابط برای برنامه‌های کاربردی است. ترتیب رویدادها در این رابط، ترتیب اطلاعات در سند را منعکس می‌کند.

class xml.sax.handler.DTDHandler

مدیریت رویدادهای DTD.

این رابط فقط رویدادهای DTD مورد نیاز برای تجزیه‌ی پایه (موجودیت‌های تجزیه‌نشده و ویژگی‌ها) را مشخص می‌کند.

class xml.sax.handler.EntityResolver

رابط پایه برای حل موجودیت‌ها. اگر یک شیء ایجاد کنید که این رابط را پیاده‌سازی می‌کند، سپس آن شیء را در پارسر خود ثبت کنید، پارسر متد موجود در شیء شما را برای حل تمام موجودیت‌های خارجی فراخوانی خواهد کرد.

class xml.sax.handler.ErrorHandler

رابطی که پارسر برای ارائه پیام‌های خطا و هشدار به برنامه از آن استفاده می‌کند. متدهای این شیء تعیین می‌کنند که آیا خطاها بلافاصله به استثناها تبدیل می‌شوند یا به روش دیگری رسیدگی می‌شوند.

class xml.sax.handler.LexicalHandler

رابطی که پارسر برای بازنمایی رویدادهای کم‌تکرار استفاده می‌کند، که ممکن است برای بسیاری از برنامه‌ها مورد توجه نباشند.

علاوه بر این کلاس‌ها، xml.sax.handler ثابت‌های نمادینی را برای نام قابلیت‌ها و ویژگی‌ها فراهم می‌کند.

xml.sax.handler.feature_namespaces
مقدار: "http://xml.org/sax/features/namespaces"
true: پردازش فضای نام انجام شود.
false: به‌صورت اختیاری، پردازش فضای نام انجام نشود (مستلزم namespace-prefixes؛ پیش‌فرض).
دسترسی: (تجزیه) فقط خواندنی؛ (بدون تجزیه) خواندن/نوشتن
xml.sax.handler.feature_namespace_prefixes
مقدار: "http://xml.org/sax/features/namespace-prefixes"
true: نام‌های اصلی دارای پیشوند و ویژگی‌های مورد استفاده برای اعلامیه‌های فضای نام را گزارش می‌دهد.
false: ویژگی‌های استفاده‌شده برای اعلان‌های فضای نام را گزارش نمی‌کند، و به‌صورت اختیاری نام‌های پیشونددار اصلی را گزارش نمی‌کند (پیش‌فرض).
دسترسی: (تجزیه) فقط خواندنی؛ (بدون تجزیه) خواندن/نوشتن

The parser based on xml.parsers.expat does not support this feature.

xml.sax.handler.feature_string_interning
مقدار: "http://xml.org/sax/features/string-interning"
true: All element names, prefixes, attribute names, Namespace URIs, and local names are interned in a dictionary (see property_interning_dict).
false: نام‌ها لزوماً درونی‌سازی‌شده نیستند، اگرچه ممکن است این‌طور باشند (پیش‌فرض).
دسترسی: (تجزیه) فقط خواندنی؛ (بدون تجزیه) خواندن/نوشتن
xml.sax.handler.feature_validation
مقدار: "http://xml.org/sax/features/validation"
true: تمام خطاهای اعتبارسنجی را گزارش می‌دهد (external-general-entities و external-parameter-entities را نیز فعال می‌کند).
false: خطاهای اعتبارسنجی گزارش داده نمی‌شوند.
دسترسی: (تجزیه) فقط خواندنی؛ (بدون تجزیه) خواندن/نوشتن

The parser based on xml.parsers.expat does not support this feature, because Expat is a non-validating parser.

xml.sax.handler.feature_external_ges

هشدار

فعال‌سازی این قابلیت، در صورتی که پارسر با محتوای XML ارائه‌شده توسط کاربر استفاده شود، آسیب‌پذیری در برابر حملات موجودیت خارجی ایجاد می‌کند. لطفاً پیش از فعال‌سازی این قابلیت، مدل تهدید خود را بررسی کنید.

مقدار: "http://xml.org/sax/features/external-general-entities"
true: همه‌ی موجودیت‌های عمومی خارجی (متنی) را شامل می‌شود.
false: موجودیت‌های عمومی خارجی را شامل نمی‌شود.
دسترسی: (تجزیه) فقط خواندنی؛ (بدون تجزیه) خواندن/نوشتن
xml.sax.handler.feature_external_pes
مقدار: "http://xml.org/sax/features/external-parameter-entities"
true: شامل تمام موجودیت‌های پارامتری خارجی، از جمله زیرمجموعه‌ی DTD خارجی می‌شود.
نادرست: هیچ موجودیت پارامتر خارجی، حتی زیرمجموعه DTD خارجی، را شامل نکنید.
دسترسی: (تجزیه) فقط خواندنی؛ (بدون تجزیه) خواندن/نوشتن

The parser based on xml.parsers.expat does not support this feature.

xml.sax.handler.all_features

فهرست تمام قابلیت‌ها.

xml.sax.handler.property_lexical_handler
مقدار: "http://xml.org/sax/properties/lexical-handler"
data type: LexicalHandler
توضیحات: یک هندلر افزونه‌ای اختیاری برای رویدادهای واژگانی مانند کامنت‌ها.
دسترسی: خواندن/نوشتن
xml.sax.handler.property_declaration_handler
مقدار: "http://xml.org/sax/properties/declaration-handler"
data type: an object implementing the SAX2 DeclHandler interface
توضیحات: یک هندلر افزونه‌ای اختیاری برای رویدادهای مرتبط با DTD، به‌جز نشان‌گذاری‌ها و موجودیت‌های تجزیه‌نشده.
دسترسی: خواندن/نوشتن

No parser in the standard library supports this property, and the standard library provides no such handler.

xml.sax.handler.property_dom_node
مقدار: "http://xml.org/sax/properties/dom-node"
data type: xml.dom.Node
توضیح: هنگام تجزیه، گره DOM جاری که بازدید می‌شود، اگر این یک پیمایش‌گر DOM باشد؛ هنگامی که تجزیه انجام نمی‌شود، گره DOM ریشه برای پیمایش.
دسترسی: (تجزیه) فقط خواندنی؛ (بدون تجزیه) خواندن/نوشتن

No parser in the standard library supports this property.

xml.sax.handler.property_xml_string
مقدار: "http://xml.org/sax/properties/xml-string"
نوع داده: بایت‌ها
توضیح: رشته‌ای لفظی از نویسه‌ها که منبع رویداد جاری بود.
access: read-only, and only during a handler callback
xml.sax.handler.property_encoding
value: "http://www.python.org/sax/properties/encoding"
data type: String
description: The name of the encoding to assume for input data.
دسترسی: خواندن/نوشتن

No parser in the standard library supports this property.

xml.sax.handler.property_interning_dict
value: "http://www.python.org/sax/properties/interning-dict"
data type: Dictionary
description: The dictionary used to intern names, or None if names are not interned. Setting it enables interning, as does the feature_string_interning feature.
دسترسی: خواندن/نوشتن
xml.sax.handler.all_properties

فهرست تمام نام‌های ویژگی‌های شناخته‌شده.

اشیای ContentHandler

انتظار می‌رود کاربران برای پشتیبانی از برنامه‌ی خود، یک زیرکلاس از ContentHandler ایجاد کنند. متدهای زیر توسط پارسر در رویدادهای مناسب در سند ورودی فراخوانی می‌شوند:

ContentHandler.setDocumentLocator(locator)

توسط پارسر فراخوانی می‌شود تا یک مکان‌یاب برای یافتن منشأ رویدادهای سند در اختیار برنامه قرار دهد.

به‌شدت توصیه می‌شود (هرچند به‌طور مطلق الزامی نیست) که پارسرهای SAX یک مکان‌یاب فراهم کنند: اگر این کار را انجام دهند، باید مکان‌یاب را با فراخوانی این متد، پیش از فراخوانی هر یک از متدهای دیگر در رابط DocumentHandler، در اختیار برنامه قرار دهند.

مکان‌یاب به برنامه اجازه می‌دهد موقعیت پایانی هر رویداد مرتبط با سند را تعیین کند، حتی اگر پارسر خطایی گزارش نکند. معمولاً برنامه از این اطلاعات برای گزارش خطاهای خود استفاده می‌کند (مانند محتوای نویسه‌ای که با قوانین تجاری برنامه مطابقت ندارد). اطلاعاتی که مکان‌یاب برمی‌گرداند احتمالاً برای استفاده در یک موتور جستجو کافی نیست.

توجه داشته باشید که مکان‌یاب (locator) اطلاعات صحیح را فقط در حین فراخوانی رویدادها در این رابط برمی‌گرداند. برنامه نباید در هیچ زمان دیگری سعی در استفاده از آن کند.

ContentHandler.startDocument()

دریافت اعلان آغاز یک سند.

پارسر SAX این متد را فقط یک‌بار، پیش از هر متد دیگری در این رابط یا در DTDHandler (به‌جز setDocumentLocator()) فراخوانی خواهد کرد.

ContentHandler.endDocument()

دریافت اعلان پایان یک سند.

پارسر SAX این متد را تنها یک بار فراخوانی می‌کند، و این آخرین متدی خواهد بود که در حین پارس فراخوانی می‌شود. پارسر این متد را فراخوانی نخواهد کرد، مگر اینکه یا پارس کردن را رها کرده باشد (به دلیل خطای غیرقابل بازیابی) یا به پایان ورودی رسیده باشد.

ContentHandler.startPrefixMapping(prefix, uri)

آغاز محدوده‌ی یک نگاشت فضای نام پیشوند-URI.

اطلاعات حاصل از این رویداد برای پردازش عادی فضای نام ضروری نیست: خواننده SAX XML هنگامی که قابلیت feature_namespaces فعال باشد (حالت پیش‌فرض)، پیشوندهای نام عناصر و ویژگی‌ها را به‌طور خودکار جایگزین می‌کند.

با این حال، مواردی وجود دارد که برنامه‌ها نیاز دارند از پیشوندها در داده‌های نویسه‌ای یا در مقدارهای ویژگی استفاده کنند، مواردی که نمی‌توان پیشوندها را در آن‌ها به‌صورت ایمن به‌طور خودکار بسط داد؛ رویدادهای startPrefixMapping() و endPrefixMapping() اطلاعات را در اختیار برنامه قرار می‌دهند تا در صورت لزوم، خود برنامه پیشوندها را در آن زمینه‌ها بسط دهد.

توجه داشته باشید که تضمینی وجود ندارد که رویدادهای startPrefixMapping() و endPrefixMapping() به‌درستی نسبت به یکدیگر تودرتو باشند: تمام رویدادهای startPrefixMapping() پیش از رویداد متناظر startElement() رخ خواهند داد، و تمام رویدادهای endPrefixMapping() پس از رویداد متناظر endElement() رخ خواهند داد، اما ترتیب آن‌ها تضمین نمی‌شود.

ContentHandler.endPrefixMapping(prefix)

پایان دادن به محدوده‌ی یک نگاشت prefix-URI.

برای جزئیات، startPrefixMapping() را ببینید. این رویداد همواره پس از رویداد متناظر endElement() رخ می‌دهد، اما به‌جز این، ترتیب رویدادهای endPrefixMapping() تضمین نمی‌شود.

ContentHandler.startElement(name, attrs)

آغاز یک عنصر را در حالت بدون فضای نام اعلام می‌کند.

پارامتر name شامل نام خام XML 1.0 برای نوع عنصر به‌صورت یک رشته است و پارامتر attrs شیءای از رابط Attributes را نگه می‌دارد که ویژگی‌های عنصر را شامل می‌شود. شیءای که به‌عنوان attrs ارسال می‌شود ممکن است توسط پارسر دوباره استفاده شود؛ نگه‌داشتن ارجاع به آن روش قابل‌اطمینانی برای حفظ یک کپی از ویژگی‌ها نیست. برای نگه‌داشتن یک کپی از ویژگی‌ها، از متد copy() شیء attrs استفاده کنید.

ContentHandler.endElement(name)

پایان یک عنصر را در حالت بدون فضای نام اعلام می‌کند.

پارامتر name شامل نام نوع عنصر است، درست مانند رویداد startElement().

ContentHandler.startElementNS(name, qname, attrs)

آغاز یک عنصر را در حالت فضای نام اعلام می‌کند.

پارامتر name شامل نام نوع عنصر به‌صورت یک تاپل (uri, localname) است، پارامتر qname شامل نام خام XML 1.0 به‌کاررفته در سند منبع است، و پارامتر attrs یک نمونه از رابط AttributesNS را نگه می‌دارد که شامل ویژگی‌های عنصر است. اگر هیچ فضای نامی به عنصر مرتبط نباشد، کامپوننت uri از name برابر None خواهد بود. ممکن است شیء ارسال‌شده به‌عنوان attrs توسط پارسر دوباره استفاده شود؛ نگه‌داشتن یک ارجاع به آن، راه قابل‌اعتمادی برای حفظ یک نسخه از ویژگی‌ها نیست. برای حفظ یک نسخه از ویژگی‌ها، از متد copy() شیء attrs استفاده کنید.

پارسرها می‌توانند پارامتر qname را روی None تنظیم کنند، مگر آنکه قابلیت feature_namespace_prefixes فعال شده باشد.

ContentHandler.endElementNS(name, qname)

پایان یک عنصر را در حالت فضای نام اعلام می‌کند.

پارامتر name شامل نام نوع المان است، همان‌طور که در متد startElementNS() وجود دارد، و پارامتر qname نیز به همین صورت است.

ContentHandler.characters(content)

دریافت اعلان داده‌های نویسه‌ای.

پارسر این متد را برای گزارش هر تکه از داده‌های نویسه‌ای فراخوانی خواهد کرد. پارسرهای SAX ممکن است تمام داده‌های نویسه‌ای پیوسته را در یک تکه برگردانند، یا آن را به چند تکه تقسیم کنند؛ با این حال، تمام نویسه‌های هر رویداد واحد باید از یک موجودیت خارجی یکسان آمده باشند تا Locator اطلاعات مفیدی فراهم کند.

content ممکن است یک نمونه از رشته یا bytes باشد؛ ماژول خواننده‌ی expat همیشه رشته تولید می‌کند.

توجه

رابط SAX 1 پیشین که توسط Python XML Special Interest Group ارائه‌شده بود، برای این متد از یک رابط شبیه‌تر به Java استفاده می‌کرد. از آنجا که بیشتر پارسرهای استفاده‌شده از Python از رابط قدیمی‌تر بهره نمی‌بردند، امضای ساده‌تر برای جایگزینی آن انتخاب شد. برای تبدیل کد قدیمی به رابط جدید، به‌جای اسلایس محتوا با پارامترهای قدیمی offset و length، از content استفاده کنید.

ContentHandler.ignorableWhitespace(whitespace)

دریافت اعلان مربوط به فضای سفید قابل‌چشم‌پوشی در محتوای عنصر.

پارسرهای اعتبارسنج باید از این متد برای گزارش هر تکه از فضای سفید قابل چشم‌پوشی استفاده کنند (به توصیه‌نامه W3C برای XML 1.0، بخش 2.10 مراجعه کنید): پارسرهای غیراعتبارسنج نیز در صورتی می‌توانند از این متد استفاده کنند که قادر به تجزیه و استفاده از مدل‌های محتوا باشند.

پارسرهای SAX ممکن است تمام فضای سفید پیوسته را در یک تکه برگردانند، یا ممکن است آن را به چند تکه تقسیم کنند؛ با این حال، تمام نویسه‌های هر رویداد واحد باید از یک موجودیت خارجی (external entity) یکسان آمده باشند، تا Locator اطلاعات مفیدی ارائه دهد.

ContentHandler.processingInstruction(target, data)

دریافت اعلان یک دستور پردازشی.

پارسر این متد را یک‌بار به‌ازای هر دستورالعمل پردازشی (processing instruction) که یافت شود فراخوانی می‌کند: توجه داشته باشید که دستورالعمل‌های پردازشی ممکن است پیش یا پس از المان اصلی سند رخ دهند.

پارسر SAX هرگز نباید اعلامیه XML (XML 1.0، بخش 2.8) یا اعلامیه متن (XML 1.0، بخش 4.3.1) را با استفاده از این متد گزارش کند.

ContentHandler.skippedEntity(name)

دریافت اعلان رد شدن یک موجودیت.

پارسر این متد را یک بار برای هر موجودیتی که رد می‌شود فراخوانی می‌کند. پردازنده‌های بدون اعتبارسنجی ممکن است موجودیت‌ها را رد کنند، اگر اعلان‌ها را ندیده باشند (زیرا، برای مثال، آن موجودیت در یک زیرمجموعه‌ی خارجی DTD اعلان شده است). همه‌ی پردازنده‌ها ممکن است موجودیت‌های خارجی را رد کنند، بسته به مقادیر ویژگی‌های feature_external_ges و feature_external_pes.

اشیای DTDHandler

نمونه‌های DTDHandler متدهای زیر را فراهم می‌کنند:

DTDHandler.notationDecl(name, publicId, systemId)

مدیریت رویداد اعلان نماد .

DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)

رویداد اعلام موجودیت تجزیه‌نشده را مدیریت می‌کند.

اشیای EntityResolver

EntityResolver.resolveEntity(publicId, systemId)

شناسه سیستمی یک موجودیت را حل کنید و یا شناسه سیستمی برای خواندن را به‌صورت یک رشته، یا یک InputSource برای خواندن برگردانید. پیاده‌سازی پیش‌فرض systemId را برمی‌گرداند.

اشیای ErrorHandler

از اشیایی که این رابط را دارند برای دریافت اطلاعات خطا و هشدار از XMLReader استفاده می‌شود. اگر شیءای ایجاد کنید که این رابط را پیاده‌سازی کند و سپس آن شیء را در XMLReader خود ثبت کنید، پارسر متدهای موجود در شیء شما را برای گزارش تمام هشدارها و خطاها فراخوانی خواهد کرد. ۳ سطح خطا در دسترس است: هشدارها، خطاهای (احتمالاً) قابل بازیابی، و خطاهای غیرقابل بازیابی. تمام متدها یک SAXParseException را به‌عنوان تنها پارامتر می‌گیرند. با پرتاب شیء استثنای داده‌شده می‌توان خطاها و هشدارها را به یک استثنا تبدیل کرد.

ErrorHandler.error(exception)

هنگامی فراخوانی می‌شود که پارسر با یک خطای قابل بازیابی مواجه شود. اگر این متد استثنایی را پرتاب نکند، ممکن است تجزیه ادامه یابد، اما برنامه نباید انتظار اطلاعات بیشتری از سند را داشته باشد. اجازه دادن به پارسر برای ادامه ممکن است امکان کشف خطاهای بیشتر در سند ورودی را فراهم کند.

ErrorHandler.fatalError(exception)

هنگامی فراخوانی می‌شود که پارسر با خطایی مواجه شود که امکان بازیابی از آن وجود ندارد؛ انتظار می‌رود تجزیه با بازگشت این متد خاتمه یابد.

ErrorHandler.warning(exception)

این متد زمانی فراخوانی می‌شود که پارسر اطلاعات هشدار جزئی را به برنامه ارائه می‌دهد. انتظار می‌رود پس از بازگشت این متد، تجزیه ادامه یابد و اطلاعات سند همچنان به برنامه ارسال شود. پرتاب یک استثنا در این متد باعث پایان تجزیه خواهد شد.

اشیای LexicalHandler

هندلر اختیاری SAX2 برای رویدادهای واژگانی.

این هندلر برای دریافت اطلاعات واژگانی درباره‌ی یک سند XML استفاده می‌شود. اطلاعات واژگانی شامل اطلاعات توصیف‌کننده‌ی کدگذاری استفاده‌شده در سند و کامنت‌ها XML نهفته در سند، و همچنین مرزهای بخش DTD و هر بخش CDATA است. هندلرهای واژگانی به همان شیوه‌ی هندلرهای محتوا استفاده می‌شوند.

برای تنظیم LexicalHandler یک XMLReader، از متد setProperty با شناسه‌ی ویژگی 'http://xml.org/sax/properties/lexical-handler' استفاده کنید.

LexicalHandler.comment(content)

یک کامنت را در هر جایی از سند (از جمله DTD و خارج از عنصر سند) گزارش می‌دهد.

LexicalHandler.startDTD(name, public_id, system_id)

در صورتی که سند دارای DTD مرتبطی باشد، آغاز اعلامیه‌های DTD را گزارش می‌کند.

LexicalHandler.endDTD()

پایان اعلان DTD را گزارش می‌دهد.

LexicalHandler.startCDATA()

آغاز یک بخش نمادگذاری‌شده‌ی CDATA را گزارش می‌کند.

محتوای بخش علامت‌گذاری‌شده CDATA از طریق هندلر نویسه‌ها گزارش می‌شود.

LexicalHandler.endCDATA()

پایان یک بخش نمادگذاری‌شده CDATA را گزارش می‌دهد.