`xml.parsers.expat` --- تجزیه سریع XML با استفاده از Expat¶

توجه

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

ماژول xml.parsers.expat یک رابط پایتون برای پارسر XML بدون اعتبارسنجی Expat است. این ماژول یک نوع توسعه‌ای واحد، xmlparser، ارائه می‌کند که وضعیت فعلی یک پارسر XML را نشان می‌دهد. پس از ایجاد یک شیء xmlparser، می‌توان ویژگی‌های مختلف آن شیء را به توابع هندلر اختصاص داد. سپس هنگامی که یک سند XML به پارسر داده می‌شود، توابع هندلر برای داده‌های نویسه‌ای و نمادگذاری‌های درون سند XML فراخوانی می‌شوند.

این ماژول از ماژول pyexpat برای فراهم کردن دسترسی به پارسرٔ Expat استفاده می‌کند. استفاده‌ی مستقیم از ماژول pyexpat منسوخ شده است.

This module provides the following exception, type object and data items:

exception xml.parsers.expat.ExpatError¶: استثنایی که وقتی Expat خطایی را گزارش می‌دهد، پرتاب می‌شود. برای اطلاعات بیشتر در مورد تفسیر خطاهای Expat، بخش استثناهای ExpatError را ببینید.

exception xml.parsers.expat.error¶: نام مستعار برای ExpatError.

xml.parsers.expat.XMLParserType¶: نوع مقادیر بازگشتی تابع ParserCreate().

xml.parsers.expat.EXPAT_VERSION¶: The version string of the Expat library loaded by the interpreter, like 'expat_2.8.4'.

xml.parsers.expat.version_info¶: The version of the Expat library loaded by the interpreter, as a tuple of three integers: major, minor and micro version.

xml.parsers.expat.features¶: The list of the features with which the loaded Expat library was compiled, as (name, value) pairs. The value is only meaningful for features which have one, like 'XML_CONTEXT_BYTES' or the default protection limits 'XML_BLAP_ACT_THRES' and 'XML_AT_MAX_AMP'; for other features, like 'XML_DTD' and 'XML_NS', the value is 0 and only the presence of the name is significant.

ماژول xml.parsers.expat شامل دو تابع است:

xml.parsers.expat.ErrorString(errno)¶: یک رشته توضیحی برای شماره خطای داده‌شده errno برمی‌گرداند.

xml.parsers.expat.ParserCreate(encoding=None, namespace_separator=None, intern=None)¶

یک شیء xmlparser جدید ایجاد می‌کند و برمی‌گرداند. encoding، در صورت مشخص بودن، باید رشته‌ای باشد که نام کدگذاری مورد استفاده در داده‌های XML را بیان می‌کند. Expat به اندازه‌ی پایتون از کدگذاری‌ها پشتیبانی نمی‌کند و مجموعه کدگذاری‌های آن قابل گسترش نیست؛ از UTF-8، UTF-16، ISO-8859-1 (Latin1) و ASCII پشتیبانی می‌کند. اگر encoding [1] داده شود، کدگذاری ضمنی یا صریح سند را نادیده می‌گیرد.

پارسرهای ایجادشده از طریق ParserCreate()، پارسرهای «ریشه» نامیده می‌شوند، از این جهت که هیچ پارسر والدی به آن‌ها متصل نیست. پارسرهای غیرریشه‌ای به‌وسیله‌ی parser.ExternalEntityParserCreate ایجاد می‌شوند.

Expat می‌تواند به‌صورت اختیاری پردازش فضای نام XML را برای شما انجام دهد؛ این قابلیت با ارائه یک مقدار برای namespace_separator فعال می‌شود. این مقدار باید رشته‌ای با یک نویسه باشد؛ اگر رشته طول غیرمجازی داشته باشد، یک ValueError پرتاب خواهد شد (None معادل حذف در نظر گرفته می‌شود). هنگامی که پردازش فضای نام فعال باشد، نام نوع المان‌ها و نام صفت‌هایی که به یک فضای نام تعلق دارند، بسط داده خواهند شد. نام المانی که به هندلرهای المان StartElementHandler و EndElementHandler ارسال می‌شود، برابر با الحاق URI فضای نام، نویسه‌ی جداکننده‌ی فضای نام و بخش محلی نام خواهد بود. اگر جداکننده‌ی فضای نام یک بایت صفر (chr(0)) باشد، URI فضای نام و بخش محلی بدون هیچ جداکننده‌ای به هم الحاق خواهند شد.

برای مثال، اگر namespace_separator برابر با یک نویسه‌ی فاصله (' ') تنظیم شده باشد و سند زیر تجزیه شود:

<?xml version="1.0"?>
<root xmlns    = "http://default-namespace.org/"
      xmlns:py = "http://www.python.org/ns/">
  <py:elem1 />
  <elem2 xmlns="" />
</root>

StartElementHandler رشته‌های زیر را برای هر عنصر دریافت خواهد کرد:

http://default-namespace.org/ root
http://www.python.org/ns/ elem1
elem2

intern, if given, must be a dictionary. It is used to intern the names of elements and attributes, and is available as the intern attribute. By default a new empty dictionary is created for every parser.

به دلیل محدودیت‌هایی در کتابخانه Expat که pyexpat از آن استفاده می‌کند، نمونه‌ی xmlparser برگردانده‌شده فقط می‌تواند برای تجزیه‌ی یک سند XML استفاده شود. برای فراهم کردن نمونه‌های پارسر یکتا، ParserCreate را برای هر سند فراخوانی کنید.

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

پارسرٔ Expat XML: صفحه‌ی اصلی پروژه Expat.

اشیاء XMLParser¶

اشیای xmlparser متدهای زیر را دارند:

