Updated documentation.

domdfcoding · domdfcoding · commit 7fe37779d957 · 2020-08-10T22:57:26.000+01:00
diff --git a/doc-source/api/bases.rst b/doc-source/api/bases.rst
@@ -5,4 +5,6 @@
 .. automodule:: domdf_python_tools.bases
 	:autosummary:
 	:members:
-	:undoc-members:
+	:inherited-members:
+	:special-members:
+	:exclude-members: __dict__, __subclasshook__, __init_subclass__, __init__, __weakref__
diff --git a/doc-source/api/import_tools.rst b/doc-source/api/import_tools.rst
@@ -0,0 +1,8 @@
+**************************************
+:mod:`domdf_python_tools.import_tools`
+**************************************
+
+.. automodule:: domdf_python_tools.import_tools
+	:autosummary:
+	:members:
+	:undoc-members:
diff --git a/doc-source/api/secrets.rst b/doc-source/api/secrets.rst
@@ -0,0 +1,9 @@
+*********************************
+:mod:`domdf_python_tools.secrets`
+*********************************
+
+.. automodule:: domdf_python_tools.secrets
+	:members:
+	:autosummary:
+	:special-members:
+	:exclude-members: __weakref__
diff --git a/doc-source/api/terminal.rst b/doc-source/api/terminal.rst
@@ -6,3 +6,4 @@
 	:members:
 	:autosummary:
 	:undoc-members:
+	:special-members:
diff --git a/doc-source/api/typing.rst b/doc-source/api/typing.rst
@@ -0,0 +1,8 @@
+***********************************
+:mod:`domdf_python_tools.typing`
+***********************************
+
+.. automodule:: domdf_python_tools.typing
+	:members:
+	:autosummary:
+	:undoc-members:
diff --git a/doc-source/api/words.rst b/doc-source/api/words.rst
@@ -0,0 +1,7 @@
+*********************************
+:mod:`domdf_python_tools.words`
+*********************************
+
+.. automodule:: domdf_python_tools.words
+	:members:
+	:autosummary:
diff --git a/domdf_python_tools/dates.py b/domdf_python_tools/dates.py
@@ -202,7 +202,6 @@ def parse_month(month: Union[str, int]) -> str:
 	:type month: str or int
 
 	:return: The full name of the month
-	:rtype: str
 	"""
 
 	try:
diff --git a/domdf_python_tools/doctools.py b/domdf_python_tools/doctools.py
@@ -39,10 +39,8 @@ def deindent_string(string: Optional[str]) -> str:
 	Removes all indentation from the given string.
 
 	:param string: The string to deindent
-	:type string: str
 
 	:return: The string without indentation
-	:rtype: str
 	"""
 
 	if not string:
