درخت XML و عناصر¶

XML یک قالب داده ذاتاً سلسله‌مراتبی است و طبیعی‌ترین راه نمایش آن، استفاده از یک درخت است. ET برای این منظور دو کلاس دارد: ElementTree کل سند XML را به‌صورت یک درخت نمایش می‌دهد و Element یک گره واحد در این درخت را نمایش می‌دهد. تعامل با کل سند (خواندن و نوشتن از/به پرونده‌ها) معمولاً در سطح ElementTree انجام می‌شود. تعامل با یک عنصر XML و عناصر فرعی آن در سطح Element انجام می‌شود.

تجزیه‌ی XML¶

در این بخش از سند XML فرضی country_data.xml به‌عنوان داده نمونه استفاده می‌کنیم:

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank>1</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank>4</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
    <country name="Panama">
        <rank>68</rank>
        <year>2011</year>
        <gdppc>13600</gdppc>
        <neighbor name="Costa Rica" direction="W"/>
        <neighbor name="Colombia" direction="E"/>
    </country>
</data>

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

import xml.etree.ElementTree as ET
tree = ET.parse('country_data.xml')
root = tree.getroot()

یا به‌صورت مستقیم از یک رشته:

root = ET.fromstring(country_data_as_string)

fromstring() XML را مستقیماً از یک رشته به یک Element تجزیه می‌کند، که عنصر ریشه‌ی درخت تجزیه‌شده است. سایر توابع تجزیه ممکن است یک ElementTree ایجاد کنند. برای اطمینان، مستندات را بررسی کنید.

به‌عنوان یک Element، root دارای یک برچسب و یک دیکشنری از ویژگی‌ها است:

>>> root.tag
'data'
>>> root.attrib
{}

همچنین گره‌های فرزندی دارد که می‌توانید آن‌ها را پیمایش کنید:

>>> for child in root:
...     print(child.tag, child.attrib)
...
country {'name': 'Liechtenstein'}
country {'name': 'Singapore'}
country {'name': 'Panama'}

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

>>> root[0][1].text
'2008'

API کششی (Pull API) برای تجزیه‌ی غیرمسدودکننده¶

بیشتر توابع تجزیه‌ی ارائه‌شده توسط این ماژول، پیش از بازگرداندن هرگونه نتیجه‌ای، نیاز دارند که کل سند به‌صورت یکجا خوانده شود. می‌توان از یک XMLParser استفاده کرد و داده‌ها را به‌صورت تدریجی به آن وارد کرد، اما این یک API فشاری (push API) است که متدهایی را روی یک هدف کال‌بک فراخوانی می‌کند و برای بیشتر نیازها بیش از حد سطح پایین و نامناسب است. گاهی آنچه کاربر واقعاً می‌خواهد این است که بتواند XML را به‌صورت تدریجی، بدون عملیات‌های مسدودکننده، تجزیه کند و در عین حال از سهولت داشتن اشیاء Element کاملاً ساخته‌شده بهره‌مند شود.

قدرتمندترین ابزار برای انجام این کار XMLPullParser است. این ابزار برای دریافت داده‌های XML نیازی به خواندن مسدودکننده ندارد و در عوض با فراخوانی‌های XMLPullParser.feed() به‌صورت تدریجی با داده تغذیه می‌شود. برای دریافت عناصر XML تجزیه‌شده، XMLPullParser.read_events() را فراخوانی کنید. در ادامه یک مثال آمده است:

>>> parser = ET.XMLPullParser(['start', 'end'])
>>> parser.feed('<mytag>sometext')
>>> list(parser.read_events())
[('start', <Element 'mytag' at 0x7fa66db2be58>)]
>>> parser.feed(' more text</mytag>')
>>> for event, elem in parser.read_events():
...     print(event)
...     print(elem.tag, 'text=', elem.text)
...
end
mytag text= sometext more text

مورد استفاده‌ی آشکار، برنامه‌هایی است که به‌صورت غیرمسدودکننده عمل می‌کنند و در آن‌ها داده‌های XML از یک سوکت دریافت می‌شوند یا به‌صورت تدریجی از یک دستگاه ذخیره‌سازی خوانده می‌شوند. در چنین مواردی، خواندن‌های مسدودکننده غیرقابل‌قبول هستند.

از آنجا که بسیار انعطاف‌پذیر است، XMLPullParser برای موارد استفاده ساده‌تر ممکن است دشوار باشد. اگر مانعی برای اینکه برنامه‌تان در هنگام خواندن داده‌های XML مسدود شود، ندارید، اما همچنان تمایل به داشتن قابلیت تجزیه افزایشی دارید، به iterparse() مراجعه کنید.

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

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

for event, elem in ET.iterparse(source):
    if elem.tag == 'record':
        process(elem)
        elem.clear()

اگر یک عنصر تعداد زیادی فرزند داشته باشد، فرزندان پردازش‌شده را از آن حذف کنید:

for event, elem in ET.iterparse(source, events=('start', 'end')):
    if event == 'start' and elem.tag == 'parent':
        parent = elem
    elif event == 'end' and elem.tag == 'child':
        process(elem)
        parent.remove(elem)

این مثال‌ها همگانی نیستند، تنها ایده‌ای برای دو مورد رایج ارائه می‌دهند. اگر اصلاً به درخت نیاز ندارید، به‌جای آن با XMLParser و یک هدف سفارشی تجزیه کنید؛ در این صورت درخت ساخته نمی‌شود و هیچ‌چیز لازم نیست حذف شود.

هرگاه بازخورد فوری از طریق رویدادها مطلوب باشد، فراخوانی متد XMLPullParser.flush() می‌تواند به کاهش تأخیر کمک کند؛ لطفاً اطمینان حاصل کنید که یادداشت‌های امنیتی مرتبط را مطالعه کرده‌اید.

یافتن عناصر جالب¶

Element چند متد مفید دارد که به پیمایش بازگشتی روی تمام زیردرخت زیر آن (فرزندان آن، فرزندان آن‌ها، و به همین ترتیب) کمک می‌کنند. برای مثال، Element.iter():

>>> for neighbor in root.iter('neighbor'):
...     print(neighbor.attrib)
...
{'name': 'Austria', 'direction': 'E'}
{'name': 'Switzerland', 'direction': 'W'}
{'name': 'Malaysia', 'direction': 'N'}
{'name': 'Costa Rica', 'direction': 'W'}
{'name': 'Colombia', 'direction': 'E'}

Element.findall() فقط عناصری با یک برچسب را پیدا می‌کند که فرزندان مستقیم عنصر جاری هستند. Element.find() اولین فرزند با یک برچسب خاص را پیدا می‌کند، و Element.text به محتوای متنی عنصر دسترسی پیدا می‌کند. Element.get() به ویژگی‌های عنصر دسترسی پیدا می‌کند:

>>> for country in root.findall('country'):
...     rank = country.find('rank').text
...     name = country.get('name')
...     print(name, rank)
...
Liechtenstein 1
Singapore 4
Panama 68

مشخص‌سازی پیشرفته‌تر اینکه کدام المان‌ها باید جستجو شوند، با استفاده از XPath امکان‌پذیر است.

تغییر یک پرونده XML¶

ElementTree راه ساده‌ای برای ساخت اسناد XML و نوشتن آن‌ها در پرونده‌ها فراهم می‌کند. متد ElementTree.write() برای همین منظور به کار می‌رود.

پس از ایجاد، می‌توان یک شیء Element را با تغییر مستقیم فیلدهای آن (مانند Element.text)، افزودن و تغییر صفت‌ها (متد Element.set()) و همچنین افزودن فرزندان جدید (برای مثال با Element.append()) دستکاری کرد.

