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>)[source]#

Read XML document into aDataFrame object.

Added in version 1.3.0.

Parameters:

path_or_bufferstr, path object, or file-like object

String, path object (implementingos.PathLike[str]), or file-likeobject implementing aread() function. The string can be any valid XMLstring or a path. The string can further be a URL. Valid URL schemesinclude http, ftp, s3, and file.

Deprecated since version 2.1.0:Passing xml literal strings is deprecated.Wrap literal xml input inio.StringIO orio.BytesIO instead.

xpathstr, optional, default ‘./*’

TheXPath to parse required set of nodes for migration toDataFrame.``XPath`` should return a collection of elementsand not a single element. Note: Theetree parser supports limitedXPathexpressions. For more complexXPath, uselxml which requiresinstallation.

namespacesdict, optional

The namespaces defined in XML document as dicts with key beingnamespace prefix and value the URI. There is no need to include allnamespaces in XML, only the ones used inxpath expression.Note: if XML document uses default namespace denoted asxmlns=’<URI>’ without a prefix, you must assign any temporarynamespace prefix such as ‘doc’ to the URI in order to parseunderlying nodes and/or attributes. For example,

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

elems_onlybool, optional, default False

Parse only the child elements at the specifiedxpath. By default,all child elements and non-empty text nodes are returned.

attrs_onlybool, optional, default False

Parse only the attributes at the specifiedxpath.By default, all attributes are returned.

nameslist-like, optional

Column names for DataFrame of parsed XML data. Use this parameter torename original element names and distinguish same named elements andattributes.

dtypeType name or dict of column -> type, optional

Data type for data or columns. E.g. {‘a’: np.float64, ‘b’: np.int32,‘c’: ‘Int64’}Usestr orobject together with suitablena_values settingsto preserve and not interpret dtype.If converters are specified, they will be applied INSTEADof dtype conversion.

Added in version 1.5.0.

convertersdict, optional

Dict of functions for converting values in certain columns. Keys can eitherbe integers or column labels.

Added in version 1.5.0.

parse_datesbool 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, 3each as a separate date column.

• list of lists. e.g. If [[1, 3]] -> combine columns 1 and 3 and parse asa single date column.

• dict, e.g. {‘foo’ : [1, 3]} -> parse columns 1, 3 as date and callresult ‘foo’

Added in version 1.5.0.

encodingstr, 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 complexXPath searchesand ability to use XSLT stylesheet are supported.

stylesheetstr, 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 documentsfor easier parsing. To use this feature you must havelxml moduleinstalled and specify ‘lxml’ asparser. Thexpath mustreference nodes of transformed XML document generated after XSLTtransformation and not the original XML document. Only XSLT 1.0scripts and not later versions is currently supported.

iterparsedict, optional

The nodes or attributes to retrieve in iterparsing of XML documentas a dict with key being the name of repeating element and value beinglist of elements or attribute names that are descendants of the repeatedelement. Note: If this option is used, it will replacexpath parsingand unlikexpath, descendants do not need to relate to each other but canexist 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"]}

Added in version 1.5.0.

compressionstr or dict, default ‘infer’

For on-the-fly decompression of on-disk data. If ‘infer’ and ‘path_or_buffer’ ispath-like, then detect compression from the following extensions: ‘.gz’,‘.bz2’, ‘.zip’, ‘.xz’, ‘.zst’, ‘.tar’, ‘.tar.gz’, ‘.tar.xz’ or ‘.tar.bz2’(otherwise no compression).If using ‘zip’ or ‘tar’, the ZIP file must contain only one data file to be read in.Set toNone for no decompression.Can also be a dict with key'method' setto one of {'zip','gzip','bz2','zstd','xz','tar'} andother key-value pairs are forwarded tozipfile.ZipFile,gzip.GzipFile,bz2.BZ2File,zstandard.ZstdDecompressor,lzma.LZMAFile ortarfile.TarFile, respectively.As an example, the following could be passed for Zstandard decompression using acustom compression dictionary:compression={'method':'zstd','dict_data':my_compression_dict}.

Added in version 1.5.0:Added support for.tar files.

Changed in version 1.4.0:Zstandard support.

storage_optionsdict, optional

Extra options that make sense for a particular storage connection, e.g.host, port, username, password, etc. For HTTP(S) URLs the key-value pairsare forwarded tourllib.request.Request as header options. For otherURLs (e.g. starting with “s3://”, and “gcs://”) the key-value pairs areforwarded tofsspec.open. Please seefsspec andurllib for moredetails, and for more examples on storage options referhere.

dtype_backend{‘numpy_nullable’, ‘pyarrow’}, default ‘numpy_nullable’

Back-end data type applied to the resultantDataFrame(still experimental). Behaviour is as follows:

• "numpy_nullable": returns nullable-dtype-backedDataFrame(default).

• "pyarrow": returns pyarrow-backed nullableArrowDtypeDataFrame.

Added in version 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 infollowing format which is the ideal fit for the two-dimensions of aDataFrame (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 includinglayout of elements and attributes as long as it conforms to W3Cspecifications. Therefore, this method is a convenience handler fora specific flatter design and not all possible XML structures.

However, for more complex XML documents,stylesheet allows you totemporarily redesign original document with XSLT (a special purposelanguage) for a flatter version for migration to a DataFrame.

This function willalways return a singleDataFrame or raiseexceptions due to issues with XML document,xpath, or otherparameters.

See theread_xml documentation in the IO section of the docs for more information in using this method to parse XMLfiles to DataFrames.

Examples

>>>fromioimportStringIO>>>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  sides0    square      360    4.01    circle      360    NaN2  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  sides0    square      360    4.01    circle      360    NaN2  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  sides0    square      360    4.01    circle      360    NaN2  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          e0      0     1  2.5   True  a 2019-12-311      1  <NA>  4.5  False  b 2019-12-31