xmlparser.Parse(data[, isfinal])¶: Parses the contents of data, calling the appropriate handler functions to process the parsed data. data can be a bytes-like object or a string. If it is a string, the encoding declaration in the XML data is ignored, and the data is parsed as already decoded text. isfinal must be true on the final call to this method; it allows the parsing of a single file in fragments, not the submission of multiple files. data can be empty at any time.

xmlparser.ParseFile(file)¶: Parse XML data reading from the object file. file only needs to provide the read(nbytes) method, which returns bytes, and an empty bytes object when there's no more data. Text files are not supported; use Parse() for data which is already decoded.

xmlparser.SetBase(base)¶: پایه‌ای را تنظیم می‌کند که برای حل URIهای نسبی در شناسه‌های سیستم در اعلان‌ها استفاده می‌شود. حل شناسه‌های نسبی بر عهده برنامه گذاشته شده است: این مقدار به‌عنوان آرگومان base به توابع ExternalEntityRefHandler()، NotationDeclHandler() و UnparsedEntityDeclHandler() ارسال می‌شود.

xmlparser.GetBase()¶: رشته‌ای شامل پایه‌ی تنظیم‌شده توسط فراخوانی پیشین SetBase()، یا در صورتی که SetBase() فراخوانی نشده باشد، None برمی‌گرداند.

xmlparser.GetInputContext()¶: Returns the input data which generated the current event as a bytes object. The data is in the encoding of the entity which contains the text. It extends to the end of the currently buffered input, therefore it can contain also the data of the following events, and if the event was generated by a large amount of text, not all of it may be available. When called while an event handler is not active, the return value is None.

xmlparser.ExternalEntityParserCreate(context[, encoding])¶: یک پارسر «فرزند» ایجاد کنید که می‌توان از آن برای تجزیه‌ی یک موجودیت تجزیه‌شده‌ی خارجی که محتوای تجزیه‌شده توسط پارسر والد به آن ارجاع می‌دهد، استفاده کرد. پارامتر context باید رشته‌ای باشد که به تابع هندلر ExternalEntityRefHandler()، که در ادامه توضیح داده شده است، ارسال می‌شود. پارسر فرزند با ordered_attributes و specified_attributes که به مقادیر این پارسر تنظیم شده‌اند، ایجاد می‌شود.

xmlparser.SetParamEntityParsing(flag)¶: تجزیه‌ی موجودیت‌های پارامتری (از جمله زیرمجموعه‌ی خارجی DTD) را کنترل می‌کند. مقادیر ممکن برای flag عبارتند از XML_PARAM_ENTITY_PARSING_NEVER، XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE و XML_PARAM_ENTITY_PARSING_ALWAYS. در صورتی که تنظیم پرچم موفقیت‌آمیز بود، true را برمی‌گرداند.

xmlparser.UseForeignDTD([flag])¶

فراخوانی این متد با یک مقدار درست برای flag (پیش‌فرض) باعث می‌شود Expat ExternalEntityRefHandler را با None برای تمام آرگومان‌ها فراخوانی کند تا امکان بارگذاری یک DTD جایگزین فراهم شود. اگر سند حاوی اعلان نوع سند نباشد، ExternalEntityRefHandler همچنان فراخوانی خواهد شد، اما StartDoctypeDeclHandler و EndDoctypeDeclHandler فراخوانی نخواهند شد.

ارسال یک مقدار نادرست برای flag، فراخوانی پیشین را که مقدار درست ارسال کرده است لغو می‌کند، اما در غیر این صورت تأثیری ندارد.

این متد تنها می‌تواند پیش از فراخوانی متدهای Parse() یا ParseFile() فراخوانی شود؛ فراخوانی آن پس از فراخوانی هر یک از آن‌ها باعث پرتاب ExpatError با ویژگی code تنظیم‌شده به errors.codes[errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING] می‌شود.

xmlparser.SetReparseDeferralEnabled(enabled)¶

هشدار

فراخوانی SetReparseDeferralEnabled(False) پیامدهای امنیتی دارد، همان‌طور که در ادامه شرح داده شده است؛ لطفاً پیش از استفاده از متد SetReparseDeferralEnabled مطمئن شوید که این پیامدها را درک می‌کنید.

Expat 2.6.0 یک سازوکار امنیتی به نام «تعویق تجزیه‌ی مجدد» (reparse deferral) معرفی کرد که در آن به جای ایجاد منع سرویس از طریق ران‌تایم درجه‌ی دوم ناشی از تجزیه‌ی مجدد توکن‌های بزرگ، تجزیه‌ی مجدد توکن‌های ناتمام اکنون به‌طور پیش‌فرض تا دریافت مقدار کافی ورودی به تعویق می‌افتد. به دلیل این تأخیر، ممکن است هندلرهای ثبت‌شده — بسته به اندازه‌ی تکه‌های ورودی ارسال‌شده به Expat — دیگر بلافاصله پس از ارسال ورودی جدید به پارسر فراخوانی نشوند. در مواردی که بازخورد فوری و بر عهده گرفتن مسئولیت محافظت در برابر منع سرویس ناشی از توکن‌های بزرگ هر دو مطلوب باشند، فراخوانی SetReparseDeferralEnabled(False) تعویق تجزیه‌ی مجدد را برای نمونه‌ی جاری پارسر Expat، به‌طور موقت یا به‌طور کامل غیرفعال می‌کند. فراخوانی SetReparseDeferralEnabled(True) امکان فعال‌سازی مجدد تعویق تجزیه‌ی مجدد را فراهم می‌کند.

توجه داشته باشید که SetReparseDeferralEnabled() به‌عنوان یک اصلاحیه امنیتی به برخی انتشارهای پیشین CPython بک‌پورت شده است. اگر در کدی استفاده می‌شود که روی نسخه‌های مختلف پایتون اجرا می‌شود، با استفاده از hasattr() دسترس‌پذیری SetReparseDeferralEnabled() را بررسی کنید.

اضافه شده در نسخه‌ی 3.13.

