Low-Level Utilities¶
-
javaproperties.
escape
(field: str, ensure_ascii: bool = True) → str[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 byunescape
(when they exist) or\uXXXX
escapes (after converting non-BMP characters to surrogate pairs).Changed in version 0.6.0:
ensure_ascii
parameter added
-
javaproperties.
java_timestamp
(timestamp: Union[None, bool, float, datetime.datetime] = True) → str[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 display- Return type
-
javaproperties.
join_key_value
(key: str, value: str, separator: str = '=', ensure_ascii: bool = True) → str[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 (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
-
javaproperties.
to_comment
(comment: str, ensure_ascii: Optional[bool] = None) → str[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 ofensure_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
-
javaproperties.
unescape
(field: str) → str[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 anInvalidUEscapeError
to be raised- Parameters
field (str) – the string to decode
- Return type
- Raises
InvalidUEscapeError – if an invalid
\uXXXX
escape sequence occurs in the input
-
exception
javaproperties.
InvalidUEscapeError
(escape: str)[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
Low-Level Parsing¶
-
javaproperties.
parse
(src: Union[IO, str, bytes]) → Iterator[javaproperties.reading.PropertiesElement][source]¶ Parse the given data as a simple line-oriented
.properties
file and return a generator ofPropertiesElement
objects representing the key-value pairs (asKeyValue
objects), comments (asComment
objects), and blank lines (asWhitespace
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 thereadline
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 anInvalidUEscapeError
to be raisedChanged 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)[source]¶ New in version 0.7.0.
Superclass of objects returned by
parse()
-
class
javaproperties.
Comment
(source: str)[source]¶ New in version 0.7.0.
Subclass of
PropertiesElement
representing a comment-
is_timestamp
() → bool[source]¶ Returns
True
iff the comment’s value appears to be a valid timestamp as produced by Java 8’sDate.toString()
-
property
value
¶ Returns the contents of the comment, with the comment marker, any whitespace leading up to it, and the trailing newline removed
-
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: UnicodeError) → Tuple[str, int][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)