`xml.etree.ElementTree` --- API اکس‌ام‌ال ElementTree¶

کد منبع: Lib/xml/etree/ElementTree.py

ماژول xml.etree.ElementTree یک API ساده و کارآمد را برای تجزیه و ایجاد داده‌های XML پیاده‌سازی می‌کند.

تغییر یافته در نسخه‌ی 3.3: این ماژول هر زمان که پیاده‌سازی سریعی در دسترس باشد، از آن استفاده خواهد کرد.

منسوخ شده از نسخه‌ی 3.3: The xml.etree.cElementTree alias of this module is deprecated.

توجه

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

آموزش¶

این یک آموزش کوتاه برای استفاده از xml.etree.ElementTree (به‌اختصار ET) است. هدف، نمایش برخی از اجزای سازنده و مفاهیم پایه این ماژول است.

درخت 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'

توجه

همه‌ی عناصر ورودی XML در نهایت به عناصر درخت تجزیه‌شده تبدیل نخواهند شد. در حال حاضر، این ماژول از هرگونه کامنت XML، دستورالعمل پردازش و اعلان نوع سند در ورودی چشم‌پوشی می‌کند. با این حال، درخت‌هایی که به‌جای تجزیه از متن XML، با استفاده از API این ماژول ساخته می‌شوند، می‌توانند شامل کامنت‌ها و دستورالعمل‌های پردازش باشند؛ این موارد هنگام تولید خروجی XML گنجانده خواهند شد. می‌توان با ارسال یک نمونه سفارشی از TreeBuilder به سازنده‌ی XMLParser به اعلان نوع سند دسترسی پیدا کرد.

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 از یک سوکت دریافت می‌شوند یا به‌صورت تدریجی از یک دستگاه ذخیره‌سازی خوانده می‌شوند. در چنین مواردی، خواندن‌های مسدودکننده غیرقابل‌قبول هستند.

Because it's so flexible, XMLPullParser can be inconvenient to use for simpler use-cases. If you don't mind your application blocking on reading XML data but would still like to have incremental parsing capabilities, take a look at iterparse().

Note that both parsers build the tree incrementally: it is not freed incrementally, so every parsed element is kept until the whole document is read. To keep the memory usage low, get rid of the data which is not needed any more.

If the processed elements are large, it is enough to clear them. This works wherever they are in the tree, but the emptied elements are left in it:

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

If an element has a large number of children, remove the processed children from it:

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)

These examples are not universal, they only give an idea for two common cases. If you do not need a tree at all, parse with XMLParser and a custom target instead; it is not built then, and nothing has to be removed.

هرگاه بازخورد فوری از طریق رویدادها مطلوب باشد، فراخوانی متد 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¶

این ماژول پشتیبانی محدودی از عبارات XPath برای مکان‌یابی عناصر در یک درخت ارائه می‌دهد. هدف، پشتیبانی از زیرمجموعه کوچکی از سینتکس خلاصه‌شده است؛ یک موتور کامل XPath خارج از محدوده این ماژول است.

مثال¶

در اینجا مثالی آمده است که برخی از قابلیت‌های 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¶

