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 filehandle fp 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 to fp. All keys and values in props must be text strings. If sort_keys is False, 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:

None

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 in props must be text strings. If sort_keys is False, 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

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 a dict 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 have key 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 a dict with later occurrences of a key overriding previous occurrences of the same key. To change this behavior, pass a callable as the object_pairs_hook argument; it will be called with one argument, a generator of (key, value) pairs representing the key-value entries in fp (including duplicates) in order of occurrence. load_xml will then return the value returned by object_pairs_hook.

Note

This uses xml.etree.ElementTree for parsing, which does not have decent support for unicode 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 of `object_pairs_hook`
Raises:	ValueError – if the root of the XML tree is not a `<properties>` tag or an `<entry>` element is missing a `key` 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 a dict 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 have key 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 a dict with later occurrences of a key overriding previous occurrences of the same key. To change this behavior, pass a callable as the object_pairs_hook argument; it will be called with one argument, a generator of (key, value) pairs representing the key-value entries in s (including duplicates) in order of occurrence. loads_xml will then return the value returned by object_pairs_hook.

Note

This uses xml.etree.ElementTree for parsing, which does not have decent support for unicode 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 of `object_pairs_hook`
Raises:	ValueError – if the root of the XML tree is not a `<properties>` tag or an `<entry>` element is missing a `key` attribute

XML .properties Format¶

Format Overview¶

Functions¶

XML `.properties` Format¶