فرض کنید می‌خواهیم یکی به رتبه هر کشور اضافه کنیم و یک ویژگی updated به عنصر rank اضافه کنیم:

>>> for rank in root.iter('rank'):
...     new_rank = int(rank.text) + 1
...     rank.text = str(new_rank)
...     rank.set('updated', 'yes')
...
>>> tree.write('output.xml')

اکنون XML ما به این شکل است:

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank updated="yes">2</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank updated="yes">5</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
    <country name="Panama">
        <rank updated="yes">69</rank>
        <year>2011</year>
        <gdppc>13600</gdppc>
        <neighbor name="Costa Rica" direction="W"/>
        <neighbor name="Colombia" direction="E"/>
    </country>
</data>

می‌توانیم المان‌ها را با استفاده از Element.remove() حذف کنیم. فرض کنید می‌خواهیم همه‌ی کشورهایی را که رتبه‌ای بالاتر از ۵۰ دارند حذف کنیم:

>>> for country in root.findall('country'):
...     # using root.findall() to avoid removal during traversal
...     rank = int(country.find('rank').text)
...     if rank > 50:
...         root.remove(country)
...
>>> tree.write('output.xml')

توجه داشته باشید که تغییر همزمان در حین پیمایش می‌تواند منجر به مشکلاتی شود، دقیقاً مانند زمانی که فهرست‌ها یا دیکشنری‌های پایتون را پیمایش می‌کنید و تغییر می‌دهید. بنابراین، مثال ابتدا همه‌ی المان‌های منطبق را با root.findall() جمع‌آوری می‌کند و تنها پس از آن، روی فهرست موارد منطبق پیمایش می‌کند.

اکنون XML ما به این شکل است:

<?xml version="1.0"?>
<data>
    <country name="Liechtenstein">
        <rank updated="yes">2</rank>
        <year>2008</year>
        <gdppc>141100</gdppc>
        <neighbor name="Austria" direction="E"/>
        <neighbor name="Switzerland" direction="W"/>
    </country>
    <country name="Singapore">
        <rank updated="yes">5</rank>
        <year>2011</year>
        <gdppc>59900</gdppc>
        <neighbor name="Malaysia" direction="N"/>
    </country>
</data>

ساخت اسناد XML¶

تابع SubElement() همچنین روش مناسبی برای ایجاد زیرعناصر جدید برای یک عنصر داده‌شده فراهم می‌کند:

>>> a = ET.Element('a')
>>> b = ET.SubElement(a, 'b')
>>> c = ET.SubElement(a, 'c')
>>> d = ET.SubElement(c, 'd')
>>> ET.dump(a)
<a><b /><c><d /></c></a>

تجزیه XML با فضای نامها¶

اگر ورودی XML دارای فضای نامها باشد، برچسب‌ها و ویژگی‌های دارای پیشوند در قالب prefix:sometag به {uri}sometag بسط داده می‌شوند که در آن prefix با URI کامل جایگزین می‌شود. همچنین، اگر یک فضای نام پیش‌فرض وجود داشته باشد، آن URI کامل به ابتدای همه برچسب‌های بدون پیشوند افزوده می‌شود.

در اینجا یک نمونه XML آمده است که دو فضای نام را شامل می‌شود؛ یکی با پیشوند «fictional» و دیگری به‌عنوان فضای نام پیش‌فرض عمل می‌کند:

<?xml version="1.0"?>
<actors xmlns:fictional="http://characters.example.com"
        xmlns="http://people.example.com">
    <actor>
        <name>John Cleese</name>
        <fictional:character>Lancelot</fictional:character>
        <fictional:character>Archie Leach</fictional:character>
    </actor>
    <actor>
        <name>Eric Idle</name>
        <fictional:character>Sir Robin</fictional:character>
        <fictional:character>Gunther</fictional:character>
        <fictional:character>Commander Clement</fictional:character>
    </actor>
</actors>

یکی از راه‌های جست‌وجو و بررسی این مثال XML، افزودن دستی URI به هر برچسب یا صفت در xpath متد find() یا findall() است:

root = fromstring(xml_text)
for actor in root.findall('{http://people.example.com}actor'):
    name = actor.find('{http://people.example.com}name')
    print(name.text)
    for char in actor.findall('{http://characters.example.com}character'):
        print(' |-->', char.text)

راه بهتر برای جست‌وجوی مثال XML دارای فضای نام این است که یک دیکشنری با پیشوندهای خودتان بسازید و از آن‌ها در توابع جست‌وجو استفاده کنید:

ns = {'real_person': 'http://people.example.com',
      'role': 'http://characters.example.com'}

for actor in root.findall('real_person:actor', ns):
    name = actor.find('real_person:name', ns)
    print(name.text)
    for char in actor.findall('role:character', ns):
        print(' |-->', char.text)

هر دوی این روش‌ها این خروجی را تولید می‌کنند:

John Cleese
 |--> Lancelot
 |--> Archie Leach
Eric Idle
 |--> Sir Robin
 |--> Gunther
 |--> Commander Clement

مثال¶

در اینجا مثالی آمده است که برخی از قابلیت‌های XPath این ماژول را نشان می‌دهد. ما از سند XML countrydata در بخش تجزیه XML استفاده خواهیم کرد:

import xml.etree.ElementTree as ET

root = ET.fromstring(countrydata)

# Top-level elements
root.findall(".")

# All 'neighbor' grand-children of 'country' children of the top-level
# elements
root.findall("./country/neighbor")

# Nodes with name='Singapore' that have a 'year' child
root.findall(".//year/..[@name='Singapore']")

# 'year' nodes that are children of nodes with name='Singapore'
root.findall(".//*[@name='Singapore']/year")

# All 'neighbor' nodes that are the second child of their parent
root.findall(".//neighbor[2]")

برای XML با فضای نامها، از نمادگذاری معمولِ کامل {namespace}tag استفاده کنید:

# All dublin-core "title" tags in the document
root.findall(".//{http://purl.org/dc/elements/1.1/}title")

سینتکس پشتیبانی‌شده‌ی XPath¶

عبارت‌های محمول (predicate) (عبارت‌های داخل کروشه) باید پس از یک نام برچسب، ستاره، یا عبارت محمول دیگری بیایند. عبارت‌های محمول position باید پس از یک نام برچسب بیایند.

توابع¶

xml.etree.ElementTree.canonicalize(xml_data=None, *, out=None, from_file=None, **options)¶

تابع تبدیل C14N 2.0.

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

این تابع یک رشته‌ی داده‌ی XML (xml_data) یا یک مسیر پرونده یا شیء شبه‌پرونده (from_file) را به‌عنوان ورودی می‌گیرد، آن را به قالب کانونیکال (canonical form) تبدیل می‌کند و در صورت ارائه، آن را با استفاده از شیء شبه‌پرونده out می‌نویسد، یا در غیر این صورت آن را به‌صورت یک رشته‌ی متنی برمی‌گرداند. پرونده خروجی متن دریافت می‌کند، نه بایت. بنابراین باید در حالت متنی با کدگذاری utf-8 باز شود.

کاربردهای معمول:

xml_data = "<root>...</root>"
print(canonicalize(xml_data))

with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
    canonicalize(xml_data, out=out_file)

with open("c14n_output.xml", mode='w', encoding='utf-8') as out_file:
    canonicalize(from_file="inputfile.xml", out=out_file)

گزینه‌های پیکربندی به شرح زیر است:

• with_comments: برای گنجاندن کامنت‌ها، روی true تنظیم شود (پیش‌فرض: false)

