Added 'head' function to utils.

Author: domdfcoding

.isort.cfg

@@ -21,6 +21,7 @@ known_third_party =
     faker
     github
     importlib_resources
+    pandas
     pydash
     pytest
     pytest_cov

doc-source/api/utils.rst

@@ -3,4 +3,3 @@
 =================================
 
 .. automodule:: domdf_python_tools.utils
-	:undoc-members:

doc-source/requirements.txt

@@ -2,13 +2,14 @@ autodocsumm>=0.2.0
 default_values>=0.0.9
 domdf_sphinx_theme>=0.1.0
 extras_require>=0.2.0
+pandas>=1.0.0
 seed_intersphinx_mapping>=0.1.1
 sphinx>=3.0.3
 sphinx-copybutton>=0.2.12
 sphinx-notfound-page>=0.5
 sphinx-prompt>=1.1.0
 sphinx-tabs>=1.1.13
-sphinx-toolbox>=0.3.3
+sphinx-toolbox>=0.5.0
 sphinxcontrib-httpdomain>=1.7.0
 sphinxemoji>=0.1.6
 toctree_plus>=0.0.4

domdf_python_tools/utils.py

@@ -52,15 +52,22 @@
 import inspect
 import itertools
 import sys
-from typing import Any, Callable, Dict, Generator, Iterable, List, Optional, Sequence, Tuple, Union
+from pprint import pformat
+from typing import TYPE_CHECKING, Any, Callable, Dict, Generator, Iterable, List, Optional, Sequence, Tuple, Union
 
 # 3rd party
 import deprecation  # type: ignore
+from typing_extensions import Protocol, runtime_checkable
 
 # this package
 import domdf_python_tools.words
 from domdf_python_tools import __version__
 
+if TYPE_CHECKING:
+	# 3rd party
+	from pandas import DataFrame, Series  # type: ignore
+	from pandas._typing import FrameOrSeries  # type: ignore
+
 __all__ = [
 		"pyversion",
 		"SPACE_PLACEHOLDER",
@@ -82,6 +89,9 @@
 		"double_chain",
 		"posargs2kwargs",
 		"convert_indents",
+		"etc",
+		"head",
+		"HasHead",
 		]
 
 #: The current major python version.
@@ -91,6 +101,16 @@
 SPACE_PLACEHOLDER = '␣'
 
 