xmlparser.GetReparseDeferralEnabled()¶: برمی‌گرداند که آیا تعویق تجزیه مجدد (reparse deferral) در حال حاضر برای نمونه پارسر Expat داده‌شده فعال است یا خیر.

اضافه شده در نسخه‌ی 3.13.

اشیای xmlparser دارای متدهای زیر برای تنظیم حفاظت‌ها در برابر برخی آسیب‌پذیری‌های رایج XML هستند.

xmlparser.SetBillionLaughsAttackProtectionActivationThreshold(threshold, /)¶

تعداد بایت‌های خروجی مورد نیاز برای فعال‌سازی محافظت در برابر حملات billion laughs را تنظیم می‌کند.

تعداد بایت‌های خروجی، افزایش حجم ناشی از بسط موجودیت (entity expansion) و خواندن پرونده‌های DTD را شامل می‌شود.

اشیای پارسر معمولاً دارای آستانه فعال‌سازی حفاظت ۸ MiB هستند، اما مقدار پیش‌فرض واقعی به کتابخانه زیربنایی Expat بستگی دارد.

اگر این متد را روی یک پارسر non-root فراخوانی کنید، یک ExpatError پرتاب می‌شود. نباید از lineno و offset مربوطه استفاده کنید، زیرا ممکن است معنای خاصی نداشته باشند.

توجه

آستانه‌های فعال‌سازی کمتر از ۴ MiB، پشتیبانی از بار DITA 1.3 را مختل می‌کنند و بنابراین توصیه نمی‌شوند.

اضافه شده در نسخه‌ی 3.14.6.

xmlparser.SetBillionLaughsAttackProtectionMaximumAmplification(max_factor, /)¶

حداکثر ضریب تقویت قابل‌تحمل را برای محافظت در برابر حملات billion laughs تنظیم می‌کند.

ضریب تقویت هنگام تجزیه به‌صورت (direct + indirect) / direct محاسبه می‌شود، که در آن direct تعداد بایت‌های خوانده‌شده از سند اصلی در حین تجزیه و indirect تعداد بایت‌های اضافه‌شده در اثر بسط موجودیت‌ها و خواندن پرونده‌های DTD خارجی است.

مقدار max_factor باید یک مقدار float غیر NaN و بزرگ‌تر یا مساوی ۱.۰ باشد. در عمل، با پرونده‌های کوچک بی‌خطر، تقویت‌های اوج با ضریب ۱۵۰۰۰ برای کل بار و با ضریب ۳۰۰۰۰ در میانه‌ی تجزیه مشاهده شده‌اند. به‌ویژه، آستانه فعال‌سازی باید با دقت انتخاب شود تا از موارد مثبت کاذب جلوگیری شود.

اشیای پارسر معمولاً دارای حداکثر ضریب تقویت ۱۰۰ هستند، اما مقدار پیش‌فرض واقعی به کتابخانه زیرین Expat بستگی دارد.

اگر این متد بر روی یک پارسر non-root فراخوانی شود یا max_factor خارج از محدوده معتبر باشد، یک استثنای ExpatError پرتاب می‌شود. نباید از lineno و offset متناظر استفاده شود، زیرا ممکن است معنای خاصی نداشته باشند.

توجه

حداکثر ضریب تقویت تنها در صورتی در نظر گرفته می‌شود که از آستانه‌ای که می‌توان آن را با SetBillionLaughsAttackProtectionActivationThreshold() تنظیم کرد، عبور شود.

اضافه شده در نسخه‌ی 3.14.6.

xmlparser.SetAllocTrackerActivationThreshold(threshold, /)¶

تعداد بایت‌های تخصیص‌یافته از حافظه پویا را که برای فعال‌سازی حفاظت در برابر استفاده نامتناسب از RAM لازم است، تنظیم می‌کند.

اشیای پارسر معمولاً آستانه فعال‌سازی تخصیص ۶۴ MiB دارند، اما مقدار پیش‌فرض واقعی به کتابخانه Expat زیرین بستگی دارد.

اگر این متد را روی یک پارسر non-root فراخوانی کنید، یک ExpatError پرتاب می‌شود. نباید از lineno و offset مربوطه استفاده کنید، زیرا ممکن است معنای خاصی نداشته باشند.

اضافه شده در نسخه‌ی 3.14.1.

xmlparser.SetAllocTrackerMaximumAmplification(max_factor, /)¶

حداکثر ضریب تقویت بین ورودی مستقیم و بایت‌های حافظه پویای تخصیص‌یافته را تنظیم می‌کند.

ضریب تقویت در حین تجزیه به‌صورت allocated / direct محاسبه می‌شود، که در آن direct تعداد بایت‌های خوانده‌شده از سند اصلی در حین تجزیه و allocated تعداد بایت‌های حافظه پویای تخصیص‌داده‌شده در سلسله‌مراتب پارسر است.

مقدار max_factor باید مقداری از نوع float، غیر NaN و بزرگ‌تر یا مساوی 1.0 باشد. در عمل، حتی با پرونده‌های بی‌خطر نیز می‌توان ضرایب تقویت بزرگ‌تر از 100.0 را در نزدیکی شروع تجزیه مشاهده کرد. به‌ویژه، آستانه فعال‌سازی باید با دقت انتخاب شود تا از مثبت‌های کاذب اجتناب شود.

اشیای پارسر معمولاً دارای حداکثر ضریب تقویت ۱۰۰ هستند، اما مقدار پیش‌فرض واقعی به کتابخانه زیرین Expat بستگی دارد.

اگر این متد بر روی یک پارسر non-root فراخوانی شود یا max_factor خارج از محدوده معتبر باشد، یک استثنای ExpatError پرتاب می‌شود. نباید از lineno و offset متناظر استفاده شود، زیرا ممکن است معنای خاصی نداشته باشند.

توجه

حداکثر ضریب تقویت تنها در صورتی در نظر گرفته می‌شود که از آستانه‌ای که با SetAllocTrackerActivationThreshold() قابل تنظیم است، فراتر رود.

