Change implementation of NamedList to avoid issues with mypy, and updated docs.

Author: domdfcoding

doc-source/api/bases.rst

@@ -3,5 +3,51 @@
 *********************************
 
 .. automodule:: domdf_python_tools.bases
+	:no-members:
+
+Dictable
+---------
+
+.. autoclass:: domdf_python_tools.bases.Dictable
+	:inherited-members:
+	:special-members:
+
+
+NamedList
+----------
+
+Both :class:`~.NamedList` and :func:`~.namedlist` can be used to create a named list.
+
+:func:`~.namedlist` can be used as follows:
+
+.. code-block:: python
+
+	>>> ShoppingList = namedlist("ShoppingList")
+	>>> shopping_list = ShoppingList(["egg and bacon", "egg sausage and bacon", "egg and spam", "egg bacon and spam"])
+	>>>
+
+If you wish to create a subclass with additional features it is recommended to subclass
+from :class:`NamedList` rather than from :func:`~.namedlist`. For example, do this:
+
+
+.. code-block:: python
+
+	>>> class ShoppingList(NamedList):
+	...     pass
+	>>>
+
+and not this:
+
+.. code-block:: python
+
+	>>> class ShoppingList(namedlist())
+	...     pass
+	>>>
+
+This avoids any potential issues with `mypy <http://mypy-lang.org/>`_
+
+.. autoclass:: domdf_python_tools.bases.NamedList
 	:inherited-members:
 	:special-members:
+
+.. autofunction:: domdf_python_tools.bases.namedlist

domdf_python_tools/bases.py

@@ -27,7 +27,7 @@
 from abc import abstractmethod
 from collections import UserList
 from pprint import pformat
-from typing import Any, Callable, Dict, Iterable, Tuple
+from typing import Any, Dict, Iterable, Tuple, Type
 
 # 3rd party
 import pydash  # type: ignore
@@ -72,26 +72,30 @@ def __eq__(self, other) -> bool:
 		return NotImplemented
 
 
-def namedlist(name: str = "NamedList") -> Callable:
+class NamedList(UserList):
 	"""
-	A factory function to return a custom list subclass with a name.
-
-	:param name: The name of the list.
+	A list with a name.
 
-	:return:
+	The name of the list is taken from the name of the subclass.
 	"""
 
-	class NamedList(UserList):
-		"""
-		A list with a name.
-		"""
+	def __repr__(self) -> str:
+		return f"{super().__repr__()}"
+
+	def __str__(self) -> str:
+		return f"{self.__class__.__name__}{pformat(list(self))}"
+
 
-		def __repr__(self) -> str:
-			return f"{super().__repr__()}"
+def namedlist(name: str = "NamedList") -> Type[NamedList]:
+	"""
+	A factory function to return a custom list subclass with a name.
+
+	:param name: The name of the list.
+	"""
 
-		def __str__(self) -> str:
-			return f"{self.__class__.__name__}{pformat(list(self))}"
+	class cls(NamedList):
+		pass
 
-	NamedList.__name__ = name
+	cls.__name__ = name
 
-	return NamedList
+	return cls

tests/test_bases.py

@@ -15,7 +15,7 @@
 import pytest
 
 # this package
-from domdf_python_tools.bases import Dictable, namedlist
+from domdf_python_tools.bases import Dictable, NamedList, namedlist
 from domdf_python_tools.utils import printr, printt
 
 
@@ -111,8 +111,80 @@ def test_namedlist(capsys):
 
 	captured = capsys.readouterr()
 	stdout = captured.out.split("\n")
-	assert stdout[0] == "<class 'domdf_python_tools.bases.namedlist.<locals>.NamedList'>"
+	assert stdout[0] == "<class 'domdf_python_tools.bases.namedlist.<locals>.cls'>"
 	assert stdout[1] == "['egg and bacon', 'egg sausage and bacon', 'egg and spam', 'egg bacon and spam']"
 	assert stdout[2] == (
 			"ShoppingList['egg and bacon', 'egg sausage and bacon', 'egg and spam', 'egg bacon and spam']"
 			)
+
+	assert str(type(shopping_list)) == "<class 'domdf_python_tools.bases.namedlist.<locals>.cls'>"
+	assert repr(
+			shopping_list
+			) == "['egg and bacon', 'egg sausage and bacon', 'egg and spam', 'egg bacon and spam']"
+	assert str(shopping_list) == (
+			"ShoppingList['egg and bacon', 'egg sausage and bacon', 'egg and spam', 'egg bacon and spam']"
+			)
+
+
+def test_namedlist_subclass_function(capsys):
+
+	class ShoppingList(namedlist()):  # type: ignore
+		pass
+
+	shopping_list = ShoppingList(["egg and bacon", "egg sausage and bacon", "egg and spam", "egg bacon and spam"])
+	assert isinstance(shopping_list, UserList)
+	assert shopping_list[0] == "egg and bacon"
+
+	printt(shopping_list)
+	printr(shopping_list)
+	print(shopping_list)
+
+	captured = capsys.readouterr()
+	stdout = captured.out.split("\n")
+	assert stdout[0] == "<class 'tests.test_bases.test_namedlist_subclass_function.<locals>.ShoppingList'>"
+	assert stdout[1] == "['egg and bacon', 'egg sausage and bacon', 'egg and spam', 'egg bacon and spam']"
+	assert stdout[2] == (
+			"ShoppingList['egg and bacon', 'egg sausage and bacon', 'egg and spam', 'egg bacon and spam']"
+			)
+
+	assert str(
+			type(shopping_list)
+			) == "<class 'tests.test_bases.test_namedlist_subclass_function.<locals>.ShoppingList'>"
+	assert repr(
+			shopping_list
+			) == "['egg and bacon', 'egg sausage and bacon', 'egg and spam', 'egg bacon and spam']"
+	assert str(shopping_list) == (
+			"ShoppingList['egg and bacon', 'egg sausage and bacon', 'egg and spam', 'egg bacon and spam']"
+			)
+
+
+def test_namedlist_subclass_class(capsys):
+
+	class ShoppingList(NamedList):
+		pass
+
+	shopping_list = ShoppingList(["egg and bacon", "egg sausage and bacon", "egg and spam", "egg bacon and spam"])
+	assert isinstance(shopping_list, UserList)
+	assert shopping_list[0] == "egg and bacon"
+
+	printt(shopping_list)
+	printr(shopping_list)
+	print(shopping_list)
+
+	captured = capsys.readouterr()
+	stdout = captured.out.split("\n")
+	assert stdout[0] == "<class 'tests.test_bases.test_namedlist_subclass_class.<locals>.ShoppingList'>"
+	assert stdout[1] == "['egg and bacon', 'egg sausage and bacon', 'egg and spam', 'egg bacon and spam']"
+	assert stdout[2] == (
+			"ShoppingList['egg and bacon', 'egg sausage and bacon', 'egg and spam', 'egg bacon and spam']"
+			)
+
+	assert str(
+			type(shopping_list)
+			) == "<class 'tests.test_bases.test_namedlist_subclass_class.<locals>.ShoppingList'>"
+	assert repr(
+			shopping_list
+			) == "['egg and bacon', 'egg sausage and bacon', 'egg and spam', 'egg bacon and spam']"
+	assert str(shopping_list) == (
+			"ShoppingList['egg and bacon', 'egg sausage and bacon', 'egg and spam', 'egg bacon and spam']"
+			)