Add "Lineup" class.

Author: domdfcoding

domdf_python_tools/bases.py

@@ -58,8 +58,24 @@
 # this package
 from domdf_python_tools.doctools import prettify_docstrings
 
-__all__ = ["Dictable", "NamedList", "namedlist", "UserList", "UserFloat"]
+__all__ = [
+		"Dictable",
+		"NamedList",
+		"namedlist",
+		"UserList",
+		"UserFloat",
+		"Lineup",
+		"_V",
+		"_LU",
+		"_T",
+		"_S",
+		"_F",
+		]
 
+_F = TypeVar("_F", bound="UserFloat")
+_LU = TypeVar("_LU", bound="Lineup")
+_S = TypeVar("_S", bound="UserList")
+_T = TypeVar("_T")
 _V = TypeVar("_V")
 
 
@@ -110,10 +126,6 @@ def __eq__(self, other) -> bool:
 		return NotImplemented
 
 
-_T = TypeVar("_T")
-_S = TypeVar("_S", bound="UserList")
-
-
 @prettify_docstrings
 class UserList(MutableSequence[_T]):
 	"""
@@ -363,9 +375,6 @@ def __index__(self) -> int:
 		...
 
 
-_F = TypeVar("_F", bound="UserFloat")
-
-
 @prettify_docstrings
 class UserFloat(Real):
 	"""
@@ -462,6 +471,10 @@ def __getnewargs__(self) -> Tuple[float]:
 		return self._value
 
 	def __trunc__(self) -> int:
+		"""
+		Truncates the float to an integer.
+		"""
+
 		return float(self).__trunc__()
 
 	def __round__(self, ndigits: Optional[int] = None) -> Union[int, float]:  # type: ignore
@@ -533,6 +546,22 @@ def __ceil__(self):
 	def __floor__(self):
 		raise NotImplementedError
 
+	def __bool__(self) -> bool:
+		"""
+		Return ``self != 0``.
+		"""
+
+		return super().__bool__()
+
+	def __complex__(self) -> complex:
+		"""
+		Returrn :func:`complex(self) <complex>``.
+
+		``complex(self) == complex(float(self), 0)``
+		"""
+
+		return super().__complex__()
+
 
 @prettify_docstrings
 class NamedList(UserList[_T]):
@@ -566,3 +595,79 @@ class cls(NamedList):
 	cls.__name__ = name
 
 	return cls
+
+
+class Lineup(UserList[_T]):
+	"""
+	List-like type with fluent methods and some star players.
+	"""
+
+	def replace(self: _LU, what: _T, with_: _T) -> _LU:
+		r"""
+		Replace the first instance of ``what`` with ``with_``.
+
+		:param what: The object to find and replace.
+		:param with\_: The new value for the position in the list.
+		"""
+
+		self[self.index(what)] = with_
+
+		return self
+
+	def sort(
+			self: _LU,
+			*,
+			key=None,
+			reverse: bool = False,
+			) -> _LU:  # type: ignore
+		"""
+		Sort the list in ascending order and return the self.
+
+		The sort is in-place (i.e. the list itself is modified) and stable (i.e. the
+		order of two equal elements is maintained).
+
+		If a key function is given, apply it once to each list item and sort them,
+		ascending or descending, according to their function values.
+
+		The reverse flag can be set to sort in descending order.
+		"""
+
+		super().sort(key=key, reverse=reverse)
+		return self
+
+	def reverse(self: _LU, ) -> _LU:  # type: ignore
+		super().reverse()
+		return self
+
+	def append(
+			self: _LU,
+			item: _T,
+			) -> _LU:  # type: ignore
+		super().append(item)
+		return self
+
+	def extend(
+			self: _LU,
+			other: Iterable[_T],
+			) -> _LU:  # type: ignore
+		super().extend(other)
+		return self
+
+	def insert(
+			self: _LU,
+			i: int,
+			item: _T,
+			) -> _LU:  # type: ignore
+		super().insert(i, item)
+		return self
+
+	def remove(
+			self: _LU,
+			item: _T,
+			) -> _LU:  # type: ignore
+		super().remove(item)
+		return self
+
+	def clear(self: _LU, ) -> _LU:  # type: ignore
+		super().clear()
+		return self

tests/test_userlist.py

@@ -12,7 +12,7 @@
 from typing import Sequence, Type, no_type_check
 
 # this package
-from domdf_python_tools.bases import UserList
+from domdf_python_tools.bases import Lineup, UserList
 from domdf_python_tools.testing import not_pypy
 from tests import list_tests
 
@@ -78,3 +78,31 @@ def test_radd_specials(self):
 		assert u2 == list("spameggs")
 		u2 = u.__radd__(UserList("spam"))
 		assert u2 == list("spameggs")
+
+
+class TestLineup(TestList):
+	type2test: Type[Lineup] = Lineup
+
+	def test_replace(self):
+		u = self.type2test([-2, -1, 0, 1, 2])
+
+		u.replace(2, 3)
+		assert u[-1] == 3
+
+	def test_fluent(self):
+		u = self.type2test([2, 1, 0, -1, -2])
+
+		assert u.sort() is u
+		assert u == [-2, -1, 0, 1, 2]
+
+		assert u.replace(2, 3) is u
+		assert u == [-2, -1, 0, 1, 3]
+
+		assert u.reverse() is u
+		assert u == [3, 1, 0, -1, -2]
+
+		assert u.append(4) is u
+		assert u == [3, 1, 0, -1, -2, 4]
+
+		assert u.insert(0, -3) is u
+		assert u == [-3, 3, 1, 0, -1, -2, 4]