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: Mapping[str, str] | Iterable[tuple[str, str]], fp: BinaryIO, comment: str | None = None, encoding: str = 'UTF-8', sort_keys: bool = False) None [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 bestr
values. Ifsort_keys
isFalse
, the entries are output in iteration order.fp (BinaryIO) – a file-like object to write the values of
props
tocomment (Optional[str]) – if non-
None
,comment
will be output as a<comment>
element before the<entry>
elementsencoding (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:
- javaproperties.dumps_xml(props: Mapping[str, str] | Iterable[tuple[str, str]], comment: str | None = None, sort_keys: bool = False) str [source]
Convert a series
props
of key-value pairs to astr
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 bestr
values. Ifsort_keys
isFalse
, the entries are output in iteration order.comment (Optional[str]) – 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:
- 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 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
.- 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 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: 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 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
.- Parameters:
- 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