• strip_text: روی true تنظیم شود تا فضای سفید پیش و پس از محتوای متنی حذف شود

• rewrite_prefixes: روی true تنظیم کنید تا پیشوندهای فضای نام با "n{number}" جایگزین شوند

• qname_aware_tags: مجموعه‌ای از نام برچسب‌های آگاه از qname که در آن‌ها پیشوندها

• qname_aware_attrs: مجموعه‌ای از نام ویژگی‌های آگاه از qname که در آن‌ها پیشوندها

• exclude_attrs: مجموعه‌ای از نام ویژگی‌هایی که نباید سریال‌سازی شوند

• exclude_tags: مجموعه‌ای از نام برچسب‌ها که نباید سریال‌سازی شوند

در فهرست گزینه‌های بالا، «یک مجموعه» به هر مجموعه یا پیمایش‌پذیری از رشته‌ها اشاره دارد؛ هیچ ترتیبی مورد انتظار نیست.

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

xml.etree.ElementTree.Comment(text=None)¶

تابع کارخانه‌ای عنصر کامنت. این تابع کارخانه‌ای یک عنصر ویژه ایجاد می‌کند که توسط سریالایزر استاندارد به عنوان یک کامنت XML سریالایز خواهد شد. text رشته‌ای است که حاوی رشته‌ی کامنت است. یک نمونه‌ی عنصر را که نشان‌دهنده‌ی یک کامنت است برمی‌گرداند.

توجه داشته باشید که XMLParser به‌جای ایجاد اشیای کامنت برای توضیح‌های موجود در ورودی، آن‌ها را نادیده می‌گیرد. یک ElementTree تنها در صورتی حاوی گره‌های کامنت خواهد بود که آن‌ها با استفاده از یکی از متدهای Element در درخت درج‌شده باشند.

xml.etree.ElementTree.dump(elem)¶

یک درخت المان یا ساختار المان را در sys.stdout می‌نویسد. این تابع باید فقط برای اشکال‌زدایی به کار رود.

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

elem یک درخت المان یا یک المان منفرد است.

تغییر یافته در نسخه‌ی 3.8: تابع dump() اکنون ترتیب ویژگی‌های مشخص‌شده توسط کاربر را حفظ می‌کند.

xml.etree.ElementTree.fromstring(text, parser=None)¶

یک بخش XML را از یک ثابت رشته‌ای تجزیه می‌کند. مانند XML(). text یک رشته حاوی داده‌های XML است. parser یک نمونه اختیاری از پارسر است. اگر داده نشود، از پارسر استاندارد XMLParser استفاده می‌شود. یک نمونه Element برمی‌گرداند.

xml.etree.ElementTree.fromstringlist(sequence, parser=None)¶

یک سند XML را از یک دنباله از قطعه‌های رشته تجزیه می‌کند. sequence یک فهرست یا دنباله دیگر حاوی قطعه‌های داده XML است. parser یک نمونه اختیاری از پارسر است. اگر داده نشود، از پارسری استاندارد XMLParser استفاده می‌شود. یک نمونه از Element را برمی‌گرداند.

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

xml.etree.ElementTree.indent(tree, space='  ', level=0)¶

فضای خالی را به زیردرخت می‌افزاید تا درخت به‌صورت بصری تورفتگی پیدا کند. می‌توان از آن برای تولید خروجی XML زیبانویسی‌شده استفاده کرد. tree می‌تواند یک Element یا ElementTree باشد. space رشته‌ی فضای خالی است که برای هر سطح تورفتگی درج می‌شود و به‌طور پیش‌فرض دو نویسه فاصله است. برای ایجاد تورفتگی در زیردرخت‌های جزئی درون درختی که از قبل تورفتگی داده شده است، سطح تورفتگی اولیه را به‌عنوان level ارسال کنید.

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

xml.etree.ElementTree.iselement(element)¶

بررسی می‌کند که آیا یک شیء به‌نظر یک شیء المان معتبر می‌رسد. element یک نمونه المان است. اگر این یک شیء المان باشد، True را بازمی‌گرداند.

xml.etree.ElementTree.iterparse(source, events=None, parser=None)¶

یک بخش XML را به طور تدریجی به یک درخت عناصر تجزیه می‌کند و آنچه را که در جریان است به کاربر گزارش می‌دهد. source یک نام‌پرونده یا شیء پرونده حاوی داده‌های XML است. events دنباله‌ای از رویدادها برای گزارش‌دهی است. رویدادهای پشتیبانی‌شده رشته‌های "start"، "end"، "comment"، "pi"، "start-ns" و "end-ns" هستند (رویدادهای «ns» برای دریافت اطلاعات دقیق فضای نام استفاده می‌شوند). اگر events حذف شود، فقط رویدادهای "end" گزارش می‌شوند. parser یک نمونه‌ی پارسر اختیاری است. اگر داده نشده باشد، از پارسر استاندارد XMLParser استفاده می‌شود. parser باید نمونه‌ای از XMLParser یا زیرکلاس آن باشد و فقط می‌تواند از TreeBuilder پیش‌فرض به عنوان هدف استفاده کند. یک پیمایش‌گر را برمی‌گرداند که جفت‌های (event, elem) را فراهم می‌کند؛ این پیمایش‌گر دارای یک ویژگی root است که به عنصر ریشه‌ی درخت XML حاصل پس از خوانده شدن کامل source ارجاع می‌دهد. این پیمایش‌گر دارای متد close() است که اگر source یک نام‌پرونده باشد، شیء پرونده‌ی داخلی را می‌بندد.

توجه داشته باشید که با وجود اینکه iterparse() درخت را به‌صورت تدریجی می‌سازد، خواندن‌های مسدودکننده روی source (یا پرونده‌ای که source نام آن را مشخص می‌کند) انجام می‌دهد. بنابراین، برای کاربردهایی که در آن‌ها نمی‌توان خواندن‌های مسدودکننده انجام داد، مناسب نیست. برای تجزیه کاملاً غیرمسدودکننده، XMLPullParser را ببینید.

درخت تنها به‌صورت افزایشی ساخته می‌شود، به‌صورت افزایشی آزاد نمی‌شود: هر عنصر پردازش‌شده تا زمانی که کل سند خوانده شود نگه‌داشته می‌شود. برای نحوه نگه‌داشتن مصرف حافظه در سطح پایین به API کششی (Pull API) برای تجزیه‌ی غیرمسدودکننده مراجعه کنید.

نکته

iterparse() هنگامی که یک رویداد "start" را منتشر می‌کند، تنها این تضمین را می‌دهد که نویسه ">" از یک برچسب آغازین را مشاهده کرده است؛ بنابراین ویژگی‌ها تعریف‌شده‌اند، اما محتوای ویژگی‌های text و tail در آن نقطه تعریف‌نشده است. همین موضوع در مورد فرزندان عنصر نیز صدق می‌کند؛ ممکن است وجود داشته باشند یا وجود نداشته باشند.

اگر به یک المان کاملاً پرشده نیاز دارید، در عوض به دنبال رویدادهای «end» بگردید.

منسوخ شده از نسخه‌ی 3.4: آرگومان parser.

تغییر یافته در نسخه‌ی 3.8: رویدادهای comment و pi افزوده شدند.

تغییر یافته در نسخه‌ی 3.13: متد close() افزوده شد.

تغییر یافته در نسخه‌ی 3.15: اگر پیمایش‌گر پرونده‌ای را باز کرده باشد و آن را به‌طور صریح نبندد، اکنون یک ResourceWarning صادر می‌شود.

xml.etree.ElementTree.parse(source, parser=None)¶

