|
|
""" |
|
|
:mod:``pandas.io.xml`` is a module for reading XML. |
|
|
""" |
|
|
|
|
|
from __future__ import annotations |
|
|
|
|
|
import io |
|
|
from os import PathLike |
|
|
from typing import ( |
|
|
TYPE_CHECKING, |
|
|
Any, |
|
|
Callable, |
|
|
) |
|
|
import warnings |
|
|
|
|
|
from pandas._libs import lib |
|
|
from pandas.compat._optional import import_optional_dependency |
|
|
from pandas.errors import ( |
|
|
AbstractMethodError, |
|
|
ParserError, |
|
|
) |
|
|
from pandas.util._decorators import doc |
|
|
from pandas.util._exceptions import find_stack_level |
|
|
from pandas.util._validators import check_dtype_backend |
|
|
|
|
|
from pandas.core.dtypes.common import is_list_like |
|
|
|
|
|
from pandas.core.shared_docs import _shared_docs |
|
|
|
|
|
from pandas.io.common import ( |
|
|
file_exists, |
|
|
get_handle, |
|
|
infer_compression, |
|
|
is_file_like, |
|
|
is_fsspec_url, |
|
|
is_url, |
|
|
stringify_path, |
|
|
) |
|
|
from pandas.io.parsers import TextParser |
|
|
|
|
|
if TYPE_CHECKING: |
|
|
from collections.abc import Sequence |
|
|
from xml.etree.ElementTree import Element |
|
|
|
|
|
from lxml import etree |
|
|
|
|
|
from pandas._typing import ( |
|
|
CompressionOptions, |
|
|
ConvertersArg, |
|
|
DtypeArg, |
|
|
DtypeBackend, |
|
|
FilePath, |
|
|
ParseDatesArg, |
|
|
ReadBuffer, |
|
|
StorageOptions, |
|
|
XMLParsers, |
|
|
) |
|
|
|
|
|
from pandas import DataFrame |
|
|
|
|
|
|
|
|
@doc( |
|
|
storage_options=_shared_docs["storage_options"], |
|
|
decompression_options=_shared_docs["decompression_options"] % "path_or_buffer", |
|
|
) |
|
|
class _XMLFrameParser: |
|
|
""" |
|
|
Internal subclass to parse XML into DataFrames. |
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
path_or_buffer : a valid JSON ``str``, path object or file-like object |
|
|
Any valid string path is acceptable. The string could be a URL. Valid |
|
|
URL schemes include http, ftp, s3, and file. |
|
|
|
|
|
xpath : str or regex |
|
|
The ``XPath`` expression to parse required set of nodes for |
|
|
migration to :class:`~pandas.DataFrame`. ``etree`` supports limited ``XPath``. |
|
|
|
|
|
namespaces : dict |
|
|
The namespaces defined in XML document (``xmlns:namespace='URI'``) |
|
|
as dicts with key being namespace and value the URI. |
|
|
|
|
|
elems_only : bool |
|
|
Parse only the child elements at the specified ``xpath``. |
|
|
|
|
|
attrs_only : bool |
|
|
Parse only the attributes at the specified ``xpath``. |
|
|
|
|
|
names : list |
|
|
Column names for :class:`~pandas.DataFrame` of parsed XML data. |
|
|
|
|
|
dtype : dict |
|
|
Data type for data or columns. E.g. {{'a': np.float64, |
|
|
'b': np.int32, 'c': 'Int64'}} |
|
|
|
|
|
.. versionadded:: 1.5.0 |
|
|
|
|
|
converters : dict, optional |
|
|
Dict of functions for converting values in certain columns. Keys can |
|
|
either be integers or column labels. |
|
|
|
|
|
.. versionadded:: 1.5.0 |
|
|
|
|
|
parse_dates : bool or list of int or names or list of lists or dict |
|
|
Converts either index or select columns to datetimes |
|
|
|
|
|
.. versionadded:: 1.5.0 |
|
|
|
|
|
encoding : str |
|
|
Encoding of xml object or document. |
|
|
|
|
|
stylesheet : str or file-like |
|
|
URL, file, file-like object, or a raw string containing XSLT, |
|
|
``etree`` does not support XSLT but retained for consistency. |
|
|
|
|
|
iterparse : dict, optional |
|
|
Dict with row element as key and list of descendant elements |
|
|
and/or attributes as value to be retrieved in iterparsing of |
|
|
XML document. |
|
|
|
|
|
.. versionadded:: 1.5.0 |
|
|
|
|
|
{decompression_options} |
|
|
|
|
|
.. versionchanged:: 1.4.0 Zstandard support. |
|
|
|
|
|
{storage_options} |
|
|
|
|
|
See also |
|
|
-------- |
|
|
pandas.io.xml._EtreeFrameParser |
|
|
pandas.io.xml._LxmlFrameParser |
|
|
|
|
|
Notes |
|
|
----- |
|
|
To subclass this class effectively you must override the following methods:` |
|
|
* :func:`parse_data` |
|
|
* :func:`_parse_nodes` |
|
|
* :func:`_iterparse_nodes` |
|
|
* :func:`_parse_doc` |
|
|
* :func:`_validate_names` |
|
|
* :func:`_validate_path` |
|
|
|
|
|
|
|
|
See each method's respective documentation for details on their |
|
|
functionality. |
|
|
""" |
|
|
|
|
|
def __init__( |
|
|
self, |
|
|
path_or_buffer: FilePath | ReadBuffer[bytes] | ReadBuffer[str], |
|
|
xpath: str, |
|
|
namespaces: dict[str, str] | None, |
|
|
elems_only: bool, |
|
|
attrs_only: bool, |
|
|
names: Sequence[str] | None, |
|
|
dtype: DtypeArg | None, |
|
|
converters: ConvertersArg | None, |
|
|
parse_dates: ParseDatesArg | None, |
|
|
encoding: str | None, |
|
|
stylesheet: FilePath | ReadBuffer[bytes] | ReadBuffer[str] | None, |
|
|
iterparse: dict[str, list[str]] | None, |
|
|
compression: CompressionOptions, |
|
|
storage_options: StorageOptions, |
|
|
) -> None: |
|
|
self.path_or_buffer = path_or_buffer |
|
|
self.xpath = xpath |
|
|
self.namespaces = namespaces |
|
|
self.elems_only = elems_only |
|
|
self.attrs_only = attrs_only |
|
|
self.names = names |
|
|
self.dtype = dtype |
|
|
self.converters = converters |
|
|
self.parse_dates = parse_dates |
|
|
self.encoding = encoding |
|
|
self.stylesheet = stylesheet |
|
|
self.iterparse = iterparse |
|
|
self.is_style = None |
|
|
self.compression: CompressionOptions = compression |
|
|
self.storage_options = storage_options |
|
|
|
|
|
def parse_data(self) -> list[dict[str, str | None]]: |
|
|
""" |
|
|
Parse xml data. |
|
|
|
|
|
This method will call the other internal methods to |
|
|
validate ``xpath``, names, parse and return specific nodes. |
|
|
""" |
|
|
|
|
|
raise AbstractMethodError(self) |
|
|
|
|
|
def _parse_nodes(self, elems: list[Any]) -> list[dict[str, str | None]]: |
|
|
""" |
|
|
Parse xml nodes. |
|
|
|
|
|
This method will parse the children and attributes of elements |
|
|
in ``xpath``, conditionally for only elements, only attributes |
|
|
or both while optionally renaming node names. |
|
|
|
|
|
Raises |
|
|
------ |
|
|
ValueError |
|
|
* If only elements and only attributes are specified. |
|
|
|
|
|
Notes |
|
|
----- |
|
|
Namespace URIs will be removed from return node values. Also, |
|
|
elements with missing children or attributes compared to siblings |
|
|
will have optional keys filled with None values. |
|
|
""" |
|
|
|
|
|
dicts: list[dict[str, str | None]] |
|
|
|
|
|
if self.elems_only and self.attrs_only: |
|
|
raise ValueError("Either element or attributes can be parsed not both.") |
|
|
if self.elems_only: |
|
|
if self.names: |
|
|
dicts = [ |
|
|
{ |
|
|
**( |
|
|
{el.tag: el.text} |
|
|
if el.text and not el.text.isspace() |
|
|
else {} |
|
|
), |
|
|
**{ |
|
|
nm: ch.text if ch.text else None |
|
|
for nm, ch in zip(self.names, el.findall("*")) |
|
|
}, |
|
|
} |
|
|
for el in elems |
|
|
] |
|
|
else: |
|
|
dicts = [ |
|
|
{ch.tag: ch.text if ch.text else None for ch in el.findall("*")} |
|
|
for el in elems |
|
|
] |
|
|
|
|
|
elif self.attrs_only: |
|
|
dicts = [ |
|
|
{k: v if v else None for k, v in el.attrib.items()} for el in elems |
|
|
] |
|
|
|
|
|
elif self.names: |
|
|
dicts = [ |
|
|
{ |
|
|
**el.attrib, |
|
|
**({el.tag: el.text} if el.text and not el.text.isspace() else {}), |
|
|
**{ |
|
|
nm: ch.text if ch.text else None |
|
|
for nm, ch in zip(self.names, el.findall("*")) |
|
|
}, |
|
|
} |
|
|
for el in elems |
|
|
] |
|
|
|
|
|
else: |
|
|
dicts = [ |
|
|
{ |
|
|
**el.attrib, |
|
|
**({el.tag: el.text} if el.text and not el.text.isspace() else {}), |
|
|
**{ch.tag: ch.text if ch.text else None for ch in el.findall("*")}, |
|
|
} |
|
|
for el in elems |
|
|
] |
|
|
|
|
|
dicts = [ |
|
|
{k.split("}")[1] if "}" in k else k: v for k, v in d.items()} for d in dicts |
|
|
] |
|
|
|
|
|
keys = list(dict.fromkeys([k for d in dicts for k in d.keys()])) |
|
|
dicts = [{k: d[k] if k in d.keys() else None for k in keys} for d in dicts] |
|
|
|
|
|
if self.names: |
|
|
dicts = [dict(zip(self.names, d.values())) for d in dicts] |
|
|
|
|
|
return dicts |
|
|
|
|
|
def _iterparse_nodes(self, iterparse: Callable) -> list[dict[str, str | None]]: |
|
|
""" |
|
|
Iterparse xml nodes. |
|
|
|
|
|
This method will read in local disk, decompressed XML files for elements |
|
|
and underlying descendants using iterparse, a method to iterate through |
|
|
an XML tree without holding entire XML tree in memory. |
|
|
|
|
|
Raises |
|
|
------ |
|
|
TypeError |
|
|
* If ``iterparse`` is not a dict or its dict value is not list-like. |
|
|
ParserError |
|
|
* If ``path_or_buffer`` is not a physical file on disk or file-like object. |
|
|
* If no data is returned from selected items in ``iterparse``. |
|
|
|
|
|
Notes |
|
|
----- |
|
|
Namespace URIs will be removed from return node values. Also, |
|
|
elements with missing children or attributes in submitted list |
|
|
will have optional keys filled with None values. |
|
|
""" |
|
|
|
|
|
dicts: list[dict[str, str | None]] = [] |
|
|
row: dict[str, str | None] | None = None |
|
|
|
|
|
if not isinstance(self.iterparse, dict): |
|
|
raise TypeError( |
|
|
f"{type(self.iterparse).__name__} is not a valid type for iterparse" |
|
|
) |
|
|
|
|
|
row_node = next(iter(self.iterparse.keys())) if self.iterparse else "" |
|
|
if not is_list_like(self.iterparse[row_node]): |
|
|
raise TypeError( |
|
|
f"{type(self.iterparse[row_node])} is not a valid type " |
|
|
"for value in iterparse" |
|
|
) |
|
|
|
|
|
if (not hasattr(self.path_or_buffer, "read")) and ( |
|
|
not isinstance(self.path_or_buffer, (str, PathLike)) |
|
|
or is_url(self.path_or_buffer) |
|
|
or is_fsspec_url(self.path_or_buffer) |
|
|
or ( |
|
|
isinstance(self.path_or_buffer, str) |
|
|
and self.path_or_buffer.startswith(("<?xml", "<")) |
|
|
) |
|
|
or infer_compression(self.path_or_buffer, "infer") is not None |
|
|
): |
|
|
raise ParserError( |
|
|
"iterparse is designed for large XML files that are fully extracted on " |
|
|
"local disk and not as compressed files or online sources." |
|
|
) |
|
|
|
|
|
iterparse_repeats = len(self.iterparse[row_node]) != len( |
|
|
set(self.iterparse[row_node]) |
|
|
) |
|
|
|
|
|
for event, elem in iterparse(self.path_or_buffer, events=("start", "end")): |
|
|
curr_elem = elem.tag.split("}")[1] if "}" in elem.tag else elem.tag |
|
|
|
|
|
if event == "start": |
|
|
if curr_elem == row_node: |
|
|
row = {} |
|
|
|
|
|
if row is not None: |
|
|
if self.names and iterparse_repeats: |
|
|
for col, nm in zip(self.iterparse[row_node], self.names): |
|
|
if curr_elem == col: |
|
|
elem_val = elem.text if elem.text else None |
|
|
if elem_val not in row.values() and nm not in row: |
|
|
row[nm] = elem_val |
|
|
|
|
|
if col in elem.attrib: |
|
|
if elem.attrib[col] not in row.values() and nm not in row: |
|
|
row[nm] = elem.attrib[col] |
|
|
else: |
|
|
for col in self.iterparse[row_node]: |
|
|
if curr_elem == col: |
|
|
row[col] = elem.text if elem.text else None |
|
|
if col in elem.attrib: |
|
|
row[col] = elem.attrib[col] |
|
|
|
|
|
if event == "end": |
|
|
if curr_elem == row_node and row is not None: |
|
|
dicts.append(row) |
|
|
row = None |
|
|
|
|
|
elem.clear() |
|
|
if hasattr(elem, "getprevious"): |
|
|
while ( |
|
|
elem.getprevious() is not None and elem.getparent() is not None |
|
|
): |
|
|
del elem.getparent()[0] |
|
|
|
|
|
if dicts == []: |
|
|
raise ParserError("No result from selected items in iterparse.") |
|
|
|
|
|
keys = list(dict.fromkeys([k for d in dicts for k in d.keys()])) |
|
|
dicts = [{k: d[k] if k in d.keys() else None for k in keys} for d in dicts] |
|
|
|
|
|
if self.names: |
|
|
dicts = [dict(zip(self.names, d.values())) for d in dicts] |
|
|
|
|
|
return dicts |
|
|
|
|
|
def _validate_path(self) -> list[Any]: |
|
|
""" |
|
|
Validate ``xpath``. |
|
|
|
|
|
This method checks for syntax, evaluation, or empty nodes return. |
|
|
|
|
|
Raises |
|
|
------ |
|
|
SyntaxError |
|
|
* If xpah is not supported or issues with namespaces. |
|
|
|
|
|
ValueError |
|
|
* If xpah does not return any nodes. |
|
|
""" |
|
|
|
|
|
raise AbstractMethodError(self) |
|
|
|
|
|
def _validate_names(self) -> None: |
|
|
""" |
|
|
Validate names. |
|
|
|
|
|
This method will check if names is a list-like and aligns |
|
|
with length of parse nodes. |
|
|
|
|
|
Raises |
|
|
------ |
|
|
ValueError |
|
|
* If value is not a list and less then length of nodes. |
|
|
""" |
|
|
raise AbstractMethodError(self) |
|
|
|
|
|
def _parse_doc( |
|
|
self, raw_doc: FilePath | ReadBuffer[bytes] | ReadBuffer[str] |
|
|
) -> Element | etree._Element: |
|
|
""" |
|
|
Build tree from path_or_buffer. |
|
|
|
|
|
This method will parse XML object into tree |
|
|
either from string/bytes or file location. |
|
|
""" |
|
|
raise AbstractMethodError(self) |
|
|
|
|
|
|
|
|
class _EtreeFrameParser(_XMLFrameParser): |
|
|
""" |
|
|
Internal class to parse XML into DataFrames with the Python |
|
|
standard library XML module: `xml.etree.ElementTree`. |
|
|
""" |
|
|
|
|
|
def parse_data(self) -> list[dict[str, str | None]]: |
|
|
from xml.etree.ElementTree import iterparse |
|
|
|
|
|
if self.stylesheet is not None: |
|
|
raise ValueError( |
|
|
"To use stylesheet, you need lxml installed and selected as parser." |
|
|
) |
|
|
|
|
|
if self.iterparse is None: |
|
|
self.xml_doc = self._parse_doc(self.path_or_buffer) |
|
|
elems = self._validate_path() |
|
|
|
|
|
self._validate_names() |
|
|
|
|
|
xml_dicts: list[dict[str, str | None]] = ( |
|
|
self._parse_nodes(elems) |
|
|
if self.iterparse is None |
|
|
else self._iterparse_nodes(iterparse) |
|
|
) |
|
|
|
|
|
return xml_dicts |
|
|
|
|
|
def _validate_path(self) -> list[Any]: |
|
|
""" |
|
|
Notes |
|
|
----- |
|
|
``etree`` supports limited ``XPath``. If user attempts a more complex |
|
|
expression syntax error will raise. |
|
|
""" |
|
|
|
|
|
msg = ( |
|
|
"xpath does not return any nodes or attributes. " |
|
|
"Be sure to specify in `xpath` the parent nodes of " |
|
|
"children and attributes to parse. " |
|
|
"If document uses namespaces denoted with " |
|
|
"xmlns, be sure to define namespaces and " |
|
|
"use them in xpath." |
|
|
) |
|
|
try: |
|
|
elems = self.xml_doc.findall(self.xpath, namespaces=self.namespaces) |
|
|
children = [ch for el in elems for ch in el.findall("*")] |
|
|
attrs = {k: v for el in elems for k, v in el.attrib.items()} |
|
|
|
|
|
if elems is None: |
|
|
raise ValueError(msg) |
|
|
|
|
|
if elems is not None: |
|
|
if self.elems_only and children == []: |
|
|
raise ValueError(msg) |
|
|
if self.attrs_only and attrs == {}: |
|
|
raise ValueError(msg) |
|
|
if children == [] and attrs == {}: |
|
|
raise ValueError(msg) |
|
|
|
|
|
except (KeyError, SyntaxError): |
|
|
raise SyntaxError( |
|
|
"You have used an incorrect or unsupported XPath " |
|
|
"expression for etree library or you used an " |
|
|
"undeclared namespace prefix." |
|
|
) |
|
|
|
|
|
return elems |
|
|
|
|
|
def _validate_names(self) -> None: |
|
|
children: list[Any] |
|
|
|
|
|
if self.names: |
|
|
if self.iterparse: |
|
|
children = self.iterparse[next(iter(self.iterparse))] |
|
|
else: |
|
|
parent = self.xml_doc.find(self.xpath, namespaces=self.namespaces) |
|
|
children = parent.findall("*") if parent is not None else [] |
|
|
|
|
|
if is_list_like(self.names): |
|
|
if len(self.names) < len(children): |
|
|
raise ValueError( |
|
|
"names does not match length of child elements in xpath." |
|
|
) |
|
|
else: |
|
|
raise TypeError( |
|
|
f"{type(self.names).__name__} is not a valid type for names" |
|
|
) |
|
|
|
|
|
def _parse_doc( |
|
|
self, raw_doc: FilePath | ReadBuffer[bytes] | ReadBuffer[str] |
|
|
) -> Element: |
|
|
from xml.etree.ElementTree import ( |
|
|
XMLParser, |
|
|
parse, |
|
|
) |
|
|
|
|
|
handle_data = get_data_from_filepath( |
|
|
filepath_or_buffer=raw_doc, |
|
|
encoding=self.encoding, |
|
|
compression=self.compression, |
|
|
storage_options=self.storage_options, |
|
|
) |
|
|
|
|
|
with preprocess_data(handle_data) as xml_data: |
|
|
curr_parser = XMLParser(encoding=self.encoding) |
|
|
document = parse(xml_data, parser=curr_parser) |
|
|
|
|
|
return document.getroot() |
|
|
|
|
|
|
|
|
class _LxmlFrameParser(_XMLFrameParser): |
|
|
""" |
|
|
Internal class to parse XML into :class:`~pandas.DataFrame` with third-party |
|
|
full-featured XML library, ``lxml``, that supports |
|
|
``XPath`` 1.0 and XSLT 1.0. |
|
|
""" |
|
|
|
|
|
def parse_data(self) -> list[dict[str, str | None]]: |
|
|
""" |
|
|
Parse xml data. |
|
|
|
|
|
This method will call the other internal methods to |
|
|
validate ``xpath``, names, optionally parse and run XSLT, |
|
|
and parse original or transformed XML and return specific nodes. |
|
|
""" |
|
|
from lxml.etree import iterparse |
|
|
|
|
|
if self.iterparse is None: |
|
|
self.xml_doc = self._parse_doc(self.path_or_buffer) |
|
|
|
|
|
if self.stylesheet: |
|
|
self.xsl_doc = self._parse_doc(self.stylesheet) |
|
|
self.xml_doc = self._transform_doc() |
|
|
|
|
|
elems = self._validate_path() |
|
|
|
|
|
self._validate_names() |
|
|
|
|
|
xml_dicts: list[dict[str, str | None]] = ( |
|
|
self._parse_nodes(elems) |
|
|
if self.iterparse is None |
|
|
else self._iterparse_nodes(iterparse) |
|
|
) |
|
|
|
|
|
return xml_dicts |
|
|
|
|
|
def _validate_path(self) -> list[Any]: |
|
|
msg = ( |
|
|
"xpath does not return any nodes or attributes. " |
|
|
"Be sure to specify in `xpath` the parent nodes of " |
|
|
"children and attributes to parse. " |
|
|
"If document uses namespaces denoted with " |
|
|
"xmlns, be sure to define namespaces and " |
|
|
"use them in xpath." |
|
|
) |
|
|
|
|
|
elems = self.xml_doc.xpath(self.xpath, namespaces=self.namespaces) |
|
|
children = [ch for el in elems for ch in el.xpath("*")] |
|
|
attrs = {k: v for el in elems for k, v in el.attrib.items()} |
|
|
|
|
|
if elems == []: |
|
|
raise ValueError(msg) |
|
|
|
|
|
if elems != []: |
|
|
if self.elems_only and children == []: |
|
|
raise ValueError(msg) |
|
|
if self.attrs_only and attrs == {}: |
|
|
raise ValueError(msg) |
|
|
if children == [] and attrs == {}: |
|
|
raise ValueError(msg) |
|
|
|
|
|
return elems |
|
|
|
|
|
def _validate_names(self) -> None: |
|
|
children: list[Any] |
|
|
|
|
|
if self.names: |
|
|
if self.iterparse: |
|
|
children = self.iterparse[next(iter(self.iterparse))] |
|
|
else: |
|
|
children = self.xml_doc.xpath( |
|
|
self.xpath + "[1]/*", namespaces=self.namespaces |
|
|
) |
|
|
|
|
|
if is_list_like(self.names): |
|
|
if len(self.names) < len(children): |
|
|
raise ValueError( |
|
|
"names does not match length of child elements in xpath." |
|
|
) |
|
|
else: |
|
|
raise TypeError( |
|
|
f"{type(self.names).__name__} is not a valid type for names" |
|
|
) |
|
|
|
|
|
def _parse_doc( |
|
|
self, raw_doc: FilePath | ReadBuffer[bytes] | ReadBuffer[str] |
|
|
) -> etree._Element: |
|
|
from lxml.etree import ( |
|
|
XMLParser, |
|
|
fromstring, |
|
|
parse, |
|
|
) |
|
|
|
|
|
handle_data = get_data_from_filepath( |
|
|
filepath_or_buffer=raw_doc, |
|
|
encoding=self.encoding, |
|
|
compression=self.compression, |
|
|
storage_options=self.storage_options, |
|
|
) |
|
|
|
|
|
with preprocess_data(handle_data) as xml_data: |
|
|
curr_parser = XMLParser(encoding=self.encoding) |
|
|
|
|
|
if isinstance(xml_data, io.StringIO): |
|
|
if self.encoding is None: |
|
|
raise TypeError( |
|
|
"Can not pass encoding None when input is StringIO." |
|
|
) |
|
|
|
|
|
document = fromstring( |
|
|
xml_data.getvalue().encode(self.encoding), parser=curr_parser |
|
|
) |
|
|
else: |
|
|
document = parse(xml_data, parser=curr_parser) |
|
|
|
|
|
return document |
|
|
|
|
|
def _transform_doc(self) -> etree._XSLTResultTree: |
|
|
""" |
|
|
Transform original tree using stylesheet. |
|
|
|
|
|
This method will transform original xml using XSLT script into |
|
|
am ideally flatter xml document for easier parsing and migration |
|
|
to Data Frame. |
|
|
""" |
|
|
from lxml.etree import XSLT |
|
|
|
|
|
transformer = XSLT(self.xsl_doc) |
|
|
new_doc = transformer(self.xml_doc) |
|
|
|
|
|
return new_doc |
|
|
|
|
|
|
|
|
def get_data_from_filepath( |
|
|
filepath_or_buffer: FilePath | bytes | ReadBuffer[bytes] | ReadBuffer[str], |
|
|
encoding: str | None, |
|
|
compression: CompressionOptions, |
|
|
storage_options: StorageOptions, |
|
|
) -> str | bytes | ReadBuffer[bytes] | ReadBuffer[str]: |
|
|
""" |
|
|
Extract raw XML data. |
|
|
|
|
|
The method accepts three input types: |
|
|
1. filepath (string-like) |
|
|
2. file-like object (e.g. open file object, StringIO) |
|
|
3. XML string or bytes |
|
|
|
|
|
This method turns (1) into (2) to simplify the rest of the processing. |
|
|
It returns input types (2) and (3) unchanged. |
|
|
""" |
|
|
if not isinstance(filepath_or_buffer, bytes): |
|
|
filepath_or_buffer = stringify_path(filepath_or_buffer) |
|
|
|
|
|
if ( |
|
|
isinstance(filepath_or_buffer, str) |
|
|
and not filepath_or_buffer.startswith(("<?xml", "<")) |
|
|
) and ( |
|
|
not isinstance(filepath_or_buffer, str) |
|
|
or is_url(filepath_or_buffer) |
|
|
or is_fsspec_url(filepath_or_buffer) |
|
|
or file_exists(filepath_or_buffer) |
|
|
): |
|
|
with get_handle( |
|
|
filepath_or_buffer, |
|
|
"r", |
|
|
encoding=encoding, |
|
|
compression=compression, |
|
|
storage_options=storage_options, |
|
|
) as handle_obj: |
|
|
filepath_or_buffer = ( |
|
|
handle_obj.handle.read() |
|
|
if hasattr(handle_obj.handle, "read") |
|
|
else handle_obj.handle |
|
|
) |
|
|
|
|
|
return filepath_or_buffer |
|
|
|
|
|
|
|
|
def preprocess_data(data) -> io.StringIO | io.BytesIO: |
|
|
""" |
|
|
Convert extracted raw data. |
|
|
|
|
|
This method will return underlying data of extracted XML content. |
|
|
The data either has a `read` attribute (e.g. a file object or a |
|
|
StringIO/BytesIO) or is a string or bytes that is an XML document. |
|
|
""" |
|
|
|
|
|
if isinstance(data, str): |
|
|
data = io.StringIO(data) |
|
|
|
|
|
elif isinstance(data, bytes): |
|
|
data = io.BytesIO(data) |
|
|
|
|
|
return data |
|
|
|
|
|
|
|
|
def _data_to_frame(data, **kwargs) -> DataFrame: |
|
|
""" |
|
|
Convert parsed data to Data Frame. |
|
|
|
|
|
This method will bind xml dictionary data of keys and values |
|
|
into named columns of Data Frame using the built-in TextParser |
|
|
class that build Data Frame and infers specific dtypes. |
|
|
""" |
|
|
|
|
|
tags = next(iter(data)) |
|
|
nodes = [list(d.values()) for d in data] |
|
|
|
|
|
try: |
|
|
with TextParser(nodes, names=tags, **kwargs) as tp: |
|
|
return tp.read() |
|
|
except ParserError: |
|
|
raise ParserError( |
|
|
"XML document may be too complex for import. " |
|
|
"Try to flatten document and use distinct " |
|
|
"element and attribute names." |
|
|
) |
|
|
|
|
|
|
|
|
def _parse( |
|
|
path_or_buffer: FilePath | ReadBuffer[bytes] | ReadBuffer[str], |
|
|
xpath: str, |
|
|
namespaces: dict[str, str] | None, |
|
|
elems_only: bool, |
|
|
attrs_only: bool, |
|
|
names: Sequence[str] | None, |
|
|
dtype: DtypeArg | None, |
|
|
converters: ConvertersArg | None, |
|
|
parse_dates: ParseDatesArg | None, |
|
|
encoding: str | None, |
|
|
parser: XMLParsers, |
|
|
stylesheet: FilePath | ReadBuffer[bytes] | ReadBuffer[str] | None, |
|
|
iterparse: dict[str, list[str]] | None, |
|
|
compression: CompressionOptions, |
|
|
storage_options: StorageOptions, |
|
|
dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default, |
|
|
**kwargs, |
|
|
) -> DataFrame: |
|
|
""" |
|
|
Call internal parsers. |
|
|
|
|
|
This method will conditionally call internal parsers: |
|
|
LxmlFrameParser and/or EtreeParser. |
|
|
|
|
|
Raises |
|
|
------ |
|
|
ImportError |
|
|
* If lxml is not installed if selected as parser. |
|
|
|
|
|
ValueError |
|
|
* If parser is not lxml or etree. |
|
|
""" |
|
|
|
|
|
p: _EtreeFrameParser | _LxmlFrameParser |
|
|
|
|
|
if isinstance(path_or_buffer, str) and not any( |
|
|
[ |
|
|
is_file_like(path_or_buffer), |
|
|
file_exists(path_or_buffer), |
|
|
is_url(path_or_buffer), |
|
|
is_fsspec_url(path_or_buffer), |
|
|
] |
|
|
): |
|
|
warnings.warn( |
|
|
"Passing literal xml to 'read_xml' is deprecated and " |
|
|
"will be removed in a future version. To read from a " |
|
|
"literal string, wrap it in a 'StringIO' object.", |
|
|
FutureWarning, |
|
|
stacklevel=find_stack_level(), |
|
|
) |
|
|
|
|
|
if parser == "lxml": |
|
|
lxml = import_optional_dependency("lxml.etree", errors="ignore") |
|
|
|
|
|
if lxml is not None: |
|
|
p = _LxmlFrameParser( |
|
|
path_or_buffer, |
|
|
xpath, |
|
|
namespaces, |
|
|
elems_only, |
|
|
attrs_only, |
|
|
names, |
|
|
dtype, |
|
|
converters, |
|
|
parse_dates, |
|
|
encoding, |
|
|
stylesheet, |
|
|
iterparse, |
|
|
compression, |
|
|
storage_options, |
|
|
) |
|
|
else: |
|
|
raise ImportError("lxml not found, please install or use the etree parser.") |
|
|
|
|
|
elif parser == "etree": |
|
|
p = _EtreeFrameParser( |
|
|
path_or_buffer, |
|
|
xpath, |
|
|
namespaces, |
|
|
elems_only, |
|
|
attrs_only, |
|
|
names, |
|
|
dtype, |
|
|
converters, |
|
|
parse_dates, |
|
|
encoding, |
|
|
stylesheet, |
|
|
iterparse, |
|
|
compression, |
|
|
storage_options, |
|
|
) |
|
|
else: |
|
|
raise ValueError("Values for parser can only be lxml or etree.") |
|
|
|
|
|
data_dicts = p.parse_data() |
|
|
|
|
|
return _data_to_frame( |
|
|
data=data_dicts, |
|
|
dtype=dtype, |
|
|
converters=converters, |
|
|
parse_dates=parse_dates, |
|
|
dtype_backend=dtype_backend, |
|
|
**kwargs, |
|
|
) |
|
|
|
|
|
|
|
|
@doc( |
|
|
storage_options=_shared_docs["storage_options"], |
|
|
decompression_options=_shared_docs["decompression_options"] % "path_or_buffer", |
|
|
) |
|
|
def read_xml( |
|
|
path_or_buffer: FilePath | ReadBuffer[bytes] | ReadBuffer[str], |
|
|
*, |
|
|
xpath: str = "./*", |
|
|
namespaces: dict[str, str] | None = None, |
|
|
elems_only: bool = False, |
|
|
attrs_only: bool = False, |
|
|
names: Sequence[str] | None = None, |
|
|
dtype: DtypeArg | None = None, |
|
|
converters: ConvertersArg | None = None, |
|
|
parse_dates: ParseDatesArg | None = None, |
|
|
|
|
|
encoding: str | None = "utf-8", |
|
|
parser: XMLParsers = "lxml", |
|
|
stylesheet: FilePath | ReadBuffer[bytes] | ReadBuffer[str] | None = None, |
|
|
iterparse: dict[str, list[str]] | None = None, |
|
|
compression: CompressionOptions = "infer", |
|
|
storage_options: StorageOptions | None = None, |
|
|
dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default, |
|
|
) -> DataFrame: |
|
|
r""" |
|
|
Read XML document into a :class:`~pandas.DataFrame` object. |
|
|
|
|
|
.. versionadded:: 1.3.0 |
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
path_or_buffer : str, path object, or file-like object |
|
|
String, path object (implementing ``os.PathLike[str]``), or file-like |
|
|
object implementing a ``read()`` function. The string can be any valid XML |
|
|
string or a path. The string can further be a URL. Valid URL schemes |
|
|
include http, ftp, s3, and file. |
|
|
|
|
|
.. deprecated:: 2.1.0 |
|
|
Passing xml literal strings is deprecated. |
|
|
Wrap literal xml input in ``io.StringIO`` or ``io.BytesIO`` instead. |
|
|
|
|
|
xpath : str, optional, default './\*' |
|
|
The ``XPath`` to parse required set of nodes for migration to |
|
|
:class:`~pandas.DataFrame`.``XPath`` should return a collection of elements |
|
|
and not a single element. Note: The ``etree`` parser supports limited ``XPath`` |
|
|
expressions. For more complex ``XPath``, use ``lxml`` which requires |
|
|
installation. |
|
|
|
|
|
namespaces : dict, optional |
|
|
The namespaces defined in XML document as dicts with key being |
|
|
namespace prefix and value the URI. There is no need to include all |
|
|
namespaces in XML, only the ones used in ``xpath`` expression. |
|
|
Note: if XML document uses default namespace denoted as |
|
|
`xmlns='<URI>'` without a prefix, you must assign any temporary |
|
|
namespace prefix such as 'doc' to the URI in order to parse |
|
|
underlying nodes and/or attributes. For example, :: |
|
|
|
|
|
namespaces = {{"doc": "https://example.com"}} |
|
|
|
|
|
elems_only : bool, optional, default False |
|
|
Parse only the child elements at the specified ``xpath``. By default, |
|
|
all child elements and non-empty text nodes are returned. |
|
|
|
|
|
attrs_only : bool, optional, default False |
|
|
Parse only the attributes at the specified ``xpath``. |
|
|
By default, all attributes are returned. |
|
|
|
|
|
names : list-like, optional |
|
|
Column names for DataFrame of parsed XML data. Use this parameter to |
|
|
rename original element names and distinguish same named elements and |
|
|
attributes. |
|
|
|
|
|
dtype : Type name or dict of column -> type, optional |
|
|
Data type for data or columns. E.g. {{'a': np.float64, 'b': np.int32, |
|
|
'c': 'Int64'}} |
|
|
Use `str` or `object` together with suitable `na_values` settings |
|
|
to preserve and not interpret dtype. |
|
|
If converters are specified, they will be applied INSTEAD |
|
|
of dtype conversion. |
|
|
|
|
|
.. versionadded:: 1.5.0 |
|
|
|
|
|
converters : dict, optional |
|
|
Dict of functions for converting values in certain columns. Keys can either |
|
|
be integers or column labels. |
|
|
|
|
|
.. versionadded:: 1.5.0 |
|
|
|
|
|
parse_dates : bool or list of int or names or list of lists or dict, default False |
|
|
Identifiers to parse index or columns to datetime. The behavior is as follows: |
|
|
|
|
|
* boolean. If True -> try parsing the index. |
|
|
* list of int or names. e.g. If [1, 2, 3] -> try parsing columns 1, 2, 3 |
|
|
each as a separate date column. |
|
|
* list of lists. e.g. If [[1, 3]] -> combine columns 1 and 3 and parse as |
|
|
a single date column. |
|
|
* dict, e.g. {{'foo' : [1, 3]}} -> parse columns 1, 3 as date and call |
|
|
result 'foo' |
|
|
|
|
|
.. versionadded:: 1.5.0 |
|
|
|
|
|
encoding : str, optional, default 'utf-8' |
|
|
Encoding of XML document. |
|
|
|
|
|
parser : {{'lxml','etree'}}, default 'lxml' |
|
|
Parser module to use for retrieval of data. Only 'lxml' and |
|
|
'etree' are supported. With 'lxml' more complex ``XPath`` searches |
|
|
and ability to use XSLT stylesheet are supported. |
|
|
|
|
|
stylesheet : str, path object or file-like object |
|
|
A URL, file-like object, or a raw string containing an XSLT script. |
|
|
This stylesheet should flatten complex, deeply nested XML documents |
|
|
for easier parsing. To use this feature you must have ``lxml`` module |
|
|
installed and specify 'lxml' as ``parser``. The ``xpath`` must |
|
|
reference nodes of transformed XML document generated after XSLT |
|
|
transformation and not the original XML document. Only XSLT 1.0 |
|
|
scripts and not later versions is currently supported. |
|
|
|
|
|
iterparse : dict, optional |
|
|
The nodes or attributes to retrieve in iterparsing of XML document |
|
|
as a dict with key being the name of repeating element and value being |
|
|
list of elements or attribute names that are descendants of the repeated |
|
|
element. Note: If this option is used, it will replace ``xpath`` parsing |
|
|
and unlike ``xpath``, descendants do not need to relate to each other but can |
|
|
exist any where in document under the repeating element. This memory- |
|
|
efficient method should be used for very large XML files (500MB, 1GB, or 5GB+). |
|
|
For example, :: |
|
|
|
|
|
iterparse = {{"row_element": ["child_elem", "attr", "grandchild_elem"]}} |
|
|
|
|
|
.. versionadded:: 1.5.0 |
|
|
|
|
|
{decompression_options} |
|
|
|
|
|
.. versionchanged:: 1.4.0 Zstandard support. |
|
|
|
|
|
{storage_options} |
|
|
|
|
|
dtype_backend : {{'numpy_nullable', 'pyarrow'}}, default 'numpy_nullable' |
|
|
Back-end data type applied to the resultant :class:`DataFrame` |
|
|
(still experimental). Behaviour is as follows: |
|
|
|
|
|
* ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame` |
|
|
(default). |
|
|
* ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype` |
|
|
DataFrame. |
|
|
|
|
|
.. versionadded:: 2.0 |
|
|
|
|
|
Returns |
|
|
------- |
|
|
df |
|
|
A DataFrame. |
|
|
|
|
|
See Also |
|
|
-------- |
|
|
read_json : Convert a JSON string to pandas object. |
|
|
read_html : Read HTML tables into a list of DataFrame objects. |
|
|
|
|
|
Notes |
|
|
----- |
|
|
This method is best designed to import shallow XML documents in |
|
|
following format which is the ideal fit for the two-dimensions of a |
|
|
``DataFrame`` (row by column). :: |
|
|
|
|
|
<root> |
|
|
<row> |
|
|
<column1>data</column1> |
|
|
<column2>data</column2> |
|
|
<column3>data</column3> |
|
|
... |
|
|
</row> |
|
|
<row> |
|
|
... |
|
|
</row> |
|
|
... |
|
|
</root> |
|
|
|
|
|
As a file format, XML documents can be designed any way including |
|
|
layout of elements and attributes as long as it conforms to W3C |
|
|
specifications. Therefore, this method is a convenience handler for |
|
|
a specific flatter design and not all possible XML structures. |
|
|
|
|
|
However, for more complex XML documents, ``stylesheet`` allows you to |
|
|
temporarily redesign original document with XSLT (a special purpose |
|
|
language) for a flatter version for migration to a DataFrame. |
|
|
|
|
|
This function will *always* return a single :class:`DataFrame` or raise |
|
|
exceptions due to issues with XML document, ``xpath``, or other |
|
|
parameters. |
|
|
|
|
|
See the :ref:`read_xml documentation in the IO section of the docs |
|
|
<io.read_xml>` for more information in using this method to parse XML |
|
|
files to DataFrames. |
|
|
|
|
|
Examples |
|
|
-------- |
|
|
>>> 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 |
|
|
""" |
|
|
check_dtype_backend(dtype_backend) |
|
|
|
|
|
return _parse( |
|
|
path_or_buffer=path_or_buffer, |
|
|
xpath=xpath, |
|
|
namespaces=namespaces, |
|
|
elems_only=elems_only, |
|
|
attrs_only=attrs_only, |
|
|
names=names, |
|
|
dtype=dtype, |
|
|
converters=converters, |
|
|
parse_dates=parse_dates, |
|
|
encoding=encoding, |
|
|
parser=parser, |
|
|
stylesheet=stylesheet, |
|
|
iterparse=iterparse, |
|
|
compression=compression, |
|
|
storage_options=storage_options, |
|
|
dtype_backend=dtype_backend, |
|
|
) |
|
|
|
