Moved some utilities from sphinx-toolbox.

Author: domdfcoding

domdf_python_tools/utils.py

@@ -51,6 +51,7 @@
 
 __all__ = [
 		"pyversion",
+		"SPACE_PLACEHOLDER",
 		"as_text",
 		"check_dependencies",
 		"chunks",
@@ -70,10 +71,16 @@
 		"Len",
 		"double_chain",
 		"posargs2kwargs",
+		"word_join",
+		"convert_indents",
 		]
 
+#: The current major python version.
 pyversion: int = int(sys.version_info.major)  # Python Version
 
+#: The ``␣`` character.
+SPACE_PLACEHOLDER = '␣'
+
 
 def as_text(value: Any) -> str:
 	"""
@@ -372,3 +379,56 @@ def posargs2kwargs(
 	kwargs.update(zip(posarg_names, args))
 
 	return kwargs
+
+
+def word_join(iterable: Iterable[str], use_repr: bool = False, oxford: bool = False) -> str:
+	"""
+	Join the given list of strings in a natural manner, with 'and' to join the last two elements.
+
+	:param iterable:
+	:param use_repr: Whether to join the ``repr`` of each object.
+	:param oxford: Whether to use an oxford comma when joining the last two elements.
+		Always :py:obj:`False` if there are less than three elements.
+	"""
+
+	if use_repr:
+		words = [repr(w) for w in iterable]
+	else:
+		words = list(iterable)
+
+	if len(words) == 0:
+		return ''
+	elif len(words) == 1:
+		return words[0]
+	elif len(words) == 2:
+		return " and ".join(words)
+	else:
+		if oxford:
+			return ", ".join(words[:-1]) + f", and {words[-1]}"
+		else:
+			return ", ".join(words[:-1]) + f" and {words[-1]}"
+
+
+def convert_indents(text: str, tab_width: int = 4, from_: str = "\t", to: str = " ") -> str:
+	"""
+	Convert indentation at the start of lines in ``text`` from tabs to spaces.
+
+	:param text: The text to convert indents in.
+	:param tab_width: The number of spaces per tab.
+	:param from_: The indent to convert from.
+	:param to: The indent to convert to.
+	"""
+
+	output = []
+	tab = to * tab_width
+	from_size = len(from_)
+
+	for line in text.splitlines():
+		indent_count = 0
+		while line.startswith(from_):
+			indent_count += 1
+			print(indent_count)
+			line = line[from_size:]
+		output.append(f"{tab * indent_count}{line}")
+
+	return "\n".join(output)

tests/test_utils.py

@@ -20,7 +20,9 @@
 # this package
 from domdf_python_tools import utils
 from domdf_python_tools.testing import testing_boolean_values
-from domdf_python_tools.utils import Len, chunks, double_chain, list2str, posargs2kwargs, pyversion, str2tuple
+from domdf_python_tools.utils import (
+		Len, chunks, convert_indents, double_chain, list2str, posargs2kwargs, pyversion, str2tuple, word_join
+		)
 
 
 def test_pyversion():
@@ -397,3 +399,57 @@ def demo_function(arg1, arg2, arg3):
 		)
 def test_posargs2kwargs(args, posarg_names, kwargs, expects):
 	assert posargs2kwargs(args, posarg_names, kwargs) == expects
+
+
+def test_word_join():
+	assert word_join([]) == ''
+
+	assert word_join(["bob"]) == "bob"
+	assert word_join(["bob", "alice"]) == "bob and alice"
+	assert word_join(["bob", "alice", "fred"]) == "bob, alice and fred"
+
+	assert word_join(["bob"], use_repr=True) == "'bob'"
+	assert word_join(["bob", "alice"], use_repr=True) == "'bob' and 'alice'"
+	assert word_join(["bob", "alice", "fred"], use_repr=True) == "'bob', 'alice' and 'fred'"
+
+	assert word_join(["bob"], use_repr=True, oxford=True) == "'bob'"
+	assert word_join(["bob", "alice"], use_repr=True, oxford=True) == "'bob' and 'alice'"
+	assert word_join(["bob", "alice", "fred"], use_repr=True, oxford=True) == "'bob', 'alice', and 'fred'"
+
+	assert word_join(()) == ''
+
+	assert word_join(("bob", )) == "bob"
+	assert word_join(("bob", "alice")) == "bob and alice"
+	assert word_join(("bob", "alice", "fred")) == "bob, alice and fred"
+
+	assert word_join(("bob", ), use_repr=True) == "'bob'"
+	assert word_join(("bob", "alice"), use_repr=True) == "'bob' and 'alice'"
+	assert word_join(("bob", "alice", "fred"), use_repr=True) == "'bob', 'alice' and 'fred'"
+
+	assert word_join(("bob", ), use_repr=True, oxford=True) == "'bob'"
+	assert word_join(("bob", "alice"), use_repr=True, oxford=True) == "'bob' and 'alice'"
+	assert word_join(("bob", "alice", "fred"), use_repr=True, oxford=True) == "'bob', 'alice', and 'fred'"
+
+
+def test_convert_indents():
+
+	# TODO: test 'to'
+
+	assert convert_indents("hello world") == "hello world"
+	assert convert_indents("	hello world") == "    hello world"
+	assert convert_indents("		hello world") == "        hello world"
+	assert convert_indents("	    hello world") == "        hello world"
+
+	assert convert_indents("hello world", tab_width=2) == "hello world"
+	assert convert_indents("	hello world", tab_width=2) == "  hello world"
+	assert convert_indents("		hello world", tab_width=2) == "    hello world"
+	assert convert_indents("	    hello world", tab_width=2) == "      hello world"
+
+	assert convert_indents("hello world", from_="    ") == "hello world"
+	assert convert_indents("    hello world", from_="    ") == "    hello world"
+	assert convert_indents("        hello world", from_="    ") == "        hello world"
+	assert convert_indents("        hello world", from_="    ") == "        hello world"
+
+	assert convert_indents("hello world", tab_width=2, from_="    ") == "hello world"
+	assert convert_indents("    hello world", tab_width=2, from_="    ") == "  hello world"
+	assert convert_indents("        hello world", tab_width=2, from_="    ") == "    hello world"