PropertiesFile
Class¶
-
class
javaproperties.
PropertiesFile
(mapping=None, **kwargs)[source]¶ New in version 0.3.0.
A custom mapping class for reading from, editing, and writing to a
.properties
file while preserving comments & whitespace in the original input.A
PropertiesFile
instance can be constructed from another mapping and/or iterable of pairs, after which it will act like anOrderedDict
. Alternatively, an instance can be constructed from a file or string withPropertiesFile.load()
orPropertiesFile.loads()
, and the resulting instance will remember the formatting of its input and retain that formatting when written back to a file or string with thedump()
ordumps()
method. The formatting information attached to an instancepf
can be forgotten by constructing another mapping from it viadict(pf)
,OrderedDict(pf)
, or evenPropertiesFile(pf)
(Use thecopy()
method if you want to create anotherPropertiesFile
instance with the same data & formatting).When not reading or writing,
PropertiesFile
behaves like a normalMutableMapping
class (i.e., you can doprops[key] = value
and so forth), except that (a) likeOrderedDict
, key insertion order is remembered and is used when iterating & dumping (andreversed
is supported), and (b) likeProperties
, it may only be used to store strings and will raise aTypeError
if passed a non-string object as key or value.Two
PropertiesFile
instances compare equal iff both their key-value pairs and comment & whitespace lines are equal and in the same order. When comparing aPropertiesFile
to any other type of mapping, only the key-value pairs are considered, and order is ignored.PropertiesFile
currently only supports reading & writing the simple line-oriented format, not XML.-
dump
(fp, separator='=')[source]¶ Write the mapping to a file in simple line-oriented
.properties
format.If the instance was originally created from a file or string with
PropertiesFile.load()
orPropertiesFile.loads()
, then the output will include the comments and whitespace from the original input, and any keys that haven’t been deleted or reassigned will retain their original formatting and multiplicity. Key-value pairs that have been modified or added to the mapping will be reformatted withjoin_key_value()
using the given separator. All key-value pairs are output in the order they were defined, with new keys added to the end.Note
Serializing a
PropertiesFile
instance with thedump()
function instead will cause all formatting information to be ignored, asdump()
will treat the instance like a normal mapping.Parameters: - fp – A file-like object to write the mapping to. It must have been opened as a text file with a Latin-1-compatible encoding.
- separator (text string) – The string to use for separating new or modified keys
& values. Only
" "
,"="
, and":"
(possibly with added whitespace) should ever be used as the separator.
Returns:
-
dumps
(separator='=')[source]¶ Convert the mapping to a text string in simple line-oriented
.properties
format.If the instance was originally created from a file or string with
PropertiesFile.load()
orPropertiesFile.loads()
, then the output will include the comments and whitespace from the original input, and any keys that haven’t been deleted or reassigned will retain their original formatting and multiplicity. Key-value pairs that have been modified or added to the mapping will be reformatted withjoin_key_value()
using the given separator. All key-value pairs are output in the order they were defined, with new keys added to the end.Note
Serializing a
PropertiesFile
instance with thedumps()
function instead will cause all formatting information to be ignored, asdumps()
will treat the instance like a normal mapping.Parameters: separator (text string) – The string to use for separating new or modified keys & values. Only " "
,"="
, and":"
(possibly with added whitespace) should ever be used as the separator.Return type: text string
-
classmethod
load
(fp)[source]¶ Parse the contents of the
readline
-supporting file-like objectfp
as a simple line-oriented.properties
file and return aPropertiesFile
instance.fp
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.Parameters: fp (file-like object) – the file from which to read the .properties
documentReturn type: PropertiesFile
-
classmethod
loads
(s)[source]¶ Parse the contents of the string
s
as a simple line-oriented.properties
file and return aPropertiesFile
instance.s
may be either a text string or bytes string. If it is a bytes string, its contents are decoded as Latin-1.Parameters: s (string) – the string from which to read the .properties
documentReturn type: PropertiesFile
-