xml.sax --- پشتیبانی از پارسرهای SAX2

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

بسته‌ی xml.sax تعدادی ماژول فراهم می‌کند که رابط Simple API for XML (SAX) را برای پایتون پیاده‌سازی می‌کنند. خود بسته، استثناهای SAX و توابع تسهیل‌کننده‌ای را فراهم می‌کند که کاربران API SAX بیشترین استفاده را از آن‌ها خواهند داشت.

توجه

اگر لازم است داده‌های غیرقابل‌اعتماد یا احراز هویت‌نشده را تجزیه کنید، امنیت XML را ببینید.

تغییر یافته در نسخه‌ی 3.7.1: پارسر SAX برای افزایش امنیت، دیگر به‌طور پیش‌فرض موجودیت‌های خارجی عمومی را پردازش نمی‌کند. پیش از این، پارسر برای DTD و موجودیت‌ها اتصال‌های شبکه ایجاد می‌کرد تا پرونده‌های دوردست را واکشی کند یا پرونده‌های محلی را از سامانه فایل‌بندی بارگذاری کند. این قابلیت را می‌توان دوباره با متد setFeature() بر روی شیء پارسر و آرگومان feature_external_ges فعال کرد.

The convenience functions and data are:

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())

Create a SAX parser and use it to parse a document. The document, passed in as filename_or_stream, can be a system identifier (a string identifying the input source -- typically a file name or a URL), a path-like object, or a file object. A system identifier which does not refer to an existing file is opened with urllib.request.urlopen(). The handler parameter needs to be a SAX ContentHandler instance. If errorHandler is given, it must be a SAX ErrorHandler instance; if omitted, SAXParseException will be raised on all errors. There is no return value; all work must be done by the handler passed in.

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

مشابه parse() است، اما از یک بافر string که به‌عنوان پارامتر دریافت شده است، تجزیه می‌کند. string باید نمونه‌ای از str یا یک bytes-like object باشد.

تغییر یافته در نسخه‌ی 3.5: پشتیبانی از نمونه‌های str افزوده شد.

xml.sax.default_parser_list

The list of the names of modules which are tried by make_parser() after the modules named in its parser_list argument. It contains 'xml.sax.expatreader', or, if the PY_SAX_PARSER environment variable is set and the environment is not ignored, the comma-separated list of module names taken from it.

یک برنامه SAX معمول از سه نوع شیء استفاده می‌کند: خواننده‌ها، هندلرها و منابع ورودی. «خواننده» در این زمینه اصطلاح دیگری برای پارسر است، یعنی قطعه‌کدی که بایت‌ها یا نویسه‌ها را از منبع ورودی می‌خواند و دنباله‌ای از رویدادها را تولید می‌کند. سپس رویدادها به اشیاء هندلر توزیع می‌شوند، یعنی خواننده متدی را روی هندلر فراخوانی می‌کند. بنابراین یک برنامه SAX باید یک شیء خواننده به دست آورد، منابع ورودی را ایجاد یا باز کند، هندلرها را ایجاد کند و این اشیاء را به یکدیگر متصل کند. به‌عنوان آخرین مرحله آماده‌سازی، خواننده برای تجزیه ورودی فراخوانی می‌شود. در حین تجزیه، متدهای اشیاء هندلر بر اساس رویدادهای ساختاری و نحوی داده‌های ورودی فراخوانی می‌شوند.

برای این اشیاء، تنها رابط‌ها اهمیت دارند؛ آن‌ها معمولاً توسط خود برنامه نمونه‌سازی نمی‌شوند. از آن‌جا که پایتون مفهوم صریحی از رابط ندارد، آن‌ها به‌طور رسمی به‌عنوان کلاس معرفی شده‌اند، اما برنامه‌ها می‌توانند از پیاده‌سازی‌هایی استفاده کنند که از کلاس‌های ارائه‌شده ارث‌بری نمی‌کنند. رابط‌های 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 ارسال می‌شوند تا اطلاعاتی را درباره خطای تجزیه ارائه دهند. این کلاس از رابط SAX Locator و همچنین رابط SAXException پشتیبانی می‌کند.

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

زیرکلاسی از SAXException که زمانی پرتاب می‌شود که یک XMLReader SAX با یک ویژگی یا خصوصیت شناخته‌نشده مواجه شود. برنامه‌ها و افزونه‌های SAX می‌توانند از این کلاس برای اهداف مشابه استفاده کنند.

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

زیرکلاسی از SAXException که هنگامی پرتاب می‌شود که از یک XMLReader SAX خواسته شود قابلیتی را که پشتیبانی نمی‌شود فعال کند، یا ویژگی‌ای را روی مقداری تنظیم کند که پیاده‌سازی از آن پشتیبانی نمی‌کند. برنامه‌ها و افزونه‌های SAX می‌توانند از این کلاس برای اهداف مشابه استفاده کنند.

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

Subclass of SAXNotSupportedException raised when no parser is available. A parser module raises it when it is imported or during parsing if the parser it provides cannot be used, and make_parser() raises it if no module from the tried ones provides a usable parser.

همچنین ملاحظه نمائید

SAX: API ساده برای XML

این وب‌سایت نقطه کانونی برای تعریف SAX API است. این وب‌سایت یک پیاده‌سازی جاوا و مستندات برخط ارائه می‌کند. پیوندهایی به پیاده‌سازی‌ها و اطلاعات تاریخی نیز در دسترس هستند.

ماژول xml.sax.handler

تعریف رابط‌ها برای اشیاء ارائه‌شده توسط برنامه.

ماژول xml.sax.saxutils

توابع کمکی برای استفاده در برنامه‌های SAX.

ماژول xml.sax.xmlreader

تعاریف رابط‌ها برای اشیاء ارائه‌شده توسط پارسر.

اشیای SAXException

کلاس استثنای SAXException از متدهای زیر پشتیبانی می‌کند:

SAXException.getMessage()

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

SAXException.getException()

یک شیء استثنای کپسوله‌شده یا None را برمی‌گرداند.