Simple Line-Oriented .properties Format

Format Overview

The simple line-oriented .properties file format consists of a series of key-value string pairs, one (or fewer) per line, with the key & value separated by the first occurrence of an equals sign (=, optionally with surrounding whitespace), a colon (:, optionally with surrounding whitespace), or non-leading whitespace. A line without a separator is treated as a key whose value is the empty string. If the same key occurs more than once in a single file, only its last value is used.

Note

Lines are terminated by \n (LF), \r\n (CR LF), or \r (CR).

Note

For the purposes of this format, only the space character (ASCII 0x20), the tab character (ASCII 0x09), and the form feed character (ASCII 0x0C) count as whitespace.

Leading whitespace on a line is ignored, but trailing whitespace (after stripping trailing newlines) is not. Lines whose first non-whitespace character is # or ! (not escaped) are comments and are ignored.

Entries can be extended across multiple lines by ending all but the last line with a backslash; the backslash, the line ending after it, and any leading whitespace on the next line will all be discarded. A backslash at the end of a comment line has no effect. A comment line after a line that ends with a backslash is treated as part of a normal key-value entry, not as a comment.

Occurrences of =, :, #, !, and whitespace inside a key or value are escaped with a backslash. In addition, the following escape sequences are recognized:

\t \n \f \r \uXXXX \\

If a backslash is followed by any other character, the backslash is dropped.

By default, keys & values in .properties files are encoded in ASCII, and comments are encoded in Latin-1; characters outside these ranges, along with any unprintable characters, are escaped with the escape sequences listed above. Unicode characters outside the Basic Multilingual Plane are first converted to UTF-16 surrogate pairs before escaping with \uXXXX escapes.

Functions

javaproperties.dump(props, fp, separator='=', comments=None, timestamp=True, sort_keys=False)[source]

Write a series of key-value pairs to a file in simple line-oriented .properties format.

Parameters:
  • props – A mapping or iterable of (key, value) pairs to write to fp. All keys and values in props must be text strings. If sort_keys is False, the entries are output in iteration order.
  • fp – A file-like object to write the values of props 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 keys & values. Only " ", "=", and ":" (possibly with added whitespace) should ever be used as the separator.
  • comments (text string or None) – if non-None, comments will be written to fp as a comment before any other content
  • timestamp (None, bool, number, or datetime.datetime) – If neither None nor False, a timestamp in the form of Mon Sep 02 14:00:54 EDT 2016 is written as a comment to fp after comments (if any) and before the key-value pairs. If timestamp is True, the current date & time is used. If it is a number, it is converted from seconds since the epoch to local time. If it is a datetime.datetime object, its value is used directly, with naïve objects assumed to be in the local timezone.
  • sort_keys (bool) – if true, the elements of props are sorted lexicographically by key in the output
Returns:

None

javaproperties.dumps(props, separator='=', comments=None, timestamp=True, sort_keys=False)[source]

Convert a series of key-value pairs to a text string in simple line-oriented .properties format.

Parameters:
  • props – A mapping or iterable of (key, value) pairs to serialize. All keys and values in props must be text strings. If sort_keys is False, the entries are output in iteration order.
  • separator (text string) – The string to use for separating keys & values. Only " ", "=", and ":" (possibly with added whitespace) should ever be used as the separator.
  • comments (text string or None) – if non-None, comments will be output as a comment before any other content
  • timestamp (None, bool, number, or datetime.datetime) – If neither None nor False, a timestamp in the form of Mon Sep 02 14:00:54 EDT 2016 is output as a comment after comments (if any) and before the key-value pairs. If timestamp is True, the current date & time is used. If it is a number, it is converted from seconds since the epoch to local time. If it is a datetime.datetime object, its value is used directly, with naïve objects assumed to be in the local timezone.
  • sort_keys (bool) – if true, the elements of props are sorted lexicographically by key in the output
Return type:

text string

javaproperties.load(fp, object_pairs_hook=<class 'dict'>)[source]

Parse the contents of the readline-supporting file-like object fp as a simple line-oriented .properties file and return a dict of the key-value pairs.

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.

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 will then return the value returned by object_pairs_hook.

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

Parameters:
  • fp (file-like object) – the file from which to read the .properties document
  • object_pairs_hook (callable) – class or function for combining the key-value pairs
Return type:

dict of text strings or the return value of object_pairs_hook

Raises:

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

javaproperties.loads(s, object_pairs_hook=<class 'dict'>)[source]

Parse the contents of the string s as a simple line-oriented .properties file and return a dict of the key-value pairs.

s may be either a text string or bytes string. If it is a bytes string, its contents are decoded as Latin-1.

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 will then return the value returned by object_pairs_hook.

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

Parameters:
  • s (string) – the string from which to read the .properties document
  • object_pairs_hook (callable) – class or function for combining the key-value pairs
Return type:

dict of text strings or the return value of object_pairs_hook

Raises:

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