Low-Level Utilities¶

javaproperties.escape(field)¶

Escape a string so that it can be safely used as either a key or value in a .properties file. All non-ASCII characters, all nonprintable or space characters, and the characters \ # ! = : are all escaped using either the single-character escapes recognized by unescape (when they exist) or \uXXXX escapes (after converting non-BMP characters to surrogate pairs).

Parameters:	field (text string) – the string to escape
Return type:	text string

javaproperties.java_timestamp(timestamp=True)¶

New in version 0.2.0.

Returns a timestamp in the format produced by Java 8’s Date.toString(), e.g.:

Mon Sep 02 14:00:54 EDT 2016

If timestamp is True (the default), the current date & time is returned.

If timestamp is None or False, an empty string is returned.

If timestamp is a number, it is converted from seconds since the epoch to local time.

If timestamp is a datetime.datetime object, its value is used directly, with naïve objects assumed to be in the local timezone.

The timestamp is always constructed using the C locale.

Parameters:	timestamp (`None`, `bool`, number, or `datetime.datetime`) – the date & time to display
Return type:	text string

javaproperties.join_key_value(key, value, separator='=')¶

Join a key and value together into a single line suitable for adding to a simple line-oriented .properties file. No trailing newline is added.

>>> join_key_value('possible separators', '= : space')
'possible\\ separators=\\= \\: space'

Parameters:	key (text string) – the key value (text string) – the value separator (text string) – the string to use for separating the key & value. Only `" "`, `"="`, and `":"` (possibly with added whitespace) should ever be used as the separator.
Return type:	text string

javaproperties.parse(fp)¶

Parse the contents of the readline-supporting file-like object fp as a simple line-oriented .properties file and return a generator of (key, value, original_lines) triples for every entry in fp (including duplicate keys) in order of occurrence. The third element of each triple is the concatenation of the unmodified lines in fp (including trailing newlines) from which the key and value were extracted. The generator also includes comments and blank/all-whitespace lines found in fp, one triple per line, with the first two elements of the triples set to None. This is the only way to extract comments from a .properties file with this library.

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.

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
Return type:	generator of triples of text strings
Raises:	InvalidUEscapeError – if an invalid `\uXXXX` escape sequence occurs in the input

javaproperties.to_comment(comment)¶

Convert a string to a .properties file comment. All non-Latin-1 characters in the string are escaped using \uXXXX escapes (after converting non-BMP characters to surrogate pairs), a # is prepended to the string, any CR LF or CR line breaks in the string are converted to LF, and a # is inserted after any line break not already followed by a # or !. No trailing newline is added.

>>> to_comment('They say foo=bar,\r\nbut does bar=foo?')
'#They say foo=bar,\n#but does bar=foo?'

Parameters:	comment (text string) – the string to convert to a comment
Return type:	text string

javaproperties.unescape(field)¶

Decode escape sequences in a .properties key or value. The following escape sequences are recognized:

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

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

In addition, any valid UTF-16 surrogate pairs in the string after escape-decoding are further decoded into the non-BMP characters they represent. (Invalid & isolated surrogate code points are left as-is.)

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

Parameters:	field (text string) – the string to decode
Return type:	text string
Raises:	InvalidUEscapeError – if an invalid `\uXXXX` escape sequence occurs in the input

exception javaproperties.InvalidUEscapeError(escape)¶

Bases: ValueError

New in version 0.5.0.

Raised when an invalid \uXXXX escape sequence (i.e., a \u not immediately followed by four hexadecimal digits) is encountered in a simple line-oriented .properties file