اشیای 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)¶

پارسر را برای تجزیه source، یک نمونه از InputSource، آماده کنید. این متد توسط parse() قبل از تغذیه داده‌ها فراخوانی می‌شود. پیاده‌سازی پارسر باید این متد را بازنویسی کند؛ پیاده‌سازی پیش‌فرض 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) همه ویژگی‌ها را بازمی‌گرداند.