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=u'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=<type '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 entrys 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=<type '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 entrys 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