xml.sax.xmlreader --- رابط برای پارسرهای XML

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

پارسرهای SAX رابط XMLReader را پیاده‌سازی می‌کنند. آن‌ها در یک ماژول پایتون پیاده‌سازی شده‌اند که باید تابع create_parser() را ارائه کند. این تابع توسط xml.sax.make_parser() بدون آرگومان فراخوانی می‌شود تا یک شیء پارسر جدید ایجاد شود.

class xml.sax.xmlreader.XMLReader

کلاس پایه‌ای که پارسرهای SAX می‌توانند آن را به ارث ببرند.

class xml.sax.xmlreader.IncrementalParser

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

هنگامی که پارسر نمونه‌سازی می‌شود، بلافاصله آماده‌ی آغاز پذیرش داده از متد feed است. پس از پایان یافتن تجزیه با فراخوانی close، باید متد reset فراخوانی شود تا پارسر آماده‌ی پذیرش داده‌های جدید، چه از feed و چه با استفاده از متد parse، شود.

توجه داشته باشید که این متدها نباید در حین تجزیه فراخوانی شوند، یعنی پس از فراخوانی parse و پیش از بازگشت آن.

به‌طور پیش‌فرض، این کلاس همچنین برای سهولت کار نویسندگان راه‌انداز SAX 2.0، متد parse رابط XMLReader را با استفاده از متدهای feed، close و reset رابط IncrementalParser پیاده‌سازی می‌کند.

class xml.sax.xmlreader.Locator

رابطی برای مرتبط کردن یک رویداد SAX با موقعیت سند. یک شیء مکان‌یاب (locator) فقط در حین فراخوانی متدهای DocumentHandler نتایج معتبر برمی‌گرداند؛ در هر زمان دیگری، نتایج غیرقابل پیش‌بینی خواهند بود. اگر اطلاعات در دسترس نباشد، متدها ممکن است None را برگردانند.

class xml.sax.xmlreader.InputSource(system_id=None)

کپسوله‌سازی اطلاعات مورد نیاز XMLReader برای خواندن موجودیت‌ها.

این کلاس ممکن است شامل اطلاعاتی درباره شناسه‌ی عمومی، شناسه‌ی سیستمی، جریان بایت (احتمالاً همراه با اطلاعات کدگذاری نویسه) و/یا جریان نویسه‌ی یک موجودیت باشد.

برنامه‌های کاربردی اشیایی از این کلاس را برای استفاده در متد XMLReader.parse() و برای بازگشت از EntityResolver.resolveEntity ایجاد می‌کنند.

یک InputSource به برنامه تعلق دارد؛ XMLReader اجازه ندارد اشیای InputSource ارسال‌شده از برنامه به آن را تغییر دهد، اگرچه می‌تواند کپی‌هایی بسازد و آن‌ها را تغییر دهد.

class xml.sax.xmlreader.AttributesImpl(attrs)

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

class xml.sax.xmlreader.AttributesNSImpl(attrs, qnames)

گونه‌ای از AttributesImpl که از فضای نام آگاه است و به startElementNS() پاس داده خواهد شد. این کلاس از AttributesImpl مشتق شده است، اما نام ویژگی‌ها را به‌صورت دوتایی‌هایی (two-tuples) از namespaceURI و localname می‌شناسد. علاوه بر این، تعدادی متد فراهم می‌کند که انتظار دریافت نام‌های کامل را دارند، همان‌گونه که در سند اصلی ظاهر می‌شوند. این کلاس رابط AttributesNS را پیاده‌سازی می‌کند (به بخش رابط AttributesNS مراجعه کنید).

اشیای XMLReader

رابط XMLReader از متدهای زیر پشتیبانی می‌کند:

XMLReader.parse(source)

