Properties Class

class javaproperties.Properties(data=None, defaults=None)

A port of Java 8’s java.util.Properties that tries to match its behavior as much as is Pythonically possible. Properties behaves like a normal MutableMapping class (i.e., you can do props[key] = value and so forth), except that it may only be used to store strings (str and unicode in Python 2; just str in Python 3). Attempts to use a non-string object as a key or value will produce a TypeError.

Two Properties instances compare equal iff both their key-value pairs and defaults attributes are equal. When comparing a Properties instance to any other type of mapping, only the key-value pairs are considered.

Changed in version 0.5.0: Properties instances can now compare equal to dicts and other mapping types

Parameters

• data (mapping or None) – A mapping or iterable of (key, value) pairs with which to initialize the Properties instance. All keys and values in data must be text strings.

• defaults (Properties or None) – a set of default properties that will be used as fallback for getProperty

copy()

New in version 0.5.0.

Create a shallow copy of the mapping. The copy’s defaults attribute will be the same instance as the original’s defaults.

defaults = None

A Properties subobject used as fallback for getProperty. Only getProperty, propertyNames, stringPropertyNames, and __eq__ use this attribute; all other methods (including the standard mapping methods) ignore it.

getProperty(key, defaultValue=None)

Fetch the value associated with the key key in the Properties instance. If the key is not present, defaults is checked, and then its defaults, etc., until either a value for key is found or the next defaults is None, in which case defaultValue is returned.

Parameters

• key (text string) – the key to look up the value of

• defaultValue – the value to return if key is not found in the Properties instance

Return type

text string (if key was found)

Raises

TypeError – if key is not a string

load(inStream)

Update the Properties instance with the entries in a .properties file or file-like object.

inStream may be either a text or binary filehandle, with or without universal newlines enabled. If it is a binary filehandle, its contents are decoded as Latin-1.

Changed in version 0.5.0: Invalid \uXXXX escape sequences will now cause an InvalidUEscapeError to be raised

Parameters

inStream (file-like object) – the file from which to read the .properties document

Returns

None

Raises

InvalidUEscapeError – if an invalid \uXXXX escape sequence occurs in the input

loadFromXML(inStream)

Update the Properties instance with the entries in the XML properties file inStream.

Beyond basic XML well-formedness, loadFromXML only checks that the root element is named properties and that all of its entry children have key attributes; no further validation is performed.

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

inStream (file-like object) – the file from which to read the XML properties document

Returns

None

Raises

ValueError – if the root of the XML tree is not a <properties> tag or an <entry> element is missing a key attribute

propertyNames()

Returns a generator of all distinct keys in the Properties instance and its defaults (and its defaults’s defaults, etc.) in unspecified order

Return type

generator of text strings

setProperty(key, value)

Equivalent to self[key] = value

store(out, comments=None)

Write the Properties instance’s entries (in unspecified order) in .properties format to out, including the current timestamp.

Parameters

• out – A file-like object to write the properties to. It must have been opened as a text file with a Latin-1-compatible encoding.

• comments (text string or None) – If non-None, comments will be written to out as a comment before any other content

Returns

None

storeToXML(out, comment=None, encoding='UTF-8')

Write the Properties instance’s entries (in unspecified order) in XML properties format to out.

Parameters

• out (binary file-like object) – a file-like object to write the properties 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)

Returns

None

stringPropertyNames()

Returns a set of all keys in the Properties instance and its defaults (and its defaults’s defaults, etc.)

Return type

set of text strings