pandas.read_xml

pandas.read_xml(path_or_buffer, xpath='./*', namespaces=None, elems_only=False, attrs_only=False, names=None, dtype=None, converters=None, parse_dates=None, encoding='utf-8', parser='lxml', stylesheet=None, iterparse=None, compression='infer', storage_options=None)[source]

Считывание XML-документа в объект DataFrame.

Новая функция в версии 1.3.0.

Параметры

path_or_buffer:str, объект пути или файлоподобный объект

Строка, объект пути (реализующий os.PathLike[str]), или файлоподобный объект, реализующий функцию read(). Строка может быть любой допустимой строкой XML или путём. Строка также может быть URL. Допустимые схемы URL включают http, ftp, s3 и file.

xpath:str, необязательно, по умолчанию ‘./*’

XPath для разбора требуемого набора узлов для миграции в DataFrame. XPath должен возвращать коллекцию элементов, а не отдельный элемент. Примечание: парсер etree поддерживает ограниченные выражения XPath. Для более сложных XPath используйте lxml, который требует установки.

namespaces:dict, необязательно

Определённые в XML-документе пространства имён в виде словарей, где ключ — префикс пространства имён, а значение — URI. Нет необходимости включать все пространства имён в XML, только те, которые используются в выражении xpath. Примечание: если XML-документ использует пространство имён по умолчанию, обозначенное как xmlns=’<URI>’ без префикса, необходимо присвоить любое временное имя пространства имён, например, ‘doc’, URI для разбора подлежащих узлов и/или атрибутов. Например,

namespaces = {"doc": "https://example.com"}

elems_only:bool, необязательно, по умолчанию False

Разбирать только дочерние элементы в указанном xpath. По умолчанию возвращаются все дочерние элементы и непустые текстовые узлы.

attrs_only:bool, необязательно, по умолчанию False

Разбирать только атрибуты в указанном xpath. По умолчанию возвращаются все атрибуты.

names:list-like, необязательно

Имена столбцов для DataFrame обработанных XML-данных. Используйте этот параметр для переименования исходных имён элементов и различения элементов и атрибутов с одинаковыми именами.

dtype:Имя типа или словарь столбец -> тип, необязательно

Тип данных для данных или столбцов. Например, {‘a’: np.float64, ‘b’: np.int32, ‘c’: ‘Int64’}. Используйте str или object вместе с соответствующими настройками na_values, чтобы сохранить и не интерпретировать тип данных. Если указаны конвертеры, они будут применены ВМЕСТО преобразования типа данных.

Новая функция в версии 1.5.0.

converters:dict, необязательно

Словарь функций для преобразования значений в определённых столбцах. Ключи могут быть целыми числами или метками столбцов.

Новая функция в версии 1.5.0.

parse_dates:bool или список целых чисел или имён или список списков или словарь, по умолчанию False

Идентификаторы для разбора индекса или столбцов в дату и время. Поведение следующее:

• булево. Если True -> попытка разбора индекса.

• список целых чисел или имён. Например, если [1, 2, 3] -> попытка разбора столбцов 1, 2, 3 каждого как отдельного столбца даты.

• список списков. Например, если [[1, 3]] -> объединение столбцов 1 и 3 и разбор как одного столбца даты.

• словарь, например, {‘foo’ : [1, 3]} -> разбор столбцов 1, 3 как даты и присвоение результата ‘foo’

Новая функция в версии 1.5.0.

encoding:str, необязательно, по умолчанию ‘utf-8’

Кодировка XML-документа.

parser:{‘lxml’,’etree’}, по умолчанию ‘lxml’

Модуль парсера для извлечения данных. Поддерживаются только ‘lxml’ и ‘etree’. С ‘lxml’ поддерживаются более сложные поиски XPath и возможность использования XSLT-стилей.

stylesheet:str, объект пути или файлоподобный объект

URL, файлоподобный объект или строка, содержащая скрипт XSLT. Этот стилизованный лист должен сгладить сложные, глубоко вложенные XML-документы для более лёгкого разбора. Чтобы использовать эту функцию, должен быть установлен модуль lxml, а ‘lxml’ указан как parser. xpath должен ссылаться на узлы преобразованного XML-документа, сгенерированного после преобразования XSLT, а не на исходный XML-документ. В настоящее время поддерживаются только скрипты XSLT 1.0, а не более поздние версии.

iterparse:dict, необязательно

Узлы или атрибуты для извлечения при итерационном разборе XML-документа в виде словаря, где ключ — имя повторяющегося элемента, а значение — список элементов или имён атрибутов, являющихся потомками повторяющегося элемента. Примечание: если этот параметр используется, он заменит xpath разбор и в отличие от xpath, потомки не должны быть связаны друг с другом, а могут находиться где угодно в документе под повторяющимся элементом. Этот метод, экономичный с точки зрения памяти, должен использоваться для очень больших XML-файлов (500 МБ, 1 ГБ или более 5 ГБ). Например,

iterparse = {"row_element": ["child_elem", "attr", "grandchild_elem"]}

Новая функция в версии 1.5.0.

compression:str или dict, по умолчанию ‘infer’

Для динамического сжатия данных на диске. Если ‘infer’ и ‘path_or_buffer’ — путь, обнаружить сжатие из следующих расширений: ‘.gz’, ‘.bz2’, ‘.zip’, ‘.xz’, ‘.zst’, ‘.tar’, ‘.tar.gz’, ‘.tar.xz’ или ‘.tar.bz2’ (в противном случае сжатия нет). Если используется ‘zip’ или ‘tar’, ZIP-файл должен содержать только один файл данных для чтения. Установите в None для отказа от сжатия. Также может быть словарь с ключом 'method', установленным в один из {'zip', 'gzip', 'bz2', 'zstd', 'tar'} и другие пары ключ-значение передаются в zipfile.ZipFile, gzip.GzipFile, bz2.BZ2File, zstandard.ZstdDecompressor или tarfile.TarFile, соответственно. Например, следующее можно передать для сжатия Zstandard с помощью пользовательского словаря сжатия: compression={'method': 'zstd', 'dict_data': my_compression_dict}.

Новая функция в версии 1.5.0: Добавлена поддержка файлов .tar.

Изменено в версии 1.4.0: Поддержка Zstandard.

storage_options:dict, необязательно

Дополнительные параметры, которые имеют смысл для определённого подключения к хранилищу, например, хост, порт, имя пользователя, пароль и т. д. Для HTTP(S) URL пары ключ-значение передаются в urllib.request.Request в качестве параметров заголовка. Для других URL (например, начинающихся с “s3://”, и “gcs://”) пары ключ-значение передаются в fsspec.open. Подробнее см. fsspec и urllib, а примеры параметров хранилища см. здесь.

Возвращает

df

DataFrame.

См. также

read_json

Преобразование JSON-строки в объект pandas.

read_html

Чтение HTML-таблиц в список объектов DataFrame.

Примечания

Этот метод лучше всего подходит для импорта поверхностных XML-документов в следующем формате, который идеально подходит для двух измерений DataFrame (строка по столбцу).

<root>
    <row>
      <column1>data</column1>
      <column2>data</column2>
      <column3>data</column3>
      ...
   </row>
   <row>
      ...
   </row>
   ...
</root>

В качестве формата файлов XML-документы могут быть спроектированы любым способом, включая расположение элементов и атрибутов, при условии соответствия спецификациям W3C. Поэтому этот метод является удобной обработкой конкретного более плоского дизайна и не всех возможных структур XML.

Однако, для более сложных XML-документов, stylesheet позволяет временно перепроектировать исходный документ с помощью XSLT (специальный язык) для получения более плоской версии для миграции в DataFrame.

Эта функция всегда возвращает один DataFrame или вызывает исключения из-за проблем с XML-документом, xpath, или другими параметрами.

Дополнительную информацию об использовании этого метода для разбора XML-файлов в DataFrame см. в документации read_xml в разделе IO документации.

Примеры

>>> xml = '''<?xml version='1.0' encoding='utf-8'?>
... <data xmlns="http://example.com">
...  <row>
...    <shape>square</shape>
...    <degrees>360</degrees>
...    <sides>4.0</sides>
...  </row>
...  <row>
...    <shape>circle</shape>
...    <degrees>360</degrees>
...    <sides/>
...  </row>
...  <row>
...    <shape>triangle</shape>
...    <degrees>180</degrees>
...    <sides>3.0</sides>
...  </row>
... </data>'''

>>> df = pd.read_xml(xml)
>>> df
      shape  degrees  sides
0    square      360    4.0
1    circle      360    NaN
2  triangle      180    3.0

>>> xml = '''<?xml version='1.0' encoding='utf-8'?>
... <data>
...   <row shape="square" degrees="360" sides="4.0"/>
...   <row shape="circle" degrees="360"/>
...   <row shape="triangle" degrees="180" sides="3.0"/>
... </data>'''

>>> df = pd.read_xml(xml, xpath=".//row")
>>> df
      shape  degrees  sides
0    square      360    4.0
1    circle      360    NaN
2  triangle      180    3.0

>>> xml = '''<?xml version='1.0' encoding='utf-8'?>
... <doc:data xmlns:doc="https://example.com">
...   <doc:row>
...     <doc:shape>square</doc:shape>
...     <doc:degrees>360</doc:degrees>
...     <doc:sides>4.0</doc:sides>
...   </doc:row>
...   <doc:row>
...     <doc:shape>circle</doc:shape>
...     <doc:degrees>360</doc:degrees>
...     <doc:sides/>
...   </doc:row>
...   <doc:row>
...     <doc:shape>triangle</doc:shape>
...     <doc:degrees>180</doc:degrees>
...     <doc:sides>3.0</doc:sides>
...   </doc:row>
... </doc:data>'''

>>> df = pd.read_xml(xml,
...                  xpath="//doc:row",
...                  namespaces={"doc": "https://example.com"})
>>> df
      shape  degrees  sides
0    square      360    4.0
1    circle      360    NaN
2  triangle      180    3.0