سینتکس	معنی
`tag`	تمام عناصر فرزند با برچسب داده‌شده را انتخاب می‌کند. برای مثال، `spam` تمام عناصر فرزند با نام `spam` را انتخاب می‌کند، و `spam/egg` تمام نوه‌ها با نام `egg` را در میان تمام عناصر فرزند با نام `spam` انتخاب می‌کند. `{namespace}` تمام برچسب‌ها را در فضای نام داده‌شده انتخاب می‌کند، `{}spam` برچسب‌هایی با نام `spam` را در هر فضای نامی (یا بدون فضای نام) انتخاب می‌کند، و `{}*` فقط برچسب‌هایی را انتخاب می‌کند که در فضای نامی نیستند. تغییر یافته در نسخه‌ی 3.8: پشتیبانی از نویسه‌های جایگزین ستاره‌ای (star-wildcards) افزوده شد.
`*`	همه عناصر فرزند، از جمله کامنت‌ها و دستورالعمل‌های پردازشی را انتخاب می‌کند. برای مثال، `*/egg` همه نوه‌هایی با نام `egg` را انتخاب می‌کند.
`.`	گره فعلی را انتخاب می‌کند. این عمدتاً در ابتدای مسیر مفید است، تا نشان دهد که مسیر نسبی است.
`//`	تمام زیرعناصر را در همه‌ی سطوح زیر عنصر فعلی انتخاب می‌کند. برای مثال، `.//egg` تمام عناصر `egg` را در کل درخت انتخاب می‌کند.
`..`	عنصر والد را انتخاب می‌کند. اگر مسیر برای رسیدن به اجداد عنصر آغازین (عنصری که `find` روی آن فراخوانی شده است) تلاش کند، `None` را برمی‌گرداند.
`[@attrib]`	تمام عناصری که دارای ویژگی داده‌شده هستند را انتخاب می‌کند.
`[@attrib='value']`	تمام المان‌هایی را انتخاب می‌کند که ویژگی داده‌شده دارای مقدار داده‌شده است. مقدار نمی‌تواند شامل علامت نقل‌قول باشد.
`[@attrib!='value']`	تمام المان‌هایی را انتخاب می‌کند که صفت داده‌شده‌ی آن‌ها فاقد مقدار داده‌شده است. مقدار نمی‌تواند شامل علامت نقل‌قول باشد. اضافه شده در نسخه‌ی 3.10.
`[tag]`	تمام عناصری را انتخاب می‌کند که فرزندی به نام `tag` دارند. تنها فرزندان مستقیم پشتیبانی می‌شوند.
`[.='text']`	تمام المان‌هایی را انتخاب می‌کند که محتوای متنی کامل آن‌ها، از جمله نوادگان، برابر با `text` داده‌شده باشد. اضافه شده در نسخه‌ی 3.7.
`[.!='text']`	تمام المان‌هایی را انتخاب می‌کند که محتوای متنی کامل آن‌ها، از جمله نوادگان، با `text` داده‌شده برابر نیست. اضافه شده در نسخه‌ی 3.10.
`[tag='text']`	تمام عناصری را انتخاب می‌کند که دارای فرزندی به نام `tag` هستند و محتوای متنی کامل آن فرزند، شامل نوادگان، برابر با `text` داده‌شده باشد.
`[tag!='text']`	تمام المان‌هایی را انتخاب می‌کند که فرزندی به نام `tag` دارند و محتوای متنی کامل آن، شامل نوادگانش، با `text` داده‌شده برابر نیست. اضافه شده در نسخه‌ی 3.10.
`[position]`	تمام المان‌هایی را انتخاب می‌کند که در موقعیت داده‌شده قرار دارند. موقعیت می‌تواند یک عدد صحیح باشد (۱ نخستین موقعیت است)، عبارت `last()` (برای آخرین موقعیت)، یا موقعیتی نسبت به آخرین موقعیت (برای مثال `last()-1`).

عبارت‌های محمول (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 تنظیم شود تا فضای سفید پیش و پس از محتوای متنی حذف شود
(پیش‌فرض: false)
rewrite_prefixes: روی true تنظیم کنید تا پیشوندهای فضای نام با "n{number}" جایگزین شوند
(پیش‌فرض: false)
qname_aware_tags: مجموعه‌ای از نام برچسب‌های آگاه از qname که در آن‌ها پیشوندها
باید در محتوای متنی جایگزین شود (پیش‌فرض: خالی)
qname_aware_attrs: مجموعه‌ای از نام ویژگی‌های آگاه از qname که در آن‌ها پیشوندها
باید در محتوای متنی جایگزین شود (پیش‌فرض: خالی)
exclude_attrs: مجموعه‌ای از نام ویژگی‌هایی که نباید سریال‌سازی شوند
exclude_tags: مجموعه‌ای از نام برچسب‌ها که نباید سریال‌سازی شوند

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

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

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

Comment element factory. This factory function creates a special element that will be serialized as an XML comment by the standard serializer. text is a string containing the comment string. Returns an element instance representing a comment.

توجه داشته باشید که 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)¶

