xml.sax.saxutils --- ابزارهای SAX

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

---

ماژول xml.sax.saxutils شامل تعدادی کلاس و تابع است که به‌طور معمول هنگام ایجاد برنامه‌های SAX، چه به‌صورت مستقیم و چه به‌عنوان کلاس‌های پایه، مفید هستند.

xml.sax.saxutils.escape(data, entities={})

خنثی کردن '&'، '<' و '>' در یک رشته‌ی داده.

شما می‌توانید با ارسال یک دیکشنری به‌عنوان پارامتر اختیاری entities، دیگر رشته‌های داده را خنثی کنید. همه‌ی کلیدها و مقدارها باید رشته باشند؛ هر کلید با مقدار متناظر خود جایگزین می‌شود. نویسه‌های '&'، '<' و '>' همیشه خنثی می‌شوند، حتی اگر entities ارائه شده باشد.

توجه

این تابع باید فقط برای خنثی کردن نویسه‌هایی به کار رود که نمی‌توان آن‌ها را مستقیماً در XML استفاده کرد. از این تابع به‌عنوان یک تابع عمومی ترجمه‌ی رشته استفاده نکنید.

xml.sax.saxutils.unescape(data, entities={})

خارج کردن '&'، '<' و '>' از حالت خنثی در رشته‌ای از داده.

می‌توانید با گذراندن یک دیکشنری به‌عنوان پارامتر اختیاری entities، سایر رشته‌های داده را از حالت خنثی خارج کنید. همه‌ی کلیدها و مقادیر باید رشته باشند؛ هر کلید با مقدار متناظر خود جایگزین خواهد شد. '&'، '<' و '>' همیشه از حالت خنثی خارج می‌شوند، حتی اگر entities ارائه شده باشد.

xml.sax.saxutils.quoteattr(data, entities={})

مشابه escape()، اما همچنین data را برای استفاده به‌عنوان مقدار یک ویژگی آماده می‌کند. مقدار بازگشتی، نسخه‌ای از data است که بین علامت‌های نقل‌قول قرار گرفته و هر جایگزین اضافی مورد نیاز در آن اعمال شده است. quoteattr() یک نویسه علامت نقل‌قول را بر اساس محتوای data انتخاب می‌کند و تلاش می‌کند از کدگذاری هیچ نویسه علامت نقل‌قولی در رشته اجتناب کند. اگر هر دو نویسه علامت نقل‌قول تکی و دوتایی از قبل در data وجود داشته باشند، نویسه‌های علامت نقل‌قول دوتایی کدگذاری می‌شوند و data بین علامت‌های نقل‌قول دوتایی قرار می‌گیرد. رشته حاصل را می‌توان مستقیماً به‌عنوان مقدار یک ویژگی استفاده کرد:

>>> print("<element attr=%s>" % quoteattr("ab ' cd \" ef"))
<element attr="ab ' cd &quot; ef">

این تابع هنگام تولید مقادیر ویژگی‌ها برای HTML یا هر SGML که از سینتکس عینی مرجع (reference concrete syntax) استفاده می‌کند، مفید است.

class xml.sax.saxutils.XMLGenerator(out=None, encoding='iso-8859-1', short_empty_elements=False)

این کلاس رابط ContentHandler را با نوشتن رویدادهای SAX обратно در یک سند XML پیاده‌سازی می‌کند. به بیان دیگر، استفاده از XMLGenerator به‌عنوان هندلر محتوا (content handler)، سند اصلی را که در حال تجزیه است بازتولید خواهد کرد. out باید یک شیء شبه‌پرونده باشد که پیش‌فرض آن sys.stdout خواهد بود. encoding کدگذاری جریان خروجی است که پیش‌فرض آن 'iso-8859-1' است. short_empty_elements قالب‌بندی عناصری را که هیچ محتوایی ندارند کنترل می‌کند: اگر False (پیش‌فرض) باشد، آن‌ها به‌صورت یک جفت برچسب آغاز/پایان خروجی داده می‌شوند و اگر روی True تنظیم شود، آن‌ها به‌صورت یک برچسب خودبسته خروجی داده می‌شوند.

تغییر یافته در نسخه‌ی 3.2: پارامتر short_empty_elements افزوده شد.

class xml.sax.saxutils.XMLFilterBase(base)

این کلاس برای قرار گرفتن بین یک XMLReader و هندلرهای رویداد برنامه‌ی کلاینت طراحی شده است. به‌طور پیش‌فرض، این کلاس هیچ کاری جز انتقال درخواست‌ها به خواننده و انتقال رویدادها به هندلرها به‌صورت بدون تغییر انجام نمی‌دهد، اما زیرکلاس‌ها می‌توانند متدهای خاصی را بازنویسی کنند تا جریان رویدادها یا درخواست‌های پیکربندی را در حین عبور تغییر دهند.

getParent()

Return the parent reader, or None if it is not set.

setParent(parent)

Set the parent reader, which the events are read from.

xml.sax.saxutils.prepare_input_source(source, base='')

این تابع یک منبع ورودی و یک URL پایه اختیاری می‌گیرد و یک شیء InputSource کاملاً حل‌شده و آماده برای خواندن برمی‌گرداند. منبع ورودی می‌تواند به‌صورت یک رشته، یک شیء شبه‌پرونده، یا یک شیء InputSource داده شود؛ پارسرها از این تابع برای پیاده‌سازی آرگومان چندریختی source در متد parse() خود استفاده می‌کنند.