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>
An example XML .properties
file:
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<comment>This is a comment.</comment>
<entry key="foo">bar</entry>
<entry key="snowman">β</entry>
<entry key="goat">π</entry>
<entry key="host:port">127.0.0.1:80</entry>
</properties>
This corresponds to the Python dict
:
{
"foo": "bar",
"snowman": "β",
"goat": "π",
"host:port": "127.0.0.1:80",
}
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
tocomment (text string or
None
) β if non-None
,comment
will be output as a<comment>
element before the<entry>
elementsencoding (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
-
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>
elementssort_keys (bool) β if true, the elements of
props
are sorted lexicographically by key in the output
- Return type
text string
-
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