یک منبع ورودی را پردازش می‌کند و رویدادهای SAX تولید می‌کند. شیء source می‌تواند یک شناسه سیستم (رشته‌ای که منبع ورودی را شناسایی می‌کند — معمولاً یک نام پرونده یا URL)، یک شیء pathlib.Path یا path-like، یا یک شیء InputSource باشد. هنگامی که parse() بازمی‌گردد، ورودی به‌طور کامل پردازش می‌شود و می‌توان شیء پارسر را دور انداخت یا بازنشانی کرد.

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

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

XMLReader.getContentHandler()

ContentHandler فعلی را برمی‌گرداند.

XMLReader.setContentHandler(handler)

ContentHandler جاری را تنظیم کنید. اگر هیچ ContentHandler تنظیم نشده باشد، رویدادهای محتوا دور ریخته می‌شوند.

XMLReader.getDTDHandler()

DTDHandler جاری را برمی‌گرداند.

XMLReader.setDTDHandler(handler)

DTDHandler جاری را تنظیم می‌کند. اگر هیچ DTDHandler تنظیم‌نشده باشد، رویدادهای DTD نادیده گرفته می‌شوند.

XMLReader.getEntityResolver()

EntityResolver جاری را برمی‌گرداند.

XMLReader.setEntityResolver(handler)

EntityResolver فعلی را تنظیم کنید. اگر هیچ EntityResolver تنظیم نشده باشد، تلاش برای حل یک موجودیت خارجی منجر به باز کردن شناسه سیستم آن موجودیت می‌شود و اگر در دسترس نباشد، شکست می‌خورد.

XMLReader.getErrorHandler()

ErrorHandler فعلی را برمی‌گرداند.

XMLReader.setErrorHandler(handler)

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

XMLReader.setLocale(locale)

به یک برنامه اجازه می‌دهد تنظیمات locale را برای خطاها و هشدارها تنظیم کند.

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

XMLReader.getFeature(featurename)

تنظیم فعلی قابلیت featurename را برمی‌گرداند. اگر قابلیت شناسایی نشود، استثنای SAXNotRecognizedException پرتاب می‌شود. نام قابلیت‌های شناخته‌شده در ماژول xml.sax.handler فهرست شده‌اند.

XMLReader.setFeature(featurename, value)

featurename را روی value تنظیم کنید. اگر ویژگی شناسایی نشود، SAXNotRecognizedException پرتاب می‌شود. اگر ویژگی یا تنظیم آن توسط پارسر پشتیبانی نشود، SAXNotSupportedException پرتاب می‌شود.

XMLReader.getProperty(propertyname)

تنظیم فعلی برای خصوصیت propertyname را برمی‌گرداند. اگر خصوصیت شناسایی نشود، یک SAXNotRecognizedException پرتاب می‌شود. نام خصوصیت‌های شناخته‌شده در ماژول xml.sax.handler فهرست شده‌اند.

XMLReader.setProperty(propertyname, value)

propertyname را روی value تنظیم کنید. اگر ویژگی شناخته نشود، SAXNotRecognizedException پرتاب می‌شود. اگر ویژگی یا تنظیم آن توسط پارسر پشتیبانی نشود، SAXNotSupportedException پرتاب می‌شود.

اشیای IncrementalParser

نمونه‌های IncrementalParser متدهای اضافی زیر را ارائه می‌دهند:

IncrementalParser.feed(data)

تکه‌ای از data را پردازش می‌کند.

IncrementalParser.close()

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

IncrementalParser.prepareParser(source)

Prepare the parser for parsing source, an InputSource instance. It is called by parse() before feeding the data. The parser implementation must override this method; the default implementation raises NotImplementedError.

IncrementalParser.reset()

این متد پس از فراخوانی close فراخوانی می‌شود تا پارسر بازنشانی شود و برای تجزیه اسناد جدید آماده شود. نتایج فراخوانی parse یا feed پس از close بدون فراخوانی reset تعریف‌نشده است.

اشیای Locator

نمونه‌های Locator این متدها را ارائه می‌دهند:

Locator.getColumnNumber()

شماره ستونی را که رویداد جاری در آن آغاز می‌شود، برمی‌گرداند.

Locator.getLineNumber()

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

Locator.getPublicId()

شناسه عمومی رویداد جاری را برمی‌گرداند.

Locator.getSystemId()

شناسه سیستمی رویداد جاری را برمی‌گرداند.

اشیاء InputSource

InputSource.setPublicId(id)

شناسه عمومی این InputSource را تنظیم می‌کند.

InputSource.getPublicId()

شناسه عمومی این InputSource را برمی‌گرداند.

InputSource.setSystemId(id)

شناسه سیستم این InputSource را تنظیم می‌کند.

InputSource.getSystemId()

شناسه سیستمی این InputSource را بازمی‌گرداند.

InputSource.setEncoding(encoding)

کدگذاری نویسه‌ای این InputSource را تنظیم می‌کند.

کدگذاری باید رشته‌ای قابل‌قبول برای اعلامیه کدگذاری XML باشد (به بخش ۴.۳.۳ از توصیه‌نامه XML مراجعه کنید).

ویژگی کدگذاری InputSource در صورتی نادیده گرفته می‌شود که InputSource شامل یک جریان نویسه‌ای نیز باشد.

InputSource.getEncoding()

کدگذاری نویسه‌ای این InputSource را دریافت کنید.

InputSource.setByteStream(bytefile)

جریان بایت (یک binary file) را برای این منبع ورودی تنظیم کنید.

پارسر SAX در صورتی که یک جریان نویسه نیز مشخص شده باشد، این را نادیده می‌گیرد، اما ترجیحاً به‌جای باز کردن اتصال URI توسط خودش، از یک جریان بایت استفاده می‌کند.

اگر برنامه کدگذاری نویسه‌های جریان بایت را بداند، باید آن را با متد setEncoding تنظیم کند.

InputSource.getByteStream()

دریافت جریان بایت برای این منبع ورودی.

متد getEncoding کدگذاری نویسه‌ای این جریان بایت را برمی‌گرداند، یا اگر ناشناخته باشد None را.

InputSource.setCharacterStream(charfile)

جریان نویسه‌ای (یک text file) را برای این منبع ورودی تنظیم کنید.

اگر یک جریان نویسه‌ای مشخص شده باشد، پارسر SAX هر جریان بایتی را نادیده می‌گیرد و برای باز کردن اتصال URI به شناسه سیستم تلاش نمی‌کند.

InputSource.getCharacterStream()

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

رابط Attributes

اشیای Attributes بخشی از پروتکل نگاشت را پیاده‌سازی می‌کنند، از جمله متدهای copy()، get()، __contains__()، items()، keys() و values(). متدهای زیر نیز ارائه شده‌اند:

Attributes.getLength()

تعداد ویژگی‌ها را برمی‌گرداند.

Attributes.getNames()

نام ویژگی‌ها را برمی‌گرداند.

Attributes.getType(name)

نوع ویژگی name را برمی‌گرداند، که معمولاً 'CDATA' است.

Attributes.getValue(name)

مقدار ویژگی name را برمی‌گرداند.

رابط AttributesNS

این رابط، زیرنوعی از رابط Attributes است (بخش رابط Attributes را ببینید). همه‌ی متدهایی که آن رابط پشتیبانی می‌کند، در اشیای AttributesNS نیز در دسترس هستند.

متدهای زیر نیز در دسترس هستند:

AttributesNS.getValueByQName(name)

مقدار یک نام کامل را برمی‌گرداند.

AttributesNS.getNameByQName(name)

جفت (namespace, localname) را برای یک نام کامل برمی‌گرداند.

AttributesNS.getQNameByName(name)

بازگرداندن نام کامل برای یک جفت (namespace, localname).

AttributesNS.getQNames()

نام‌های کامل (qualified names) همه ویژگی‌ها را بازمی‌گرداند.