diff --git a/sopel/irc/utils.py b/sopel/irc/utils.py index 3d3bf450f..a812f9687 100644 --- a/sopel/irc/utils.py +++ b/sopel/irc/utils.py @@ -17,28 +17,32 @@ from sopel.lifecycle import deprecated -def safe(string): - """Remove newlines from a string. +def safe(string: str) -> str: + """Remove disallowed bytes from a string, and ensure Unicode. - :param str string: input text to process - :return: the string without newlines - :rtype: str + :param string: input text to process + :return: the string as Unicode without characters prohibited in IRC messages :raises TypeError: when ``string`` is ``None`` - This function removes newlines and null-bytes from a string. It will always + This function removes newlines and null bytes from a string. It will always return a Unicode ``str``, even if given non-Unicode input, but doesn't strip or alter the string in any other way:: - >>> safe('some \x00text\\r\\n') + >>> safe('some \\x00text\\r\\n') 'some text' - This is useful to ensure a string can be used in a IRC message. + This is useful to ensure a string can be used in a IRC message. Parameters + can **never** contain NUL, CR, or LF octets, per :rfc:`2812#section-2.3.1`. .. versionchanged:: 7.1 This function now raises a :exc:`TypeError` instead of an unpredictable behaviour when given ``None``. + .. versionchanged:: 8.0.1 + + Also remove NUL (``\\x00``) in addition to CR/LF. + """ if string is None: raise TypeError('safe function requires a string, not NoneType')