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: Union[Mapping[str, str], Iterable[Tuple[str, str]]], fp: BinaryIO, comment: Optional[str] = None, encoding: str = 'UTF-8', sort_keys: bool = False) → None[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 str values. If sort_keys is False, the entries are output in iteration order.

  • fp (BinaryIO) – a file-like object to write the values of props to

  • comment (Optional[str]) – if non-None, comment will be output as a <comment> element before the <entry> elements

  • encoding (str) – 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: Union[Mapping[str, str], Iterable[Tuple[str, str]]], comment: Optional[str] = None, sort_keys: bool = False) → str[source]

Convert a series props of key-value pairs to a str 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 str values. If sort_keys is False, the entries are output in iteration order.

  • comment (Optional[str]) – 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

str

javaproperties.load_xml(fp: IO) → Dict[str, str][source]
javaproperties.load_xml(fp: IO, object_pairs_hook: Type[T]) → T
javaproperties.load_xml(fp: IO, object_pairs_hook: Callable[[Iterator[Tuple[str, str]]], T]) → T

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.

Parameters

  • fp (IO) – 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: AnyStr) → Dict[str, str][source]
javaproperties.loads_xml(fp: IO, object_pairs_hook: Type[T]) → T
javaproperties.loads_xml(s: AnyStr, object_pairs_hook: Callable[[Iterator[Tuple[str, str]]], T]) → T

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.

Parameters

  • s (Union[str,bytes]) – 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