@@ -106,12 +104,9 @@ def make_sphinx_links(input_string: str, builtins_list: Optional[Sequence[str]]
 	`intersphinx_mapping` dict of your conf.py for sphinx.
 
 	:param input_string: The string to process
-	:type input_string: str
 	:param builtins_list: A list of builtins to make links for
-	:type builtins_list: list of str
 
 	:return: processed string with links
-	:rtype: str
 	"""
 
 	if builtins_list is None:
@@ -164,8 +159,8 @@ def sphinxify_docstring() -> Callable:
 
 	i.e. \`\`str\`\` becomes \:class\:\`~python:str\`
 
-	Make sure to have `'python': ('https://docs.python.org/3/', None),` in the
-	`intersphinx_mapping` dict of your conf.py for sphinx.
+	Make sure to have ``'python': ('https://docs.python.org/3/', None),`` in the
+	``intersphinx_mapping`` dict of your ``conf.py`` file for Sphinx.
 	"""
 
 	def wrapper(target: F) -> F:
diff --git a/domdf_python_tools/import_tools.py b/domdf_python_tools/import_tools.py
@@ -56,13 +56,13 @@ def discover(
 		match_func: Optional[Callable[[Any], bool]] = None,
 		) -> List[Type[Any]]:
 	"""
-	Returns a set of objects in the directory matched by match_func
+	Returns a list of objects in the directory matched by match_func
 
 	:param package: A Python package
 	:param match_func: Function taking an object and returning true if the object is to be included in the output.
+	:default match_func: :py:obj:`None`, which includes all objects.
 
-	:return:
-	:rtype:
+	:return: List of matching objects.
 	"""
 
 	matched_classes = list()
diff --git a/domdf_python_tools/paths.py b/domdf_python_tools/paths.py
@@ -174,7 +174,6 @@ def read(filename: PathLike, **kwargs) -> str:
 	:param filename: The file to read from
 
 	:return: The contents of the file
-	:rtype: str
 	"""
 
 	with open(os.path.join(os.getcwd(), filename), **kwargs) as f:
diff --git a/domdf_python_tools/secrets.py b/domdf_python_tools/secrets.py
@@ -0,0 +1,56 @@
+#  !/usr/bin/env python
+#
+#  secrets.py
+"""
+Functions for working with secrets, such as API tokens.
+"""
+#
+#  Copyright © 2020 Dominic Davis-Foster <dominic@davis-foster.co.uk>
+#
+#  This program is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program; if not, write to the Free Software
+#  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+#  MA 02110-1301, USA.
+#
+
+
+class Secret(str):
+	"""
+	Subclass of :py:class:`str` that guards against accidentally printing a secret to the terminal.
+
+	The actual value of the secret is accessed via the ``.value`` attribute.
+
+	The protection should be maintained even when the secret is in a list, tuple, set or dict,
+	but you should still refrain from printing objects containing the secret.
+
+	The secret overrides the :meth:`~.__eq__` method of :class:`str`, so:
+
+		.. code-block:: python
+
+			>>> Secret("Barry as FLUFL") == "Barry as FLUFL"
+			True
+
+	"""
+
+	value: str  #: The actual value of the secret.
+
+	def __new__(cls, value) -> "Secret":
+		obj: Secret = super().__new__(cls, "<SECRET>")  # type: ignore
+		obj.value = str(value)
+		return obj
+
+	def __eq__(self, other) -> bool:
+		return self.value == other
+
+	def __hash__(self):
+		return hash(self.value)
diff --git a/domdf_python_tools/terminal_colours.py b/domdf_python_tools/terminal_colours.py
@@ -162,7 +162,6 @@ def UP(self, n: int = 1) -> str:
 		:type n: int
 
 		:return:
-		:rtype: str
 		"""
 
 		return f"{CSI}{str(n)}A"
@@ -174,7 +173,6 @@ def DOWN(self, n: int = 1) -> str:
 		:type n: int
 
 		:return:
-		:rtype: str
 		"""
 
 		return f"{CSI}{str(n)}B"
@@ -186,7 +184,6 @@ def FORWARD(self, n: int = 1) -> str:
 		:type n: int
 
 		:return:
-		:rtype: str
 		"""
 
 		return f"{CSI}{str(n)}C"
@@ -198,7 +195,6 @@ def BACK(self, n: int = 1) -> str:
 		:type n: int
 
 		:return:
-		:rtype: str
 		"""
 
 		return f"{CSI}{str(n)}D"
@@ -212,7 +208,6 @@ def POS(self, x: int = 1, y: int = 1) -> str:
 		:type y: int
 
 		:return:
-		:rtype: str
 		"""
 
 		return f"{CSI}{str(y)};{str(x)}H"
diff --git a/domdf_python_tools/typing.py b/domdf_python_tools/typing.py
@@ -28,6 +28,7 @@
 import pathlib
 from typing import Any, Type, Union
 
+#: Type hint for objects that represent filesystem paths.
 PathLike = Union[str, pathlib.Path, os.PathLike]
 
 
diff --git a/domdf_python_tools/utils.py b/domdf_python_tools/utils.py
@@ -37,6 +37,7 @@
 #
 
 # stdlib
+import itertools
 import sys
 from typing import Any, Generator, Iterable, List, Sequence, Tuple, Union
 
@@ -68,8 +69,6 @@ def as_text(value: Any) -> str:
 	Convert the given value to a string. ``None`` is converted to ``''``.
 
 	:param value: Value to convert to a string
-
-	:rtype: str
 	"""
 
 	if value is None:
@@ -131,8 +130,6 @@ def cmp(x, y) -> int:
 	Compare the two objects x and y and return an integer according to the outcome.
 
 	The return value is negative if x < y, zero if x == y and strictly positive if x > y.
-
-	:rtype: int
 	"""
 
 	return int((x > y) - (x < y))
@@ -142,13 +139,10 @@ def list2str(the_list: Iterable[Any], sep: str = ',') -> str:
 	"""
 	Convert an iterable, such as a list, to a comma separated string.
 
-	:param the_list: The iterable to convert to a string
-	:type the_list: ~collections.abc.Iterable
-	:param sep: Separator to use for the string. Default `,`
-	:type sep: str
+	:param the_list: The iterable to convert to a string.
+	:param sep: Separator to use for the string.
 
 	:return: Comma separated string
-	:rtype: str
 	"""
 
 	return sep.join([str(x) for x in the_list])
@@ -164,14 +158,9 @@ def permutations(data: Iterable[Any], n: int = 2) -> List[Tuple[Any, ...]]:
 	If ``n`` is equal to or greater than the length of the data an empty list of returned.
 
 	:param data:
-	:type data: ~collections.abc.Iterable
 	:param n:
-	:type n: int
 	"""
 
-	# stdlib
-	import itertools
-
 	if n == 0:
 		raise ValueError("'n' cannot be 0")
 
@@ -267,9 +256,9 @@ def strtobool(val: Union[str, bool]) -> bool:
 		return bool(val)
 
 	val = val.lower()
-	if val in ('y', "yes", 't', "true", "on", '1'):
+	if val in {'y', "yes", 't', "true", "on", '1'}:
 		return True
-	elif val in ('n', "no", 'f', "false", "off", '0'):
+	elif val in {'n', "no", 'f', "false", "off", '0'}:
 		return False
 	else:
 		raise ValueError(f"invalid truth value {val!r}")
@@ -288,5 +277,7 @@ def enquote_value(value: Any) -> Union[str, bool, float]:
 		return value
 	elif isinstance(value, (int, float)):
 		return value
+	elif isinstance(value, str):
+		return repr(value)
 	else:
 		return f"'{value}'"
diff --git a/tests/test_secrets.py b/tests/test_secrets.py
@@ -0,0 +1,26 @@
+# 3rd party
+import pytest
+
+# this package
+from domdf_python_tools.secrets import Secret
+from domdf_python_tools.words import get_words_list
+
+
+@pytest.mark.parametrize("value", get_words_list())
+def test_secret(value):
+	the_secret = Secret(value)
+	assert isinstance(the_secret, str)
+	assert isinstance(the_secret.value, str)
+	assert the_secret.value == value
+	assert the_secret == value
+	assert str(the_secret) == "<SECRET>"
+	assert repr(the_secret) == "'<SECRET>'"
+	assert str([the_secret]) == "['<SECRET>']"
+	assert str((the_secret, )) == "('<SECRET>',)"
+	assert str({the_secret}) == "{'<SECRET>'}"
+	assert str({"token": the_secret}) == "{'token': '<SECRET>'}"
+	assert repr([the_secret]) == "['<SECRET>']"
+	assert repr((the_secret, )) == "('<SECRET>',)"
+	assert repr({the_secret}) == "{'<SECRET>'}"
+	assert repr({"token": the_secret}) == "{'token': '<SECRET>'}"
+	assert hash(the_secret) == hash(value)