اضافه شده در نسخه‌ی 3.14.1.

اشیای xmlparser ویژگی‌های زیر را دارند:

xmlparser.buffer_size¶: اندازه‌ی بافری که هنگامی که buffer_text برابر true باشد استفاده می‌شود. می‌توان اندازه‌ی جدید بافر را با انتساب یک مقدار عدد صحیح جدید به این ویژگی تنظیم کرد. هنگامی که اندازه تغییر کند، بافر تخلیه خواهد شد.

xmlparser.buffer_text¶: تنظیم این ویژگی روی مقدار درست باعث می‌شود شیء xmlparser محتوای متنی بازگردانده‌شده توسط Expat را در بافرذخیره کند تا تا حد امکان از فراخوانی‌های مکرر کال‌بک CharacterDataHandler() اجتناب شود. این کار می‌تواند عملکرد را به‌طور قابل‌توجهی بهبود بخشد، زیرا Expat معمولاً داده‌های نویسه‌ای را در هر پایان خط به تکه‌ها می‌شکند. این ویژگی به‌طور پیش‌فرض نادرست است و می‌تواند در هر زمانی تغییر کند. توجه داشته باشید که وقتی این ویژگی نادرست است، داده‌هایی که حاوی خط جدید نیستند نیز ممکن است بخش‌بندی (chunking) شوند.

xmlparser.buffer_used¶: اگر buffer_text فعال باشد، تعداد بایت‌های ذخیره‌شده در بافر است. این بایت‌ها بیانگر متن کدگذاری‌شده با UTF-8 هستند. این ویژگی وقتی buffer_text نادرست باشد، تفسیر معناداری ندارد.

xmlparser.ordered_attributes¶: تنظیم این ویژگی روی یک عدد صحیح غیرصفر باعث می‌شود صفت‌ها به‌جای یک دیکشنری، به‌صورت یک فهرست گزارش شوند. صفت‌ها به ترتیب موجود در متن سند ارائه می‌شوند. برای هر صفت، دو آیتم از فهرست ارائه می‌شوند: نام صفت و مقدار صفت. (نسخه‌های قدیمی‌تر این ماژول نیز از همین قالب استفاده می‌کردند.) به‌طور پیش‌فرض، این ویژگی نادرست است؛ می‌توان آن را در هر زمانی تغییر داد.

xmlparser.specified_attributes¶: اگر روی یک عدد صحیح غیرصفر تنظیم شود، پارسر فقط آن ویژگی‌هایی را گزارش می‌کند که در نمونه سند مشخص شده‌اند و نه آن‌هایی که از اعلامیه‌های ویژگی به دست آمده‌اند. برنامه‌هایی که این ویژگی را تنظیم می‌کنند باید به‌ویژه مراقب باشند که از اطلاعات تکمیلی موجود در اعلامیه‌ها، در صورت نیاز، برای رعایت استانداردهای رفتار پردازنده‌های XML استفاده کنند. به‌طور پیش‌فرض، این ویژگی false است؛ می‌توان آن را در هر زمان تغییر داد.

xmlparser.intern¶: The dictionary used to intern the names of elements and attributes. It is either the dictionary passed as the intern argument of ParserCreate(), or a new dictionary created for this parser.

xmlparser.namespace_prefixes¶: If set to a true value, and namespace processing is enabled, the namespace prefix is reported as the third part of the expanded name, separated by the namespace separator. Names which have no prefix are not affected. By default, this attribute is false; it may be changed at any time.

ویژگی‌های زیر شامل مقادیری مربوط به آخرین خطایی هستند که یک شیء xmlparser با آن مواجه شده است، و تنها زمانی مقادیر صحیح خواهند داشت که یک فراخوانی Parse() یا ParseFile() یک استثنا xml.parsers.expat.ExpatError را پرتاب کرده باشد.

xmlparser.ErrorByteIndex¶: اندیس بایتی که خطا در آن رخ داد.

xmlparser.ErrorCode¶: کد عددی که مشکل را مشخص می‌کند. این مقدار را می‌توان به تابع ErrorString() ارسال کرد یا با یکی از ثابت‌های تعریف‌شده در شیء errors مقایسه کرد.

xmlparser.ErrorColumnNumber¶: شماره‌ی ستونی که خطا در آن رخ داده است.

xmlparser.ErrorLineNumber¶: شماره‌ی سطری که در آن خطایی رخ داده است.

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

xmlparser.CurrentByteIndex¶: اندیس بایت جاری در ورودی پارسر.

xmlparser.CurrentColumnNumber¶: شماره‌ی ستون جاری در ورودی پارسر.

xmlparser.CurrentLineNumber¶: شماره خط جاری در ورودی پارسر .

در اینجا فهرستی از هندلرها که می‌توان آن‌ها را تنظیم کرد آمده است. برای تنظیم یک هندلر روی یک شیء xmlparser به نام o، از o.handlername = func استفاده کنید. handlername باید از فهرست زیر انتخاب شود، و func باید یک شیء فراخوانی‌پذیر باشد که تعداد صحیح آرگومان‌ها را بپذیرد. همه آرگومان‌ها رشته هستند، مگر آنکه خلاف آن ذکر شده باشد.

xmlparser.XmlDeclHandler(version, encoding, standalone)¶: Called when the XML declaration is parsed. The XML declaration is the (optional) declaration of the applicable version of the XML recommendation, the encoding of the document text, and an optional "standalone" declaration. version and encoding will be strings, and standalone will be 1 if the document is declared standalone, 0 if it is declared not to be standalone, or -1 if the standalone clause was omitted.

xmlparser.StartDoctypeDeclHandler(doctypeName, systemId, publicId, has_internal_subset)¶: Called when Expat begins parsing the document type declaration (<!DOCTYPE ...). The doctypeName is provided exactly as presented. The systemId and publicId parameters give the system and public identifiers if specified, or None if omitted. has_internal_subset will be true if the document contains an internal document declaration subset.