+@runtime_checkable
+class String(Protocol):
+	"""
+	Protocol for classes that implement ``__str__``.
+	"""
+
+	def __str__(self) -> str:
+		...  # pragma: no cover
+
+
 def check_dependencies(dependencies: Iterable[str], prt: bool = True) -> List[str]:
 	"""
 	Check whether one or more dependencies are available to be imported.
@@ -415,3 +435,70 @@ def convert_indents(text: str, tab_width: int = 4, from_: str = "\t", to: str =
 		)(
 				domdf_python_tools.words.word_join
 				)
+
+
+@runtime_checkable
+class HasHead(Protocol):
+	"""
+	:class:`typing.Protocol` for classes that have a ``head``.
+
+	This includes :class:`pandas.DataFrame` and :class:`pandas.Series`.
+	"""
+
+	def head(self: "FrameOrSeries", n: int = 5) -> "FrameOrSeries":
+		...  # pragma: no cover
+
+	def to_string(self, *args, **kwargs) -> Optional[str]:
+		...  # pragma: no cover
+
+
+class _Etcetera(str):
+
+	def __new__(cls):
+		return str.__new__(cls, "...")  # type: ignore
+
+	def __repr__(self) -> str:
+		return str(self)
+
+
+etc = _Etcetera()
+"""
+Object that provides an ellipsis string
+
+.. versionadded:: 0.8.0
+"""
+
+
+def head(obj: Union[Tuple, List, "DataFrame", "Series", "String"], n: int = 10) -> str:
+	"""
+	Returns the head of the given object.
+
+	:param obj:
+	:param n: Show the first ``n`` items of ``obj``.
+
+	.. versionadded:: 0.8.0
+	"""
+
+	if isinstance(obj, tuple) and hasattr(obj, "_fields"):
+		if len(obj) <= n:
+			return repr(obj)
+		else:
+			# Likely a namedtuple
+			head_of_namedtuple = {k: v for k, v in zip(obj._fields[:n], obj[:n])}  # type: ignore
+			repr_fmt = '(' + ', '.join(f'{k}={v!r}' for k, v in head_of_namedtuple.items()) + f', {etc})'
+			return obj.__class__.__name__ + repr_fmt
+
+	elif isinstance(obj, (list, tuple)):
+		if len(obj) > n:
+			return pformat(obj.__class__((*obj[:n], etc)))
+		else:
+			return pformat(obj)
+
+	elif isinstance(obj, HasHead):
+		return obj.head(n).to_string()
+
+	elif len(obj) <= n:  # type: ignore
+		return str(obj)
+
+	else:
+		return str(obj[:n]) + etc  # type: ignore

tests/requirements.txt

@@ -1,6 +1,7 @@
 coverage>=5.1
 coverage_pyver_pragma>=0.0.5
 faker>=4.1.2
+pandas>=1.0.0; implementation_name == "cpython" and python_version < "3.9"
 pytest>=6.0.0
 pytest-cov>=2.8.1
 pytest-randomly>=3.3.1

tests/test_utils.py

@@ -13,13 +13,15 @@
 import re
 import sys
 import types
+from collections import namedtuple
 
 # 3rd party
 import pytest
 
 # this package
 from domdf_python_tools import utils
 from domdf_python_tools.testing import testing_boolean_values
+from domdf_python_tools.utils import HasHead, head
 
 
 def test_pyversion():
@@ -433,3 +435,74 @@ def test_convert_indents():
 	assert utils.convert_indents("hello world", tab_width=2, from_="    ") == "hello world"
 	assert utils.convert_indents("    hello world", tab_width=2, from_="    ") == "  hello world"
 	assert utils.convert_indents("        hello world", tab_width=2, from_="    ") == "    hello world"
+
+
+class TestHead:
+
+	def test_protocol(self):
+		assert not isinstance(str, HasHead)
+		assert not isinstance(int, HasHead)
+		assert not isinstance(float, HasHead)
+		assert not isinstance(tuple, HasHead)
+		assert not isinstance(list, HasHead)
+
+	def test_protocol_pandas(self):
+		pandas = pytest.importorskip("pandas")
+
+		assert isinstance(pandas.DataFrame, HasHead)
+		assert isinstance(pandas.Series, HasHead)
+
+	def test_namedtuple(self):
+		foo = namedtuple("foo", "a, b, c, d, e, f, g, h, i, j, k, l, m")
+		assert head(
+				foo(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13)
+				) == "foo(a=1, b=2, c=3, d=4, e=5, f=6, g=7, h=8, i=9, j=10, ...)"
+		assert head(
+				foo(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13), 13
+				) == "foo(a=1, b=2, c=3, d=4, e=5, f=6, g=7, h=8, i=9, j=10, k=11, l=12, m=13)"
+
+	def test_tuple(self):
+		assert head((1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13)) == "(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ...)"
+		assert head((1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13),
+					13) == "(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13)"
+
+	def test_list(self):
+		assert head([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13]) == "[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ...]"
+		assert head([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13],
+					13) == "[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13]"
+
+	def test_data_frame(self):
+		pandas = pytest.importorskip("pandas")
+
+		df = pandas.DataFrame(
+				data=[["Bob", 20, "Apprentice"], ["Alice", 23, "Secretary"], ["Mario", 39, "Plumber"]],
+				columns=["Name", "Age", "Occupation"],
+				)
+		assert head(
+				df
+				) == """    Name  Age  Occupation
+0    Bob   20  Apprentice
+1  Alice   23   Secretary
+2  Mario   39     Plumber\
+"""
+		assert head(df, 1) == "  Name  Age  Occupation\n0  Bob   20  Apprentice"
+
+	def test_series(self):
+		pandas = pytest.importorskip("pandas")
+
+		df = pandas.DataFrame(
+				data=[["Bob", 20, "Apprentice"], ["Alice", 23, "Secretary"], ["Mario", 39, "Plumber"]],
+				columns=["Name", "Age", "Occupation"],
+				)
+		ser = df.iloc[0]
+		assert head(ser) == """\
+Name                 Bob
+Age                   20
+Occupation    Apprentice\
+"""
+		assert head(ser, 1) == "Name    Bob"
+
+	def test_str(self):
+		assert head("Hello World") == "Hello Worl..."
+		assert head("Hello World", 11) == "Hello World"
+		assert head("Hello World", 5) == "Hello..."