Parses an XML section into an element tree incrementally, and reports what's going on to the user. source is a filename or file object containing XML data. events is a sequence of events to report back. The supported events are the strings "start", "end", "comment", "pi", "start-ns" and "end-ns" (the "ns" events are used to get detailed namespace information). If events is omitted, only "end" events are reported. parser is an optional parser instance. If not given, the standard XMLParser parser is used. parser must be an instance of XMLParser or its subclass and can only use the default TreeBuilder as a target. Returns an iterator providing (event, elem) pairs; it has a root attribute that references the root element of the resulting XML tree once source is fully read. The iterator has the close() method that closes the internal file object if source is a filename.

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

The tree is only built incrementally, it is not freed incrementally: every parsed element is kept until the whole document is read. See API کششی (Pull API) برای تجزیه‌ی غیرمسدودکننده for how to keep the memory usage low.

توجه

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

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

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

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

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

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 is the parent element. tag is the subelement name. attrib is an optional dictionary, containing element attributes. extra contains additional attributes, given as keyword arguments. Returns an element instance.

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¶

این ماژول پشتیبانی محدودی از دایرکتیوهای XInclude را از طریق ماژول کمکی xml.etree.ElementInclude فراهم می‌کند. می‌توان از این ماژول برای درج زیردرخت‌ها و رشته‌های متنی در درخت‌های المان، بر اساس اطلاعات موجود در درخت استفاده کرد.

مثال¶

در اینجا مثالی آمده است که استفاده از ماژول 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 is the element name. attrib is an optional dictionary, containing element attributes. extra contains additional attributes, given as keyword arguments.

The element name and the attribute names and values are strings or QName instances, and the text and the tail are strings or None. The element name can also be Comment() or ProcessingInstruction(), which are used for special elements. If it is None, the element itself is not serialized: only its text and its children are written, and its attributes are ignored. This can be used for a fragment which contains several elements. With method="html" the attribute value can also be None, which produces an empty attribute (such as checked). Other objects can be stored in the tree, but they cannot be serialized.

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()¶: Returns the element attributes as (name, value) pairs.

keys()¶: Returns the element attribute names.

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)¶: Adds text to the current element. data is a string.

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)¶: Feeds data to the parser. data is a string or encoded data (bytes or a bytes-like object).

flush()¶

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

توجه داشته باشید که flush() به‌عنوان یک اصلاح امنیتی به برخی نسخه‌های پیشین CPython بک‌پورت شده است . در صورت استفاده در کدی که روی نسخه‌های گوناگون پایتون اجرا می‌شود، دسترس‌پذیری flush() را با استفاده از 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)¶: Feed the given data to the parser. data is a string or encoded data (bytes or a bytes-like object).

flush()¶

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

توجه داشته باشید که flush() به‌عنوان یک اصلاح امنیتی به برخی نسخه‌های پیشین CPython بک‌پورت شده است . در صورت استفاده در کدی که روی نسخه‌های گوناگون پایتون اجرا می‌شود، دسترس‌پذیری flush() را با استفاده از 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، که محل وقوع خطا را مشخص می‌کند.

پانویس‌ها

`xml.etree.ElementTree` --- API اکس‌ام‌ال ElementTree¶

آموزش¶

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

تجزیه‌ی XML¶

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

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

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

ساخت اسناد XML¶

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

پشتیبانی از XPath¶

مثال¶

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

مرجع¶

توابع¶

پشتیبانی از XInclude¶

مثال¶

مرجع¶

توابع¶

اشیای عنصر¶

اشیاء ElementTree¶

اشیاء QName¶

اشیای TreeBuilder¶

اشیاء XMLParser¶

اشیای XMLPullParser¶

استثناها¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه

xml.etree.ElementTree --- API اکس‌ام‌ال ElementTree¶

آموزش¶

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

تجزیه‌ی XML¶

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

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

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

ساخت اسناد XML¶

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

پشتیبانی از XPath¶

مثال¶

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

مرجع¶

توابع¶

پشتیبانی از XInclude¶

مثال¶

مرجع¶

توابع¶

اشیای عنصر¶

اشیاء ElementTree¶

اشیاء QName¶

اشیای TreeBuilder¶

اشیاء XMLParser¶

اشیای XMLPullParser¶

استثناها¶

`xml.etree.ElementTree` --- API اکس‌ام‌ال ElementTree¶