XML .properties
Format¶
Format Overview¶
The XML .properties
file format encodes a series of key-value string pairs
(and optionally also a comment) as an XML document conforming to the following
Document Type Definition (published at
<http://java.sun.com/dtd/properties.dtd>):
<!ELEMENT properties (comment?, entry*)>
<!ATTLIST properties version CDATA #FIXED "1.0">
<!ELEMENT comment (#PCDATA)>
<!ELEMENT entry (#PCDATA)>
<!ATTLIST entry key CDATA #REQUIRED>
Functions¶
-
javaproperties.
dump_xml
(props, fp, comment=None, encoding='UTF-8', sort_keys=False)[source]¶ Write a series
props
of key-value pairs to a binary filehandlefp
in the format of an XML properties file. The file will include both an XML declaration and a doctype declaration.Parameters: - props – A mapping or iterable of
(key, value)
pairs to write tofp
. All keys and values inprops
must be text strings. Ifsort_keys
isFalse
, the entries are output in iteration order. - fp (binary file-like object) – a file-like object to write the values of
props
to - comment (text string or
None
) – if non-None
,comment
will be output as a<comment>
element before the<entry>
elements - encoding (string) – the name of the encoding to use for the XML document (also included in the XML declaration)
- sort_keys (bool) – if true, the elements of
props
are sorted lexicographically by key in the output
Returns: - props – A mapping or iterable of
-
javaproperties.
dumps_xml
(props, comment=None, sort_keys=False)[source]¶ Convert a series
props
of key-value pairs to a text string containing an XML properties document. The document will include a doctype declaration but not an XML declaration.Parameters: - props – A mapping or iterable of
(key, value)
pairs to serialize. All keys and values inprops
must be text strings. Ifsort_keys
isFalse
, the entries are output in iteration order. - comment (text string or
None
) – if non-None
,comment
will be output as a<comment>
element before the<entry>
elements - sort_keys (bool) – if true, the elements of
props
are sorted lexicographically by key in the output
Return type: text string
- props – A mapping or iterable of
-
javaproperties.
load_xml
(fp, object_pairs_hook=<class 'dict'>)[source]¶ Parse the contents of the file-like object
fp
as an XML properties file and return adict
of the key-value pairs.Beyond basic XML well-formedness,
load_xml
only checks that the root element is named “properties
” and that all of its<entry>
children havekey
attributes. No further validation is performed; if any<entry>
s happen to contain nested tags, the behavior is undefined.By default, the key-value pairs extracted from
fp
are combined into adict
with later occurrences of a key overriding previous occurrences of the same key. To change this behavior, pass a callable as theobject_pairs_hook
argument; it will be called with one argument, a generator of(key, value)
pairs representing the key-value entries infp
(including duplicates) in order of occurrence.load_xml
will then return the value returned byobject_pairs_hook
.Note
This uses
xml.etree.ElementTree
for parsing, which does not have decent support forunicode
input in Python 2. Files containing non-ASCII characters need to be opened in binary mode in Python 2, while Python 3 accepts both binary and text input.Parameters: - fp (file-like object) – the file from which to read the XML properties document
- object_pairs_hook (callable) – class or function for combining the key-value pairs
Return type: dict
or the return value ofobject_pairs_hook
Raises: ValueError – if the root of the XML tree is not a
<properties>
tag or an<entry>
element is missing akey
attribute
-
javaproperties.
loads_xml
(s, object_pairs_hook=<class 'dict'>)[source]¶ Parse the contents of the string
s
as an XML properties document and return adict
of the key-value pairs.Beyond basic XML well-formedness,
loads_xml
only checks that the root element is named “properties
” and that all of its<entry>
children havekey
attributes. No further validation is performed; if any<entry>
s happen to contain nested tags, the behavior is undefined.By default, the key-value pairs extracted from
s
are combined into adict
with later occurrences of a key overriding previous occurrences of the same key. To change this behavior, pass a callable as theobject_pairs_hook
argument; it will be called with one argument, a generator of(key, value)
pairs representing the key-value entries ins
(including duplicates) in order of occurrence.loads_xml
will then return the value returned byobject_pairs_hook
.Note
This uses
xml.etree.ElementTree
for parsing, which does not have decent support forunicode
input in Python 2. Strings containing non-ASCII characters need to be encoded as bytes in Python 2 (Use either UTF-8 or UTF-16 if the XML document does not contain an encoding declaration), while Python 3 accepts both binary and text input.Parameters: - s (string) – the string from which to read the XML properties document
- object_pairs_hook (callable) – class or function for combining the key-value pairs
Return type: dict
or the return value ofobject_pairs_hook
Raises: ValueError – if the root of the XML tree is not a
<properties>
tag or an<entry>
element is missing akey
attribute