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 فعال کرد.

توابع کمکی و داده‌ها عبارتند از:

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 معمول از سه نوع شیء استفاده می‌کند: خواننده‌ها، هندلرها و منابع ورودی. «خواننده» در این زمینه اصطلاح دیگری برای پارسر است، یعنی قطعه‌کدی که بایت‌ها یا نویسه‌ها را از منبع ورودی می‌خواند و دنباله‌ای از رویدادها را تولید می‌کند. سپس رویدادها به اشیاء هندلر توزیع می‌شوند، یعنی خواننده متدی را روی هندلر فراخوانی می‌کند. بنابراین یک برنامه 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)

زیرکلاس SAXNotSupportedException که وقتی هیچ پارسری در دسترس نیست پرتاب می‌شود. یک ماژول پارسر هنگام وارد کردن یا در حین تجزیه، اگر پارسر ارائه شده قابل استفاده نباشد، این استثنا را پرتاب می‌کند، و make_parser() آن را پرتاب می‌کند اگر هیچ ماژولی از میان امتحان شده‌ها پارسر قابل استفاده‌ای ارائه ندهد.

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

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

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

ماژول xml.sax.handler

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

ماژول xml.sax.saxutils

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

ماژول xml.sax.xmlreader

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

اشیای SAXException

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

SAXException.getMessage()

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

SAXException.getException()

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