Low-Level Utilities

javaproperties.escape(field: str, ensure_ascii: bool = True) → str

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 (str) – 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:

str

javaproperties.java_timestamp(timestamp: None | bool | float | datetime = True) → str

Added 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:

str

javaproperties.join_key_value(key: str, value: str, separator: str = '=', ensure_ascii: bool = True) → str

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 (str) – the key

• value (str) – the value

• separator (str) – 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:

str

javaproperties.to_comment(comment: str, ensure_ascii: bool | None = None) → str

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 (str) – the string to convert to a comment

• ensure_ascii (Optional[bool]) – 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:

str

javaproperties.unescape(field: str) → str

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 (str) – the string to decode

Return type:

str

Raises:

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

exception javaproperties.InvalidUEscapeError(escape: str)

Bases: ValueError

Added 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: str

The invalid \uXXXX escape sequence encountered

Low-Level Parsing

javaproperties.parse(src: IO | str | bytes) → Iterator[PropertiesElement]

Parse the given data as a simple line-oriented .properties file and return a generator of PropertiesElement objects representing the key-value pairs (as KeyValue objects), comments (as Comment objects), and blank lines (as Whitespace objects) in the input in order of occurrence.

If the same key appears multiple times in the input, a separate KeyValue object is emitted for each entry.

src may be a text string, a bytes string, or a text or binary filehandle/file-like object supporting the readline method (with or without universal newlines enabled). Bytes input is decoded as Latin-1.

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

Changed in version 0.7.0: parse() now accepts strings as input, and it now returns a generator of custom objects instead of triples of strings

Parameters:

src (string or file-like object) – the .properties document

Return type:

Iterator[PropertiesElement]

Raises:

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

class javaproperties.PropertiesElement(source: str)

Added in version 0.7.0.

Superclass of objects returned by parse()

source: str

The raw, unmodified input line (including trailing newlines)

property source_stripped: str

Like source, but with the final trailing newline and line continuation (if any) removed

class javaproperties.Comment(source: str)

Added in version 0.7.0.

Subclass of PropertiesElement representing a comment

is_timestamp() → bool

Returns True iff the comment’s value appears to be a valid timestamp as produced by Java 8’s Date.toString()

property source_stripped: str

Like source, but with the final trailing newline (if any) removed

property value: str

Returns the contents of the comment, with the comment marker, any whitespace leading up to it, and the trailing newline removed

class javaproperties.KeyValue(key: str, value: str, source: str)

Added in version 0.7.0.

Subclass of PropertiesElement representing a key-value entry

key: str

The entry’s key, after processing escape sequences

value: str

The entry’s value, after processing escape sequences

class javaproperties.Whitespace(source: str)

Added in version 0.7.0.

Subclass of PropertiesElement representing a line that is either empty or contains only whitespace (and possibly some line continuations)

Custom Encoding Error Handler

Added 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: UnicodeError) → tuple[str, int]

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