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 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: 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 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