Low-Level Utilities¶
-
javaproperties.
escape
(field)[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\uXXXX
escapes (after converting non-BMP characters to surrogate pairs) or the single-character escapes recognized byunescape
.Parameters: field (text string) – the string to escape 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
isTrue
(the default), the current date & time is returned.If
timestamp
isNone
orFalse
, an empty string is returned.If
timestamp
is a number, it is converted from seconds since the epoch to local time.If
timestamp
is adatetime.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, ordatetime.datetime
) – the date & time to displayReturn type: text string
-
javaproperties.
join_key_value
(key, value, separator=u'=')[source]¶ Join a key and value together into a single line suitable for adding to a
.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)[source]¶ Parse the contents of the
readline
-supporting file-like objectfp
as a.properties
file and return a generator of(key, value, original_lines)
triples for every entry infp
(including duplicate keys) in order of occurrence. The third element of each triple is the concatenation of the unmodified lines infp
(including trailing newlines) from which the key and value were extracted. The generator also includes comments and blank/all-whitespace lines found infp
, one triple per line, with the first two elements of the triples set toNone
. 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.Parameters: fp (file-like object) – the file from which to read the .properties
documentReturn type: generator of triples of text strings
-
javaproperties.
to_comment
(comment)[source]¶ 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)[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.)
Parameters: field (text string) – the string to decode Return type: text string