Low-Level Utilities

javaproperties.escape(field, ensure_ascii=True)[source]

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).

Changed in version 0.6.0: ensure_ascii parameter added

Parameters

  • field (text string) – the string to escape

  • ensure_ascii (bool) – if true, all non-ASCII characters will be replaced with \uXXXX escape sequences in the output; if false, non-ASCII characters will be passed through as-is

Return type

text string

javaproperties.java_timestamp(timestamp=True)[source]

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='=', ensure_ascii=True)[source]

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'

Changed in version 0.6.0: ensure_ascii parameter added

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.

  • ensure_ascii (bool) – if true, all non-ASCII characters will be replaced with \\uXXXX escape sequences in the output; if false, non-ASCII characters will be passed through as-is

Return type

text string

javaproperties.parse(fp)[source]

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, ensure_ascii=None)[source]

Convert a string to a .properties file comment. Non-Latin-1 or non-ASCII characters in the string may be escaped using \uXXXX escapes (depending on the value of ensure_ascii), 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?'

Changed in version 0.6.0: ensure_ascii parameter added

Parameters

  • comment (text string) – the string to convert to a comment

  • ensure_ascii – if true, all non-ASCII characters will be replaced with \uXXXX escape sequences in the output; if None, only non-Latin-1 characters will be escaped; if false, no characters will be escaped

Return type

text string

javaproperties.unescape(field)[source]

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)[source]

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

escape = None

The invalid \uXXXX escape sequence encountered

Custom Encoding Error Handler

New in version 0.6.0.

Importing javaproperties causes a custom error handler, 'javapropertiesreplace', to be automatically defined that can then be supplied as the errors argument to str.encode, open, or similar encoding operations in order to cause all unencodable characters to be replaced by \uXXXX escape sequences (with non-BMP characters converted to surrogate pairs first).

This is useful, for example, when calling javaproperties.dump(obj, fp, ensure_ascii=False) where fp has been opened using an encoding that does not contain all Unicode characters (e.g., Latin-1); in such a case, if errors='javapropertiesreplace' is supplied when opening fp, then any characters in a key or value of obj that exist outside fp’s character set will be safely encoded as .properties file format-compatible escape sequences instead of raising an error.

Note that the hexadecimal value used in a \uXXXX escape sequences is always based on the source character’s codepoint value in Unicode regardless of the target encoding:

>>> # Here we see one character encoded to the byte 0x00f0 (because that's
>>> # how the target encoding represents it) and a completely different
>>> # character encoded as the escape sequence \u00f0 (because that's its
>>> # value in Unicode):
>>> 'apple: \uF8FF; edh: \xF0'.encode('mac_roman', 'javapropertiesreplace')
b'apple: \xf0; edh: \\u00f0'
javaproperties.javapropertiesreplace_errors(e)[source]

New in version 0.6.0.

Implements the 'javapropertiesreplace' error handling (for text encodings only): unencodable characters are replaced by \uXXXX escape sequences (with non-BMP characters converted to surrogate pairs first)