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=<no_default>)[исходный код]

Считывает 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>’ без префикса, необходимо назначить URI любой временный префикс пространства имен, например ‘doc’, чтобы разобрать содержащиеся в нем узлы и/или атрибуты. Например:

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

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

Добавлено в версии 1.5.0.

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

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

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

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

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

• dict, например {‘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’ — объект типа path, сжатие определяется по следующим расширениям: ‘.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:dict, необязательно

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

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

Тип данных серверной части, применяемый к результирующему объекту DataFrame (функция все еще является экспериментальной). Поведение следующее:

• "numpy_nullable": возвращает DataFrame с типами данных nullable (по умолчанию).

• "pyarrow": возвращает DataFrame с типами ArrowDtype nullable на основе pyarrow.

Добавлено в версии 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 или другими параметрами.

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

Примеры

>>> 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