یک بخش XML را به یک درخت عنصر تجزیه می‌کند. source یک نام پرونده یا شیء پرونده حاوی داده‌های XML است. parser یک نمونه پارسر اختیاری است. اگر داده نشود، از پارسر استاندارد XMLParser استفاده می‌شود. یک نمونه ElementTree بازمی‌گرداند.

xml.etree.ElementTree.ProcessingInstruction(target, text=None)¶

کارخانه عنصر PI. این تابع کارخانه‌ای یک عنصر ویژه ایجاد می‌کند که به‌صورت یک دستور پردازشی XML سریال‌سازی خواهد شد. target رشته‌ای حاوی هدف PI است. text رشته‌ای حاوی محتویات PI است، در صورتی که ارائه شده باشد. یک نمونه عنصر را برمی‌گرداند که نشان‌دهنده یک دستور پردازشی است.

توجه داشته باشید که XMLParser از دستورالعمل‌های پردازشی در ورودی می‌گذرد، به‌جای آن‌که اشیای PI برای آن‌ها ایجاد کند. یک ElementTree تنها شامل گره‌های دستورالعمل پردازشی خواهد بود اگر آن‌ها با استفاده از یکی از متدهای Element در درخت درج شده باشند.

xml.etree.ElementTree.register_namespace(prefix, uri)¶

یک پیشوند فضای نام را ثبت می‌کند. این ثبت سراسری است و هر نگاشت موجود برای پیشوند داده‌شده یا URI فضای نام حذف خواهد شد. prefix یک پیشوند فضای نام است. uri یک URI فضای نام است. برچسب‌ها و ویژگی‌های این فضای نام در صورت امکان با پیشوند داده‌شده سریال‌سازی خواهند شد.

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

xml.etree.ElementTree.SubElement(parent, tag, /, attrib={}, **extra)¶

کارخانه‌ی زیرالمان. این تابع نمونه‌ای از المان ایجاد می‌کند و آن را به یک المان موجود می‌افزاید.

parent عنصر والد است. tag نام زیرعنصر است. attrib یک دیکشنری اختیاری است که حاوی ویژگی‌های عنصر است. extra شامل ویژگی‌های اضافی است که به صورت آرگومان‌های کلیدواژه‌ای داده شده‌اند. یک نمونه‌ی عنصر را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.15: پارامتر attrib اکنون می‌تواند یک frozendict باشد.

تغییر یافته در نسخه‌ی 3.15: پارامترهای parent و tag اکنون صرفاً جایگاهی هستند.

xml.etree.ElementTree.tostring(element, encoding='us-ascii', method='xml', *, xml_declaration=None, default_namespace=None, short_empty_elements=True)¶

نمایش رشته‌ای از یک المان XML را تولید می‌کند که شامل تمام زیرالمان‌ها است. element یک نمونه از Element است. encoding [1] کدگذاری خروجی است (پیش‌فرض US-ASCII است). برای تولید یک رشته یونیکد، از encoding="unicode" استفاده کنید (در غیر این صورت، یک رشته بایتی تولید می‌شود). method یکی از "xml"، "html" یا "text" است (پیش‌فرض "xml" است). xml_declaration، default_namespace و short_empty_elements همان معنایی را دارند که در ElementTree.write() آمده است. رشته‌ای (به‌صورت اختیاری) کدگذاری‌شده حاوی داده‌های XML را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.4: پارامتر short_empty_elements اضافه شد.

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

تغییر یافته در نسخه‌ی 3.8: تابع tostring() اکنون ترتیب ویژگی‌های مشخص‌شده توسط کاربر را حفظ می‌کند.

xml.etree.ElementTree.tostringlist(element, encoding='us-ascii', method='xml', *, xml_declaration=None, default_namespace=None, short_empty_elements=True)¶

نمایش رشته‌ای از یک عنصر XML، شامل تمام زیرعناصر، تولید می‌کند. element یک نمونه از Element است. encoding [1] کدگذاری خروجی است (پیش‌فرض US-ASCII است). برای تولید یک رشته یونیکد از encoding="unicode" استفاده کنید (در غیر این صورت، یک رشته بایتی تولید می‌شود). method یکی از "xml"، "html" یا "text" است (پیش‌فرض "xml" است). xml_declaration، default_namespace و short_empty_elements همان معنای موجود در ElementTree.write() را دارند. فهرستی از رشته‌های (به‌اختیار) کدگذاری‌شده حاوی داده‌های XML را برمی‌گرداند. هیچ ترتیب خاصی را تضمین نمی‌کند، به جز اینکه b"".join(tostringlist(element)) == tostring(element).

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

تغییر یافته در نسخه‌ی 3.4: پارامتر short_empty_elements اضافه شد.

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

تغییر یافته در نسخه‌ی 3.8: تابع tostringlist() اکنون ترتیب ویژگی‌های مشخص‌شده توسط کاربر را حفظ می‌کند.

xml.etree.ElementTree.XML(text, parser=None)¶

یک بخش XML را از یک ثابت رشته تجزیه می‌کند. می‌توان از این تابع برای تعبیه «مقادیر لفظی XML» در کد پایتون استفاده کرد. text یک رشته حاوی داده‌های XML است. parser یک نمونه پارسر اختیاری است. اگر داده نشود، از پارسر استاندارد XMLParser استفاده می‌شود. یک نمونه Element را برمی‌گرداند.

xml.etree.ElementTree.XMLID(text, parser=None)¶

یک بخش XML را از یک ثابت رشته‌ای تجزیه می‌کند، و همچنین دیکشنری‌ای برمی‌گرداند که شناسه‌های المان را به المان‌ها نگاشت می‌کند. text یک رشته حاوی داده‌های XML است. parser یک نمونه‌ی پارسر اختیاری است. اگر ارائه نشود، از پارسر استاندارد XMLParser استفاده می‌شود. یک تاپل شامل یک نمونه‌ی Element و یک دیکشنری برمی‌گرداند.

مثال¶

