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, dtype_backend=_NoDefault.no_default)[source]

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

Новое в версии 1.3.0.

Параметры:

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

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

Устаревшее с версии 2.1.0: Передача XML-литеральных строк устарела. Вместо этого оберните литеральный XML-вход в io.StringIO или io.BytesIO.

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:последовательность, необязательно

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

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

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

Новое в версии 1.5.0.

converters:словарь, необязательно

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

Новое в версии 1.5.0.

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

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

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

• список int или имен. Например, если [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 или словарь, по умолчанию ‘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', 'xz', 'tar'}, а другие пары ключ-значение передаются в zipfile.ZipFile, gzip.GzipFile, bz2.BZ2File, zstandard.ZstdDecompressor, lzma.LZMAFile или tarfile.TarFile, соответственно. Например, для сжатия Zstandard с использованием пользовательского словаря сжатия можно передать: compression={'method': 'zstd', 'dict_data': my_compression_dict}.

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

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

storage_options:словарь, необязательно

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

dtype_backend:{‘numpy_nullable’, ‘pyarrow’}, по умолчанию ‘numpy_nullable’

Применяемый к результирующему DataFrame backend-тип данных (еще экспериментально). Поведение следующее:

• "numpy_nullable": возвращает DataFrame с поддержкой nullable-dtype (по умолчанию).

• "pyarrow": возвращает DataFrame с поддержкой pyarrow-nullable ArrowDtype.

Новое в версии 2.0.

Возвращает:

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, или другими параметрами.

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

Примеры

>>> from io import StringIO
>>> 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(StringIO(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(StringIO(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(StringIO(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

>>> xml_data = '''
...         <data>
...            <row>
...               <index>0</index>
...               <a>1</a>
...               <b>2.5</b>
...               <c>True</c>
...               <d>a</d>
...               <e>2019-12-31 00:00:00</e>
...            </row>
...            <row>
...               <index>1</index>
...               <b>4.5</b>
...               <c>False</c>
...               <d>b</d>
...               <e>2019-12-31 00:00:00</e>
...            </row>
...         </data>
...         '''

>>> df = pd.read_xml(StringIO(xml_data),
...                  dtype_backend="numpy_nullable",
...                  parse_dates=["e"])
>>> df
   index     a    b      c  d          e
0      0     1  2.5   True  a 2019-12-31
1      1  <NA>  4.5  False  b 2019-12-31