xmlparser.EndDoctypeDeclHandler()¶: Called when Expat is done parsing the document type declaration.

xmlparser.ElementDeclHandler(name, model)¶: برای هر اعلامیه‌ی نوع عنصر یک بار فراخوانی می‌شود. name نام نوع عنصر است، و model نمایشی از مدل محتوا است.

xmlparser.AttlistDeclHandler(elname, attname, type, default, required)¶: Called for each declared attribute for an element type. If an attribute list declaration declares three attributes, this handler is called three times, once for each attribute. elname is the name of the element to which the declaration applies and attname is the name of the attribute declared. The The attribute type is a string passed as type: 'CDATA', 'ID', 'IDREF', 'IDREFS', 'ENTITY', 'ENTITIES', 'NMTOKEN' or 'NMTOKENS', an enumeration like '(x|y)', or a notation list like 'NOTATION(n1|n2)'. default gives the default value for the attribute used when the attribute is not specified by the document instance, or None if there is no default value (#IMPLIED values). If the attribute is required to be given in the document instance, required will be true.

xmlparser.StartElementHandler(name, attributes)¶: برای آغاز هر عنصر فراخوانی می‌شود. name یک رشته حاوی نام عنصر است، و attributes صفات عنصر است. اگر ordered_attributes برابر true باشد، این یک فهرست است (برای توضیح کامل ordered_attributes را ببینید). در غیر این صورت، یک دیکشنری است که نام‌ها را به مقدارها نگاشت می‌کند.

xmlparser.EndElementHandler(name)¶: برای پایان هر عنصر فراخوانی می‌شود.

xmlparser.ProcessingInstructionHandler(target, data)¶: برای هر دستور پردازشی فراخوانی می‌شود.

xmlparser.CharacterDataHandler(data)¶: برای داده‌های نویسه‌ای فراخوانی می‌شود. این متد برای داده‌های نویسه‌ای عادی، محتوای علامت‌گذاری‌شده CDATA و فضای خالی قابل‌چشم‌پوشی فراخوانی خواهد شد. برنامه‌هایی که باید این حالت‌ها را از هم تشخیص دهند، می‌توانند از کال‌بک‌های StartCdataSectionHandler، EndCdataSectionHandler و ElementDeclHandler برای جمع‌آوری اطلاعات مورد نیاز استفاده کنند. توجه داشته باشید که داده‌های نویسه‌ای ممکن است حتی در صورت کوتاه بودن بخش‌بندی (chunking) شوند و بنابراین ممکن است بیش از یک فراخوانی برای CharacterDataHandler() دریافت کنید. برای جلوگیری از این موضوع، ویژگی نمونه buffer_text را روی True تنظیم کنید.

xmlparser.UnparsedEntityDeclHandler(entityName, base, systemId, publicId, notationName)¶: Called for unparsed (NDATA) entity declarations. If this handler is not set, such declarations are reported by EntityDeclHandler, which is preferred for new code. (The underlying function in the Expat library has been declared obsolete.)

xmlparser.EntityDeclHandler(entityName, is_parameter_entity, value, base, systemId, publicId, notationName)¶: Called for all entity declarations. For parameter and internal entities, value will be a string giving the declared contents of the entity; this will be None for external entities. The notationName parameter will be None for parsed entities, and the name of the notation for unparsed entities. is_parameter_entity will be true if the entity is a parameter entity or false for general entities (most applications only need to be concerned with general entities).

xmlparser.NotationDeclHandler(notationName, base, systemId, publicId)¶: برای اعلان‌های نمادگذاری (notation declarations) فراخوانی می‌شود. notationName، base، systemId و publicId در صورت ارائه شدن، رشته هستند. اگر شناسه عمومی ذکر نشده باشد، publicId برابر None خواهد بود.

xmlparser.StartNamespaceDeclHandler(prefix, uri)¶: هنگامی که یک عنصر شامل یک اعلان فضای نام باشد، فراخوانی می‌شود. اعلان‌های فضای نام پیش از فراخوانی StartElementHandler برای عنصری که اعلان‌ها بر روی آن قرار گرفته‌اند، پردازش می‌شوند.

xmlparser.EndNamespaceDeclHandler(prefix)¶: هنگامی که به برچسب پایانی المانی حاوی اعلام فضای نام می‌رسیم، فراخوانی می‌شود. این به ازای هر اعلام فضای نام روی المان یک بار فراخوانی می‌شود، با ترتیب معکوس ترتیبی که StartNamespaceDeclHandler برای نشان دادن آغاز محدوده‌ی هر اعلام فضای نام فراخوانی شده بود. فراخوانی‌های این هندلر پس از EndElementHandler متناظر برای پایان المان انجام می‌شوند.

xmlparser.CommentHandler(data)¶: برای کامنت‌ها فراخوانی می‌شود. data متن کامنت است، بدون '' انتهایی.

xmlparser.StartCdataSectionHandler()¶: در آغاز یک بخش CDATA فراخوانی می‌شود. برای آنکه بتوان آغاز و پایان سینتکسی بخش‌های CDATA را شناسایی کرد، به این مورد و EndCdataSectionHandler نیاز است.

xmlparser.EndCdataSectionHandler()¶: در پایان یک بخش CDATA فراخوانی می‌شود.

xmlparser.DefaultHandler(data)¶: برای هر نویسه‌ای در سند XML که هیچ هندلری قابل‌اعمالی برای آن مشخص نشده باشد، فراخوانی می‌شود. این به معنای نویسه‌هایی است که بخشی از ساختاری هستند که می‌تواند گزارش شود، اما هیچ هندلری برای آن تأمین نشده است.

xmlparser.DefaultHandlerExpand(data)¶: This is the same as the DefaultHandler, but doesn't inhibit expansion of internal entities. The entity reference will not be passed to the default handler.

xmlparser.NotStandaloneHandler()¶: اگر سند XML به‌عنوان یک سند مستقل اعلام نشده باشد، فراخوانی می‌شود. این حالت زمانی رخ می‌دهد که یک زیرمجموعه خارجی یا ارجاعی به یک موجودیت پارامتری وجود داشته باشد، اما در اعلامیه XML مقدار standalone روی yes تنظیم نشده باشد. اگر این هندلر 0 را برگرداند، پارسر یک خطای XML_ERROR_NOT_STANDALONE پرتاب خواهد کرد. اگر این هندلر تنظیم نشده باشد، پارسر برای این وضعیت هیچ استثنایی پرتاب نمی‌کند.

xmlparser.ExternalEntityRefHandler(context, base, systemId, publicId)¶

هشدار

پیاده‌سازی یک هندلر که به پرونده‌های محلی و/یا شبکه دسترسی دارد، ممکن است در صورتی که از xmlparser با محتوای XML ارائه‌شده توسط کاربر استفاده شود، آسیب‌پذیری در برابر حملات موجودیت خارجی ایجاد کند. لطفاً پیش از پیاده‌سازی این هندلر، مدل تهدید خود را در نظر بگیرید.

برای ارجاع‌ها به موجودیت‌های خارجی فراخوانی می‌شود. base پایه فعلی است که با فراخوانی پیشین SetBase() تنظیم شده است. شناسه‌های عمومی و سیستمی، systemId و publicId، اگر ارائه شده باشند، رشته هستند؛ اگر شناسه عمومی ارائه نشده باشد، publicId برابر None خواهد بود. مقدار context مبهم است و باید فقط همان‌طور که در ادامه توضیح داده شده است استفاده شود.

برای این که موجودیت‌های خارجی تجزیه شوند، این هندلر باید پیاده‌سازی شود. این هندلر مسئول ایجاد پارسر فرعی با استفاده از ExternalEntityParserCreate(context)، مقداردهی اولیه‌ی آن با کال‌بک‌های مناسب و تجزیه‌ی موجودیت است. این هندلر باید یک عدد صحیح برگرداند؛ اگر 0 برگرداند، پارسر خطای XML_ERROR_EXTERNAL_ENTITY_HANDLING را پرتاب خواهد کرد، در غیر این صورت تجزیه ادامه خواهد یافت.

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

xmlparser.SkippedEntityHandler(entityName, is_parameter_entity)¶: Called for entity references which are not expanded, because the parser did not read the declaration of the entity. This happens when the external DTD subset or an external parameter entity is not parsed. is_parameter_entity is true for a parameter entity and false for a general entity.

استثناهای ExpatError¶

استثناهای ExpatError تعدادی ویژگی جالب دارند:

ExpatError.code¶

شماره‌ی خطای داخلی Expat برای خطای مشخص. دیکشنری errors.messages این شماره‌های خطا را به پیام‌های خطای Expat نگاشت می‌کند. برای مثال:

from xml.parsers.expat import ParserCreate, ExpatError, errors

p = ParserCreate()
try:
    p.Parse(some_xml_document)
except ExpatError as err:
    print("Error:", errors.messages[err.code])

ماژول errors همچنین ثابت‌های پیام خطا و دیکشنری codes را ارائه می‌دهد که این پیام‌ها را به کدهای خطا نگاشت می‌کند، در زیر ببینید.

ExpatError.lineno¶: شماره‌ی سطری که خطا در آن تشخیص داده شد. اولین خط با شماره‌ی 1 شماره‌گذاری شده است.

ExpatError.offset¶: آفست نویسه‌ای در سطری که خطا در آن رخ داده است. شماره‌ی اولین ستون 0 است.

مثال¶

برنامه زیر ۳ هندلر تعریف می‌کند که فقط آرگومان‌های خود را چاپ می‌کنند.

import xml.parsers.expat

# 3 handler functions
def start_element(name, attrs):
    print('Start element:', name, attrs)
def end_element(name):
    print('End element:', name)
def char_data(data):
    print('Character data:', repr(data))

p = xml.parsers.expat.ParserCreate()

p.StartElementHandler = start_element
p.EndElementHandler = end_element
p.CharacterDataHandler = char_data

p.Parse("""<?xml version="1.0"?>
<parent id="top"><child1 name="paul">Text goes here</child1>
<child2 name="fred">More text</child2>
</parent>""", 1)

خروجی این برنامه:

Start element: parent {'id': 'top'}
Start element: child1 {'name': 'paul'}
Character data: 'Text goes here'
End element: child1
Character data: '\n'
Start element: child2 {'name': 'fred'}
Character data: 'More text'
End element: child2
Character data: '\n'
End element: parent

توصیف‌های مدل محتوا¶

مدل‌های محتوا با استفاده از تاپل‌های تودرتو توصیف می‌شوند. هر تاپل شامل چهار مقدار است: نوع، کمیت‌گذار، نام، و یک تاپل از فرزندان. فرزندان صرفاً توصیف‌های اضافی مدل محتوا هستند.

مقادیر دو فیلد نخست، ثابت‌های تعریف‌شده در ماژول xml.parsers.expat.model هستند. این ثابت‌ها را می‌توان در دو گروه دسته‌بندی کرد: گروه نوع مدل و گروه کمیت‌گذار.

ثابت‌های گروه نوع مدل عبارتند از:

xml.parsers.expat.model.XML_CTYPE_ANY¶: برای عنصر نام‌گذاری‌شده با نام مدل، مدل محتوای ANY اعلام شده بود.

xml.parsers.expat.model.XML_CTYPE_CHOICE¶: عنصر نام‌دار امکان انتخاب از میان تعدادی گزینه را فراهم می‌کند؛ این برای مدل‌های محتوا مانند (A | B | C) استفاده می‌شود.

xml.parsers.expat.model.XML_CTYPE_EMPTY¶: عناصری که به‌صورت EMPTY اعلام شده‌اند، این نوع مدل را دارند.

xml.parsers.expat.model.XML_CTYPE_MIXED¶: The named element allows character data, optionally interspersed with the named children; this is used for content models such as (#PCDATA) and (#PCDATA | A | B)*.

xml.parsers.expat.model.XML_CTYPE_NAME¶: The model names a single element, as for A.

xml.parsers.expat.model.XML_CTYPE_SEQ¶: مدل‌هایی که یک رشته از مدل‌های متوالی را نشان می‌دهند، با این نوع مدل مشخص می‌شوند. این برای مدل‌هایی مانند (A, B, C) به کار می‌رود.

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

xml.parsers.expat.model.XML_CQUANT_NONE¶: هیچ تغییردهنده‌ای داده نشده است، بنابراین می‌تواند دقیقاً یک بار ظاهر شود، مانند A.

xml.parsers.expat.model.XML_CQUANT_OPT¶: مدل اختیاری است: می‌تواند یک بار ظاهر شود یا اصلاً ظاهر نشود، مانند A?.

xml.parsers.expat.model.XML_CQUANT_PLUS¶: مدل باید یک یا چند بار تکرار شود (مانند A+).

xml.parsers.expat.model.XML_CQUANT_REP¶: مدل باید صفر یا چند بار تکرار شود، مانند A*.

ثابت‌های خطای Expat¶

ثابت‌های زیر در ماژول xml.parsers.expat.errors ارائه شده‌اند. این ثابت‌ها برای تفسیر برخی از ویژگی‌های اشیای استثنای ExpatError که هنگام وقوع خطا پرتاب می‌شوند، مفید هستند. از آن‌جا که به دلایل سازگاری با نسخه‌های قدیمی، مقدار ثابت‌ها پیام خطا است، نه کد خطای عددی، این کار را با مقایسه‌ی ویژگی code آن با errors.codes[errors.XML_ERROR_CONSTANT_NAME] انجام دهید.

ماژول errors دارای ویژگی‌های زیر است:

xml.parsers.expat.errors.codes¶: یک دیکشنری که توضیحات رشته‌ای را به کدهای خطای آن‌ها نگاشت می‌کند.

اضافه شده در نسخه‌ی 3.2.

xml.parsers.expat.errors.messages¶: یک دیکشنری که کدهای خطای عددی را به توضیحات رشته‌ای آن‌ها نگاشت می‌کند.

اضافه شده در نسخه‌ی 3.2.

xml.parsers.expat.errors.XML_ERROR_ASYNC_ENTITY¶

xml.parsers.expat.errors.XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF¶: یک ارجاع به موجودیت در مقدار یک ویژگی، به‌جای یک موجودیت داخلی، به یک موجودیت خارجی اشاره داشت.

xml.parsers.expat.errors.XML_ERROR_BAD_CHAR_REF¶: یک ارجاع نویسه به نویسه‌ای اشاره می‌کرد که در XML غیرمجاز است (برای مثال، نویسه‌ی 0، یا '').

xml.parsers.expat.errors.XML_ERROR_BINARY_ENTITY_REF¶: یک ارجاع موجودیت (entity reference) به موجودیتی اشاره داشت که با یک نمادگذاری اعلام شده بود، بنابراین نمی‌توان آن را تجزیه (parse) کرد.

xml.parsers.expat.errors.XML_ERROR_DUPLICATE_ATTRIBUTE¶: یک ویژگی بیش از یک بار در یک برچسب شروع استفاده شده است.

xml.parsers.expat.errors.XML_ERROR_INCORRECT_ENCODING¶

xml.parsers.expat.errors.XML_ERROR_INVALID_TOKEN¶: هنگامی پرتاب می‌شود که نتوان یک بایت ورودی را به‌درستی به یک نویسه اختصاص داد؛ برای مثال، یک بایت NUL (با مقدار 0) در یک جریان ورودی UTF-8.

xml.parsers.expat.errors.XML_ERROR_JUNK_AFTER_DOC_ELEMENT¶: پس از عنصر سند، چیزی جز فضای سفید رخ داد.

xml.parsers.expat.errors.XML_ERROR_MISPLACED_XML_PI¶: یک اعلان XML در جایی غیر از ابتدای داده ورودی یافت شد.

xml.parsers.expat.errors.XML_ERROR_NO_ELEMENTS¶: The document contains no elements (XML requires all documents to contain exactly one top-level element).

xml.parsers.expat.errors.XML_ERROR_NO_MEMORY¶: Expat نتوانست حافظه را به‌صورت داخلی تخصیص دهد.

xml.parsers.expat.errors.XML_ERROR_PARAM_ENTITY_REF¶: ارجاعی به موجودیت پارامتری در جایی یافت شد که مجاز نبود.

xml.parsers.expat.errors.XML_ERROR_PARTIAL_CHAR¶: یک نویسه‌ی ناقص در ورودی یافت شد.

xml.parsers.expat.errors.XML_ERROR_RECURSIVE_ENTITY_REF¶: یک ارجاع موجودیت شامل ارجاع دیگری به همان موجودیت بود؛ احتمالاً از طریق نامی متفاوت، و احتمالاً به‌طور غیرمستقیم.

xml.parsers.expat.errors.XML_ERROR_SYNTAX¶: یک خطای سینتکسی نامشخص رخ داد.

xml.parsers.expat.errors.XML_ERROR_TAG_MISMATCH¶: یک برچسب پایان با داخلی‌ترین برچسب شروع باز مطابقت نداشت.

xml.parsers.expat.errors.XML_ERROR_UNCLOSED_TOKEN¶: توکنی (مانند برچسب شروع) پیش از پایان جریان یا برخورد با توکن بعدی بسته نشده بود.

xml.parsers.expat.errors.XML_ERROR_UNDEFINED_ENTITY¶: ارجاعی به یک موجودیت تعریف‌نشده داده شده است.

xml.parsers.expat.errors.XML_ERROR_UNKNOWN_ENCODING¶: کدگذاری سند توسط Expat پشتیبانی نمی‌شود.

xml.parsers.expat.errors.XML_ERROR_UNCLOSED_CDATA_SECTION¶: یک بخش نمادگذاری‌شده‌ی CDATA بسته نشده است.

xml.parsers.expat.errors.XML_ERROR_EXTERNAL_ENTITY_HANDLING¶

xml.parsers.expat.errors.XML_ERROR_NOT_STANDALONE¶: پارسر تشخیص داد که سند «مستقل» نیست، هرچند در اعلان XML خود را مستقل اعلام کرده بود، و NotStandaloneHandler تنظیم شده بود و 0 را برگرداند.

xml.parsers.expat.errors.XML_ERROR_UNEXPECTED_STATE¶

xml.parsers.expat.errors.XML_ERROR_ENTITY_DECLARED_IN_PE¶

xml.parsers.expat.errors.XML_ERROR_FEATURE_REQUIRES_XML_DTD¶: عملیاتی درخواست شد که نیاز دارد پشتیبانی DTD در Expat کامپایل‌شده باشد، اما Expat بدون پشتیبانی DTD پیکربندی شده است. این مورد هرگز نباید در ساخت استاندارد ماژول xml.parsers.expat گزارش شود.

xml.parsers.expat.errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING¶: تغییری در رفتار پس از شروع تجزیه درخواست شد که فقط پیش از شروع تجزیه می‌توان آن را تغییر داد. این مورد (در حال حاضر) فقط توسط UseForeignDTD() پرتاب می‌شود.

xml.parsers.expat.errors.XML_ERROR_UNBOUND_PREFIX¶: هنگامی که پردازش فضای نام فعال بود، یک پیشوند اعلام‌نشده یافت شد.

xml.parsers.expat.errors.XML_ERROR_UNDECLARING_PREFIX¶: سند تلاش کرد اعلامیه‌ی فضای نام مرتبط با یک پیشوند را حذف کند.

xml.parsers.expat.errors.XML_ERROR_INCOMPLETE_PE¶: یک موجودیت پارامتر (parameter entity) شامل نمادگذاری ناقص بود.

xml.parsers.expat.errors.XML_ERROR_XML_DECL¶: There was an error parsing the XML declaration.

xml.parsers.expat.errors.XML_ERROR_TEXT_DECL¶: هنگام تجزیه‌ی یک اعلامیه‌ی متنی در یک موجودیت خارجی، خطایی رخ داد.

xml.parsers.expat.errors.XML_ERROR_PUBLICID¶: نویسه‌هایی که مجاز نیستند، در شناسه عمومی یافت شدند.

xml.parsers.expat.errors.XML_ERROR_SUSPENDED¶: عملیات درخواست‌شده روی یک پارسر تعلیق‌شده انجام شد، اما مجاز نیست. این شامل تلاش‌هایی برای ارائه ورودی اضافی یا متوقف کردن پارسر است.

xml.parsers.expat.errors.XML_ERROR_NOT_SUSPENDED¶: تلاشی برای از سرگیری پارسر انجام شد، در حالی که پارسر معلق نشده بود.

xml.parsers.expat.errors.XML_ERROR_ABORTED¶: این نباید به برنامه‌های پایتون گزارش شود.

xml.parsers.expat.errors.XML_ERROR_FINISHED¶: عملیات درخواست‌شده روی پارسری انجام شد که تجزیه ورودی را به پایان رسانده بود، اما این کار مجاز نیست. این شامل تلاش‌ها برای فراهم کردن ورودی اضافی یا متوقف کردن پارسر می‌شود.

xml.parsers.expat.errors.XML_ERROR_SUSPEND_PE¶

xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XML¶: تلاشی برای لغو تعریف پیشوند فضای نام رزروشده xml یا مقیدسازی آن به URI یک فضای نام دیگر انجام شد.

xml.parsers.expat.errors.XML_ERROR_RESERVED_PREFIX_XMLNS¶: تلاشی برای اعلام یا لغو اعلام پیشوند فضای نام محفوظ xmlns انجام شد.

xml.parsers.expat.errors.XML_ERROR_RESERVED_NAMESPACE_URI¶: تلاشی برای اتصال URI یکی از پیشوندهای فضای نام رزروشده xml و xmlns به یک پیشوند فضای نام دیگر انجام شد.

xml.parsers.expat.errors.XML_ERROR_INVALID_ARGUMENT¶: این نباید به برنامه‌های پایتون گزارش شود.

xml.parsers.expat.errors.XML_ERROR_NO_BUFFER¶: این نباید به برنامه‌های پایتون گزارش شود.

xml.parsers.expat.errors.XML_ERROR_AMPLIFICATION_LIMIT_BREACH¶: از حد مجاز ضریب تقویت ورودی (input amplification factor) ناشی از DTD و موجودیت‌ها فراتر رفته است.

xml.parsers.expat.errors.XML_ERROR_NOT_STARTED¶: تلاش شد تا پارسر پیش از شروع متوقف یا معلق شود.

اضافه شده در نسخه‌ی 3.14.

پانویس‌ها

`xml.parsers.expat` --- تجزیه سریع XML با استفاده از Expat¶

اشیاء XMLParser¶

استثناهای ExpatError¶

مثال¶

توصیف‌های مدل محتوا¶

ثابت‌های خطای Expat¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه

xml.parsers.expat --- تجزیه سریع XML با استفاده از Expat¶

اشیاء XMLParser¶

استثناهای ExpatError¶

مثال¶

توصیف‌های مدل محتوا¶

ثابت‌های خطای Expat¶

`xml.parsers.expat` --- تجزیه سریع XML با استفاده از Expat¶