در اینجا مثالی آمده است که استفاده از ماژول XInclude را نشان می‌دهد. برای درج یک سند XML در سند جاری، از عنصر {http://www.w3.org/2001/XInclude}include استفاده کنید، صفت parse را روی "xml" تنظیم کنید و از صفت href برای مشخص کردن سند موردنظر برای درج استفاده کنید.

<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include href="source.xml" parse="xml" />
</document>

به‌طور پیش‌فرض، ویژگی href به‌عنوان نام پرونده در نظر گرفته می‌شود. می‌توانید از بارگذارهای سفارشی برای بازنویسی این رفتار استفاده کنید. همچنین توجه داشته باشید که کمک‌کننده استاندارد از سینتکس XPointer پشتیبانی نمی‌کند.

برای پردازش این پرونده، آن را به‌صورت معمول بارگذاری کنید و عنصر ریشه را به ماژول xml.etree.ElementTree ارسال کنید:

from xml.etree import ElementTree, ElementInclude

tree = ElementTree.parse("document.xml")
root = tree.getroot()

ElementInclude.include(root)

ماژول ElementInclude، المان {http://www.w3.org/2001/XInclude}include را با المان ریشه‌ی سند source.xml جایگزین می‌کند. نتیجه ممکن است چیزی شبیه به این باشد:

<document xmlns:xi="http://www.w3.org/2001/XInclude">
  <para>این یک پاراگراف است.</para>
</document>

اگر صفت parse حذف شود، مقدار پیش‌فرض آن "xml" است. صفت href الزامی است.

برای شامل کردن یک سند متنی، از عنصر {http://www.w3.org/2001/XInclude}include استفاده کنید و ویژگی parse را روی "text" تنظیم کنید:

<?xml version="1.0"?>
<document xmlns:xi="http://www.w3.org/2001/XInclude">
  Copyright (c) <xi:include href="year.txt" parse="text" />.
</document>

ممکن است نتیجه چیزی شبیه به این باشد:

<document xmlns:xi="http://www.w3.org/2001/XInclude">
  حق نشر (c) ۲۰۰۳.
</document>

توابع¶

xml.etree.ElementInclude.default_loader(href, parse, encoding=None)¶

بارگذار پیش‌فرض. این بارگذار پیش‌فرض، یک منبع شامل‌شده را از دیسک می‌خواند. href یک URL است. parse برای حالت تجزیه است و می‌تواند "xml" یا "text" باشد. encoding یک کدگذاری متن اختیاری است. اگر داده نشود، کدگذاری utf-8 است. منبع بسط‌یافته را برمی‌گرداند. اگر حالت تجزیه "xml" باشد، این یک نمونه Element است. اگر حالت تجزیه "text" باشد، این یک رشته است. اگر بارگذار با شکست مواجه شود، می‌تواند None برگرداند یا یک استثنا پرتاب کند.

xml.etree.ElementInclude.include(elem, loader=None, base_url=None, max_depth=6)¶

این تابع دایرکتیوهای XInclude را به‌صورت درجا در درختی که elem به آن اشاره می‌کند، بسط می‌دهد. elem می‌تواند المان ریشه‌ی Element یا یک نمونه از ElementTree برای یافتن چنین المانی باشد. loader یک بارگذار منبع اختیاری است. در صورت حذف، به‌طور پیش‌فرض از default_loader() استفاده می‌شود. در صورت ارائه، باید یک شیء قابل فراخوانی باشد که همان رابط default_loader() را پیاده‌سازی می‌کند. base_url نشانی پایه‌ی پرونده اصلی است و برای رفع ارجاع‌های نسبی به پرونده‌های include استفاده می‌شود. max_depth بیشینه تعداد درج‌های بازگشتی است. این مقدار محدود شده است تا خطر انفجار محتوای مخرب کاهش یابد. برای غیرفعال کردن این محدودیت، None را ارسال کنید.

تغییر یافته در نسخه‌ی 3.9: پارامترهای base_url و max_depth اضافه شدند.

اشیای عنصر¶

class xml.etree.ElementTree.Element(tag, /, attrib={}, **extra)¶

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

tag نام عنصر است. attrib یک دیکشنری اختیاری است که حاوی ویژگی‌های عنصر است. extra شامل ویژگی‌های اضافی است که به صورت آرگومان‌های کلیدواژه‌ای داده شده‌اند.

نامِ المان و نام‌ها و مقادیرِ ویژگی‌ها رشته‌ها یا نمونه‌های QName هستند، و متن و tail رشته‌ها یا None هستند. نامِ المان همچنین می‌تواند Comment() یا ProcessingInstruction() باشد که برای المان‌های خاص استفاده می‌شوند. اگر None باشد، خودِ المان سریال‌سازی نمی‌شود: تنها متن و فرزندانِ آن نوشته می‌شوند و ویژگی‌های آن نادیده گرفته می‌شوند. این می‌تواند برای یک قطعه که شامل چندین المان است استفاده شود. با method="html" مقدارِ ویژگی نیز می‌تواند None باشد که یک ویژگیِ خالی تولید می‌کند (مانند checked). سایر اشیاء می‌توانند در درخت ذخیره شوند، اما آن‌ها نمی‌توانند سریال‌سازی شوند.

تغییر یافته در نسخه‌ی 3.15: پارامتر attrib اکنون می‌تواند یک frozendict باشد.

تغییر یافته در نسخه‌ی 3.15: tag اکنون یک پارامتر فقط-جایگاهی است.

tag¶

رشته‌ای که مشخص می‌کند این المان نمایانگر چه نوع داده‌ای است (به عبارت دیگر، نوع المان).

text¶

tail¶

می‌توان از این ویژگی‌ها برای نگهداری داده‌های اضافی مرتبط با عنصر استفاده کرد. مقادیر آن‌ها معمولاً رشته هستند، اما می‌توانند هر شیء مختص برنامه باشند. اگر عنصر از یک پرونده XML ایجاد شده باشد، ویژگی text یا شامل متن بین برچسب شروع عنصر و اولین فرزند آن یا برچسب پایان آن است، یا None، و ویژگی tail یا شامل متن بین برچسب پایان عنصر و برچسب بعدی است، یا None. برای داده‌های XML

<a><b>1<c>2<d/>3</c></b>4</a>

عنصر a برای هر دو ویژگی text و tail دارای مقدار None است، عنصر b دارای text با مقدار "1" و tail با مقدار "4" است، عنصر c دارای text با مقدار "2" و tail با مقدار None است، و عنصر d دارای text با مقدار None و tail با مقدار "3" است.

برای جمع‌آوری متن داخلی یک المان، itertext() را ببینید، برای مثال "".join(element.itertext()).

برنامه‌های کاربردی می‌توانند اشیاء دلخواه را در این ویژگی‌ها ذخیره کنند.

attrib¶

دیکشنری حاوی ویژگی‌های عنصر. توجه داشته باشید که اگرچه مقدار attrib همیشه یک دیکشنری پایتون تغییرپذیر واقعی است، اما یک پیاده‌سازی ElementTree ممکن است از بازنمایی داخلی دیگری استفاده کند و دیکشنری را تنها در صورتی ایجاد کند که کسی آن را درخواست کند. برای بهره‌گیری از چنین پیاده‌سازی‌هایی، تا حد امکان از متدهای دیکشنری زیر استفاده کنید.

متدهای زیر که شبیه دیکشنری هستند، روی صفت‌های عنصر کار می‌کنند.

clear()¶

یک عنصر را بازنشانی می‌کند. این تابع همه‌ی زیرعناصر را حذف می‌کند، همه‌ی ویژگی‌ها را پاک می‌کند و ویژگی‌های text و tail را روی None قرار می‌دهد.

get(key, default=None)¶

ویژگی المان با نام key را دریافت می‌کند.

مقدار ویژگی را برمی‌گرداند، یا اگر ویژگی یافت نشد، default را برمی‌گرداند.

items()¶

ویژگی‌های المان را به‌عنوان جفت‌های (نام، مقدار) برمی‌گرداند.

keys()¶

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

set(key, value)¶

ویژگی key را روی عنصر برابر value قرار دهید.

متدهای زیر روی فرزندان عنصر (زیرعناصر) عمل می‌کنند.

append(subelement)¶

عنصر subelement را به انتهای فهرست داخلی زیرعناصر این عنصر اضافه می‌کند. اگر subelement یک Element نباشد، TypeError پرتاب می‌شود.

extend(subelements)¶

زیرعناصر را از یک پیمایش‌پذیر از عناصر می‌افزاید. اگر زیرعنصری Element نباشد، TypeError پرتاب می‌شود.

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

find(match, namespaces=None)¶

اولین المان فرعی منطبق با match را پیدا می‌کند. match می‌تواند یک نام تگ یا یک مسیر باشد. یک نمونه المان یا None برمی‌گرداند. namespaces یک نگاشت اختیاری از پیشوند فضای نام به نام کامل است. برای انتقال تمام نام‌های تگ بدون پیشوند در عبارت به فضای نام داده‌شده، '' را به‌عنوان پیشوند ارسال کنید.

findall(match, namespaces=None)¶

تمام زیرالمان‌های منطبق را بر اساس نام برچسب یا مسیر پیدا می‌کند. فهرستی شامل تمام المان‌های منطبق را به ترتیب سند برمی‌گرداند. namespaces یک نگاشت اختیاری از پیشوند فضای نام به نام کامل است. برای انتقال تمام نام‌های برچسب بدون پیشوند در عبارت به فضای نام داده‌شده، '' را به‌عنوان پیشوند ارسال کنید.

findtext(match, default=None, namespaces=None)¶

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

insert(index, subelement)¶

subelement را در موقعیت داده‌شده در این عنصر درج می‌کند. اگر subelement یک Element نباشد، TypeError پرتاب می‌شود.

iter(tag=None)¶

یک پیمایش‌گر درختی با المان فعلی به‌عنوان ریشه ایجاد می‌کند. این پیمایش‌گر این المان و تمام المان‌های زیر آن را به ترتیب سند (اول عمق) پیمایش می‌کند. اگر tag برابر None یا '*' نباشد، تنها المان‌هایی که برچسب آن‌ها برابر tag است از پیمایش‌گر برگردانده می‌شوند. اگر ساختار درختی در حین پیمایش تغییر کند، نتیجه تعریف‌نشده است.

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

iterfind(match, namespaces=None)¶

همه زیرالمان‌های منطبق را بر اساس نام برچسب یا مسیر می‌یابد. یک پیمایش‌پذیر برمی‌گرداند که همه المان‌های منطبق را به ترتیب سند تولید می‌کند. namespaces یک نگاشت اختیاری از پیشوند فضای نام به نام کامل است.

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

itertext()¶

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

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

makeelement(tag, attrib)¶

یک شیء المان جدید از همان نوع این المان ایجاد می‌کند. این متد را فراخوانی نکنید، در عوض از تابع کارخانه‌ی SubElement() استفاده کنید.

remove(subelement)¶

subelement را از المان حذف می‌کند. برخلاف متدهای find*، این متد المان‌ها را بر اساس هویت نمونه مقایسه می‌کند، نه بر اساس مقدار tag یا محتوای آن‌ها.

اشیاء Element همچنین از متدهای نوع دنباله‌ای زیر برای کار با زیرعناصر پشتیبانی می‌کنند: __delitem__()، __getitem__()، __setitem__()، __len__().

هشدار: المان‌هایی که المان فرعی ندارند، به‌صورت False ارزیابی می‌شوند. در نسخه‌ای آینده از پایتون، همه المان‌ها صرف‌نظر از وجود المان‌های فرعی، به‌صورت True ارزیابی خواهند شد. در عوض، بررسی‌های صریح len(elem) یا elem is not None را ترجیح دهید.:

element = root.find('foo')

if not element:  # careful!
    print("element not found, or element has no subelements")

if element is None:
    print("element not found")

تغییر یافته در نسخه‌ی 3.12: بررسی مقدار بولی یک عنصر باعث صدور DeprecationWarning می‌شود.

پیش از Python 3.8، ترتیب سریال‌سازی ویژگی‌های XML عناصر با مرتب‌سازی ویژگی‌ها بر اساس نام آن‌ها به‌صورت مصنوعی قابل پیش‌بینی شده بود. بر اساس ترتیب اکنون تضمین‌شده‌ی دیکشنری‌ها، این مرتب‌سازی مجدد خودسرانه در Python 3.8 حذف شد تا ترتیبی که ویژگی‌ها در اصل با آن تجزیه شده یا توسط کد کاربر ایجاد شده بودند، حفظ شود.

به‌طور کلی، با توجه به اینکه XML Information Set به‌صراحت ترتیب ویژگی‌ها را از انتقال اطلاعات مستثنا می‌کند، کد کاربر باید سعی کند به ترتیب خاصی از ویژگی‌ها وابسته نباشد. کد باید برای مواجهه با هر ترتیبی در ورودی آماده باشد. در مواردی که خروجی XML قطعی مورد نیاز است، برای مثال برای امضای رمزنگارانه یا مجموعه‌های داده آزمایشی، سریال‌سازی کانونیکال (canonical serialisation) با تابع canonicalize() در دسترس است.

در مواردی که خروجی کانونیکال قابل اعمال نیست، اما همچنان ترتیب مشخصی برای ویژگی‌ها در خروجی مطلوب است، کد باید تلاش کند ویژگی‌ها را مستقیماً با ترتیب مطلوب ایجاد کند تا از ناهماهنگی‌های ادراکی برای خوانندگان کد پرهیز شود. در مواردی که دستیابی به این امر دشوار است، می‌توان پیش از سریال‌سازی (serialisation)، دستورالعملی مانند آنچه در ادامه می‌آید را برای اعمال ترتیبی مستقل از ایجاد Element به کار برد:

def reorder_attributes(root):
    for el in root.iter():
        attrib = el.attrib
        if len(attrib) > 1:
            # adjust attribute order, e.g. by sorting
            attribs = sorted(attrib.items())
            attrib.clear()
            attrib.update(attribs)

اشیاء ElementTree¶

class xml.etree.ElementTree.ElementTree(element=None, file=None)¶

کلاس پوششی ElementTree. این کلاس کل یک سلسله‌مراتب عناصر را نشان می‌دهد و پشتیبانی اضافه‌ای برای سریال‌سازی به XML استاندارد و از آن می‌افزاید.

element عنصر ریشه است. درخت با محتویات XML file، در صورت ارائه‌شدن، مقداردهی اولیه می‌شود.

_setroot(element)¶

المان ریشه‌ی این درخت را جایگزین می‌کند. این کار محتویات کنونی درخت را دور می‌اندازد و آن را با المان داده‌شده جایگزین می‌کند. با احتیاط استفاده کنید. element یک نمونه المان است.

find(match, namespaces=None)¶

همانند Element.find()، با شروع از ریشه‌ی درخت.

findall(match, namespaces=None)¶

مشابه Element.findall()، با شروع از ریشه درخت.

findtext(match, default=None, namespaces=None)¶

همانند Element.findtext() است و از ریشه‌ی درخت شروع می‌شود.

getroot()¶

عنصر ریشه‌ی این درخت را برمی‌گرداند.

iter(tag=None)¶

یک پیمایش‌گر درختی برای عنصر ریشه ایجاد می‌کند و بازمی‌گرداند. این پیمایش‌گر همه عناصر این درخت را به ترتیب بخش پیمایش می‌کند. tag برچسب مورد جستجو است (پیش‌فرض، بازگرداندن همه عناصر است).

iterfind(match, namespaces=None)¶

مانند Element.iterfind()، از ریشه‌ی درخت شروع می‌شود.

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

parse(source, parser=None)¶

یک بخش خارجی XML را در این درخت عنصر بارگذاری می‌کند. source یک نام پرونده یا file object است. parser یک نمونه اختیاری از پارسر است. اگر داده نشود، از پارسر استاندارد XMLParser استفاده می‌شود. عنصر ریشه‌ی بخش را برمی‌گرداند.

write(file, encoding='us-ascii', xml_declaration=None, default_namespace=None, method='xml', *, short_empty_elements=True)¶

درخت المان را به‌صورت XML در یک پرونده می‌نویسد. file یک نام پرونده یا یک file object باز شده برای نوشتن است. encoding [1] کدگذاری خروجی است (پیش‌فرض US-ASCII است). xml_declaration کنترل می‌کند که آیا یک اعلامیه XML باید به پرونده اضافه شود یا خیر. برای هرگز از False، برای همیشه از True و برای افزودن فقط در صورتی که US-ASCII یا UTF-8 یا Unicode نباشد از None استفاده کنید (پیش‌فرض None است). default_namespace فضای نام پیش‌فرض XML را تنظیم می‌کند (برای "xmlns"). method یکی از "xml"، "html" یا "text" است (پیش‌فرض "xml" است). پارامتر short_empty_elements که فقط کلیدواژه‌ای است، قالب‌بندی المان‌های بدون محتوا را کنترل می‌کند. اگر True باشد (پیش‌فرض)، آن‌ها به‌صورت یک تگ خودبسته در خروجی قرار می‌گیرند، در غیر این صورت به‌صورت یک جفت تگ آغاز/پایان در خروجی قرار می‌گیرند.

خروجی یا یک رشته (str) است یا دودویی (bytes). این موضوع با آرگومان encoding کنترل می‌شود. اگر encoding برابر "unicode" باشد، خروجی یک رشته است؛ در غیر این صورت، دودویی است. توجه داشته باشید که این ممکن است با نوع file ناسازگار باشد، اگر file یک شیء پرونده باز باشد؛ اطمینان حاصل کنید که سعی نمی‌کنید یک رشته را در یک جریان دودویی بنویسید و برعکس.

تغییر یافته در نسخه‌ی 3.4: پارامتر short_empty_elements اضافه شد.

تغییر یافته در نسخه‌ی 3.8: متد write() اکنون ترتیب ویژگی‌های تعیین‌شده توسط کاربر را حفظ می‌کند.

این پرونده XMLای است که قرار است دستکاری شود:

<html>
    <head>
        <title>صفحه نمونه</title>
    </head>
    <body>
        <p>به <a href="http://example.org/">example.org</a>
        یا <a href="http://example.com/">example.com</a> منتقل شد.</p>
    </body>
</html>

مثالی از تغییر ویژگی "target" هر پیوند در اولین پاراگراف:

>>> from xml.etree.ElementTree import ElementTree
>>> tree = ElementTree()
>>> tree.parse("index.xhtml")
<Element 'html' at 0xb77e6fac>
>>> p = tree.find("body/p")     # Finds first occurrence of tag p in body
>>> p
<Element 'p' at 0xb77ec26c>
>>> links = list(p.iter("a"))   # Returns list of all links
>>> links
[<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>]
>>> for i in links:             # Iterates through all found links
...     i.attrib["target"] = "blank"
...
>>> tree.write("output.xhtml")

اشیاء QName¶

class xml.etree.ElementTree.QName(text_or_uri, tag=None)¶

دربرگیرنده‌ی QName. می‌توان از آن برای دربرگرفتن مقدار ویژگی QName استفاده کرد تا مدیریت صحیح فضای نام در خروجی حاصل شود. text_or_uri رشته‌ای است که مقدار QName را به شکل {uri}local در بر دارد، یا اگر آرگومان tag داده شده باشد، بخش URI یک QName است. اگر tag داده شود، آرگومان اول به‌عنوان URI تفسیر می‌شود و این آرگومان به‌عنوان نام محلی تفسیر می‌شود. نمونه‌های QName غیرشفاف هستند.

اشیای TreeBuilder¶

class xml.etree.ElementTree.TreeBuilder(element_factory=None, *, comment_factory=None, pi_factory=None, insert_comments=False, insert_pis=False)¶

سازنده‌ی عام ساختار المان. این سازنده، دنباله‌ای از فراخوانی‌های متدهای start، data، end، comment و pi را به یک ساختار المان خوش‌ساخت تبدیل می‌کند. شما می‌توانید از این کلاس برای ساخت یک ساختار المان با استفاده از یک پارسری XML سفارشی، یا پارسری برای قالبی دیگر XML-مانند استفاده کنید.

element_factory، در صورت ارائه، باید یک شیء فراخوانی‌پذیر باشد که دو آرگومان جایگاهی می‌پذیرد: یک برچسب و یک دیکشنری از صفات. انتظار می‌رود که یک نمونه عنصر جدید را برگرداند.

توابع comment_factory و pi_factory، در صورت ارائه، باید مانند توابع Comment() و ProcessingInstruction() رفتار کنند تا کامنت‌ها و دستورالعمل‌های پردازشی ایجاد شوند. در صورت ارائه نشدن، کارخانه‌های پیش‌فرض استفاده خواهند شد. هرگاه مقدار insert_comments و/یا insert_pis برابر با true باشد، کامنت‌ها/دستورالعمل‌های پردازشی در صورتی در درخت درج می‌شوند که درون عنصر ریشه ظاهر شوند (اما نه خارج از آن).

close()¶

بافرهای سازنده را تخلیه می‌کند و عنصر سند سطح بالا را بازمی‌گرداند. یک نمونه از Element بازمی‌گرداند.

data(data)¶

متن را به عنصر فعلی اضافه می‌کند. data یک رشته است.

end(tag)¶

عنصر جاری را می‌بندد. tag نام عنصر است. عنصر بسته‌شده را برمی‌گرداند.

start(tag, attrs)¶

یک عنصر جدید را باز می‌کند. tag نام عنصر است. attrs یک دیکشنری حاوی ویژگی‌های عنصر است. عنصر بازشده را برمی‌گرداند.

comment(text)¶

یک کامنت با text داده‌شده ایجاد می‌کند. اگر insert_comments درست باشد، آن را نیز به درخت اضافه می‌کند.

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

pi(target, text)¶

یک دستورالعمل پردازشی با نام target و text داده‌شده ایجاد می‌کند. اگر insert_pis درست باشد، آن را به درخت نیز اضافه می‌کند.

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

علاوه بر این، یک شیء سفارشی TreeBuilder می‌تواند متدهای زیر را ارائه دهد:

doctype(name, pubid, system)¶

اعلان نوع سند (doctype) را مدیریت می‌کند. name نام doctype است. pubid شناسه عام است. system شناسه سیستم است. این متد در کلاس پیش‌فرض TreeBuilder وجود ندارد.

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

start_ns(prefix, uri)¶

هر زمان که پارسر با یک اعلان فضای نام جدید مواجه شود، پیش از کال‌بک start() برای عنصر آغازینی که آن را تعریف می‌کند، فراخوانی می‌شود. prefix برای فضای نام پیش‌فرض '' است و در غیر این صورت، نام پیشوندِ فضای نام اعلان‌شده است. uri URI فضای نام است.

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

end_ns(prefix)¶

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

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

class xml.etree.ElementTree.C14NWriterTarget(write, *, with_comments=False, strip_text=False, rewrite_prefixes=False, qname_aware_tags=None, qname_aware_attrs=None, exclude_attrs=None, exclude_tags=None)¶

یک نویسنده برای C14N 2.0. آرگومان‌ها همان آرگومان‌های تابع canonicalize() هستند. این کلاس درختی نمی‌سازد، بلکه رویدادهای کال‌بک را مستقیماً با استفاده از تابع write به شکلی سریال‌شده تبدیل می‌کند.

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

اشیاء XMLParser¶

class xml.etree.ElementTree.XMLParser(*, target=None, encoding=None)¶

این کلاس، بلوک سازنده‌ی سطح پایین این ماژول است. این کلاس از xml.parsers.expat برای تجزیه‌ی کارآمد و رویدادمحور XML استفاده می‌کند. می‌توان داده‌های XML را به‌صورت افزایشی با متد feed() به آن داد و رویدادهای تجزیه به یک API فشاری (push API) تبدیل می‌شوند — با فراخوانی کال‌بک‌ها روی شیء target. اگر target حذف شود، از TreeBuilder استاندارد استفاده می‌شود. اگر encoding [1] داده شود، مقدار آن، کدگذاری مشخص‌شده در پرونده XML را نادیده می‌گیرد.

تغییر یافته در نسخه‌ی 3.8: پارامترها اکنون فقط کلیدواژه‌ای هستند. آرگومان html دیگر پشتیبانی نمی‌شود.

close()¶

وارد کردن داده به پارسر را به پایان می‌رساند. نتیجه‌ی فراخوانی متد close() برای target ارسال‌شده در هنگام ساخت را برمی‌گرداند؛ به‌طور پیش‌فرض، این المان سند سطح بالا است.

feed(data)¶

داده‌ها را به پارسر تغذیه می‌کند. data یک رشته یا داده‌ی کدگذاری‌شده (bytes یا یک شیء شبه‌بایت) است.

flush()¶

تجزیه‌ی هرگونه داده‌ی تجزیه‌نشده‌ای که پیش‌تر وارد شده است را راه‌اندازی می‌کند، که می‌تواند برای اطمینان از بازخورد فوری‌تر به کار رود، به‌ویژه با Expat >=2.6.0. پیاده‌سازی flush() تعویق تجزیه‌ی مجدد در Expat را به‌طور موقت غیرفعال می‌کند (اگر در حال حاضر فعال باشد) و یک تجزیه‌ی مجدد را راه‌اندازی می‌کند. غیرفعال‌سازی تعویق تجزیه‌ی مجدد پیامدهای امنیتی دارد؛ لطفاً برای جزئیات xml.parsers.expat.xmlparser.SetReparseDeferralEnabled() را ببینید.

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

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

XMLParser.feed() برای هر برچسب باز، متد start(tag, attrs_dict) از target و برای هر برچسب بسته، متد end(tag) آن را فراخوانی می‌کند، و داده با متد data(data) پردازش می‌شود. برای دیگر متدهای کال‌بک پشتیبانی‌شده، کلاس TreeBuilder را ببینید. XMLParser.close() متد close() از target را فراخوانی می‌کند. می‌توان از XMLParser نه فقط برای ساختن ساختار درختی استفاده کرد. این مثالی برای شمارش بیشینه عمق یک پرونده XML است:

>>> from xml.etree.ElementTree import XMLParser
>>> class MaxDepth:                     # The target object of the parser
...     maxDepth = 0
...     depth = 0
...     def start(self, tag, attrib):   # Called for each opening tag.
...         self.depth += 1
...         if self.depth > self.maxDepth:
...             self.maxDepth = self.depth
...     def end(self, tag):             # Called for each closing tag.
...         self.depth -= 1
...     def data(self, data):
...         pass            # We do not need to do anything with data.
...     def close(self):    # Called when all data has been parsed.
...         return self.maxDepth
...
>>> target = MaxDepth()
>>> parser = XMLParser(target=target)
>>> exampleXml = """
... <a>
...   <b>
...   </b>
...   <b>
...     <c>
...       <d>
...       </d>
...     </c>
...   </b>
... </a>"""
>>> parser.feed(exampleXml)
>>> parser.close()
4

اشیای XMLPullParser¶

class xml.etree.ElementTree.XMLPullParser(events=None)¶

یک پارسر کششی (pull parser) مناسب برای برنامه‌های غیرمسدودکننده. API سمت ورودی آن مشابه API XMLParser است، اما به‌جای فرستادن فراخوانی‌ها به یک هدف کال‌بک، XMLPullParser یک فهرست درونی از رویدادهای تجزیه را جمع‌آوری می‌کند و به کاربر اجازه می‌دهد از آن بخواند. events دنباله‌ای از رویدادها برای گزارش‌دهی است. رویدادهای پشتیبانی‌شده رشته‌های "start"، "end"، "comment"، "pi"، "start-ns" و "end-ns" هستند (رویدادهای "ns" برای دریافت اطلاعات دقیق فضای نام استفاده می‌شوند). اگر events حذف شود، فقط رویدادهای "end" گزارش می‌شوند.

feed(data)¶

داده‌ی داده‌شده را به پارسر می‌دهد. data یک رشته یا داده‌ی کدگذاری‌شده است (bytes یا یک شیء شبه‌بایت).

flush()¶

تجزیه‌ی هرگونه داده‌ی تجزیه‌نشده‌ای که پیش‌تر وارد شده است را راه‌اندازی می‌کند، که می‌تواند برای اطمینان از بازخورد فوری‌تر به کار رود، به‌ویژه با Expat >=2.6.0. پیاده‌سازی flush() تعویق تجزیه‌ی مجدد در Expat را به‌طور موقت غیرفعال می‌کند (اگر در حال حاضر فعال باشد) و یک تجزیه‌ی مجدد را راه‌اندازی می‌کند. غیرفعال‌سازی تعویق تجزیه‌ی مجدد پیامدهای امنیتی دارد؛ لطفاً برای جزئیات xml.parsers.expat.xmlparser.SetReparseDeferralEnabled() را ببینید.

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

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

close()¶

به پارسر اعلام می‌کند که جریان داده به پایان رسیده است. برخلاف XMLParser.close()، این متد همیشه None را برمی‌گرداند. هر رویدادی که هنوز در زمان بسته شدن پارسر دریافت‌نشده باشد، همچنان می‌تواند با read_events() خوانده شود.

read_events()¶

یک پیمایش‌گر بر رویدادهایی برمی‌گرداند که در داده‌های واردشده به پارسر مشاهده شده‌اند. این پیمایش‌گر جفت‌های (event, elem) را تولید می‌کند، که در آن event رشته‌ای است که نوع رویداد را نشان می‌دهد (برای مثال "end") و elem شیء Element مشاهده‌شده، یا مقدار زمینه‌ای دیگر به شرح زیر است.

• start، end: المان جاری.

• comment، pi: کامنت / دستور پردازش جاری

• start-ns: یک تاپل (prefix, uri) که نگاشت فضای نام اعلام‌شده را نام‌گذاری می‌کند.

• end-ns: None (این ممکن است در نسخه‌ای آینده تغییر کند)

رویدادهای ارائه‌شده در یک فراخوانی قبلی از read_events() دوباره تولید نخواهند شد. رویدادها تنها زمانی از صف داخلی مصرف می‌شوند که از پیمایش‌گر دریافت شوند؛ بنابراین چندین خواننده که به‌صورت موازی روی پیمایش‌گرهای به‌دست‌آمده از read_events() تکرار می‌کنند، نتایج غیرقابل‌پیش‌بینی خواهند داشت.

نکته

XMLPullParser فقط تضمین می‌کند که هنگام انتشار یک رویداد "start"، نویسه‌ی ">" از یک برچسب شروع را دیده است، بنابراین ویژگی‌ها تعریف‌شده‌اند، اما محتوای ویژگی‌های text و tail در آن نقطه تعریف‌نشده است. همین موضوع در مورد عناصر فرزند نیز صدق می‌کند؛ ممکن است وجود داشته باشند یا نداشته باشند.

اگر به یک المان کاملاً پرشده نیاز دارید، در عوض به دنبال رویدادهای «end» بگردید.

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

تغییر یافته در نسخه‌ی 3.8: رویدادهای comment و pi افزوده شدند.

استثناها¶

class xml.etree.ElementTree.ParseError¶

خطای تجزیه XML، که توسط متدهای مختلف تجزیه در این ماژول هنگام شکست در تجزیه پرتاب می‌شود. نمایش رشته‌ای یک نمونه از این استثنا شامل یک پیام خطای کاربرپسند خواهد بود. علاوه بر این، ویژگی‌های زیر در دسترس خواهند بود:

code¶

یک کد خطای عددی از پارسر expat. برای فهرست کدهای خطا و معانی آن‌ها، مستندات xml.parsers.expat را ببینید.

position¶

یک تاپل از شماره‌های line و column، که محل وقوع خطا را مشخص می‌کند.

پانویس‌ها