Add function for replacing nonprinting (control) characters with ^ and M+ notation.

Author: domdfcoding

domdf_python_tools/utils.py

@@ -30,7 +30,7 @@
 
 """
 #
-#  Copyright © 2018-2020 Dominic Davis-Foster <dominic@davis-foster.co.uk>
+#  Copyright © 2018-2022 Dominic Davis-Foster <dominic@davis-foster.co.uk>
 #
 #  Permission is hereby granted, free of charge, to any person obtaining a copy
 #  of this software and associated documentation files (the "Software"), to deal
@@ -84,6 +84,7 @@
 		List,
 		Optional,
 		Pattern,
+		Set,
 		Tuple,
 		TypeVar,
 		Union,
@@ -128,6 +129,7 @@
 		"divide",
 		"redivide",
 		"unique_sorted",
+		"replace_nonprinting",
 		]
 
 #: The current major python version.
@@ -346,6 +348,13 @@ def posargs2kwargs(
 	elif callable(posarg_names):
 		posarg_names = inspect.getfullargspec(posarg_names).args
 
+	for name, arg_value in zip(posarg_names, args):
+		if name in kwargs:
+			if isinstance(posarg_names, MethodType):
+				raise TypeError(f"{posarg_names.__name__}(): got multiple values for argument '{name}'")
+			else:
+				raise TypeError(f"got multiple values for argument '{name}'")
+
 	kwargs.update(zip(posarg_names, args))
 
 	if self_arg is not None and self_arg in kwargs:
@@ -613,3 +622,38 @@ def unique_sorted(
 	"""
 
 	return sorted(set(elements), key=key, reverse=reverse)
+
+
+def replace_nonprinting(string: str, exclude: Optional[Set[int]] = None) -> str:
+	"""
+	Replace nonprinting (control) characters in ``string`` with ``^`` and ``M-`` notation.
+
+	.. versionadded:: 3.3.0
+
+	:param string:
+	:param exclude: A set of codepoints to exclude.
+
+	:rtype:
+
+	.. seealso:: :wikipedia:`C0 and C1 control codes` on Wikipedia
+	"""
+
+	# https://stackoverflow.com/a/44952259
+
+	if exclude is None:
+		exclude = set()
+
+	translation_map = {}
+
+	for codepoint in range(32):
+		if codepoint not in exclude:
+			translation_map[codepoint] = f"^{chr(64 + codepoint)}"
+
+	if 127 not in exclude:
+		translation_map[127] = "^?"
+
+	for codepoint in range(128, 256):
+		if codepoint not in exclude:
+			translation_map[codepoint] = f"M+{chr(codepoint-64)}"
+
+	return string.translate(translation_map)

tests/test_utils.py

@@ -36,6 +36,7 @@
 		pyversion,
 		redirect_output,
 		redivide,
+		replace_nonprinting,
 		stderr_writer,
 		str2tuple,
 		strtobool,
@@ -527,3 +528,18 @@ def test_redivide_errors():
 		)
 def test_unique_sorted(values, expected):
 	assert unique_sorted(values) == expected
+
+
+@pytest.mark.parametrize(
+		"the_string, expected",
+		[
+				("\t\t\t", "^I^I^I"),
+				("\u0000\u0000\u0000", "^@^@^@"),
+				("\r\n", "^M^J"),
+				("\b\u000b", "^H^K"),
+				("\u001a", "^Z^?"),
+				('\x81', "M+A"),
+				]
+		)
+def test_replace_nonprinting(the_string: str, expected: str):
+	assert replace_nonprinting(the_string) == expected