Updated docs.

Author: domdfcoding

.isort.cfg

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

doc-source/api/dates.rst

@@ -12,26 +12,33 @@
 
 .. automodule:: domdf_python_tools.dates
 	:undoc-members:
+	:exclude-members: months
 
-	.. py:data:: months
+	**Data:**
 
-		Mapping of months to their 3-character shortcodes.
+	.. autosummary::
 
-		Essentially:
+		~domdf_python_tools.dates.months
 
-		.. code-block:: python
 
-			months = {
-				Jan="January",
-				Feb="February",
-				Mar="March",
-				Apr="April",
-				May="May",
-				Jun="June",
-				Jul="July",
-				Aug="August",
-				Sep="September",
-				Oct="October",
-				Nov="November",
-				Dec="December",
-			}
+.. autovariable:: domdf_python_tools.dates.months
+	:no-value:
+
+	Essentially:
+
+	.. code-block:: python
+
+		months = {
+			Jan="January",
+			Feb="February",
+			Mar="March",
+			Apr="April",
+			May="May",
+			Jun="June",
+			Jul="July",
+			Aug="August",
+			Sep="September",
+			Oct="October",
+			Nov="November",
+			Dec="December",
+		}

doc-source/api/delegators.rst

@@ -3,3 +3,4 @@
 =====================================
 
 .. automodule:: domdf_python_tools.delegators
+	:members: _C,delegate_kwargs,delegates

doc-source/api/paths.rst

@@ -4,4 +4,4 @@
 
 .. automodule:: domdf_python_tools.paths
 	:undoc-members:
-	:exclude-members: __enter__,__exit__
+	:exclude-members: __enter__,__exit__,__slots__

doc-source/api/words.rst

@@ -2,15 +2,14 @@
 :mod:`domdf_python_tools.words`
 =================================
 
-Functions for working with (English) words.
-
-.. versionadded:: 0.4.5
+.. automodule:: domdf_python_tools.words
+	:no-members:
 
 .. automodulesumm:: domdf_python_tools.words
 
-.. autodata:: domdf_python_tools.words.ascii_digits
-.. autodata:: domdf_python_tools.words.greek_uppercase
-.. autodata:: domdf_python_tools.words.greek_lowercase
+.. autovariable:: domdf_python_tools.words.ascii_digits
+.. autovariable:: domdf_python_tools.words.greek_uppercase
+.. autovariable:: domdf_python_tools.words.greek_lowercase
 
 .. autofunction:: domdf_python_tools.words.get_words_list
 .. autofunction:: domdf_python_tools.words.get_random_word
@@ -19,38 +18,49 @@ Functions for working with (English) words.
 .. autoclass:: domdf_python_tools.words.Font
 	:special-members:
 
-.. autodata:: domdf_python_tools.words.SERIF_BOLD_LETTERS
-	:annotation:
+.. autovariable:: domdf_python_tools.words.SERIF_BOLD_LETTERS
+	:no-value:
+	:no-type:
 
-.. autodata:: domdf_python_tools.words.SERIF_ITALIC_LETTERS
-	:annotation:
+.. autovariable:: domdf_python_tools.words.SERIF_ITALIC_LETTERS
+	:no-value:
+	:no-type:
 
-.. autodata:: domdf_python_tools.words.SERIF_BOLD_ITALIC_LETTERS
-	:annotation:
+.. autovariable:: domdf_python_tools.words.SERIF_BOLD_ITALIC_LETTERS
+	:no-value:
+	:no-type:
 
-.. autodata:: domdf_python_tools.words.SANS_SERIF_LETTERS
-	:annotation:
+.. autovariable:: domdf_python_tools.words.SANS_SERIF_LETTERS
+	:no-value:
+	:no-type:
 
-.. autodata:: domdf_python_tools.words.SANS_SERIF_BOLD_LETTERS
-	:annotation:
+.. autovariable:: domdf_python_tools.words.SANS_SERIF_BOLD_LETTERS
+	:no-value:
+	:no-type:
 
-.. autodata:: domdf_python_tools.words.SANS_SERIF_ITALIC_LETTERS
-	:annotation:
+.. autovariable:: domdf_python_tools.words.SANS_SERIF_ITALIC_LETTERS
+	:no-value:
+	:no-type:
 
-.. autodata:: domdf_python_tools.words.SANS_SERIF_BOLD_ITALIC_LETTERS
-	:annotation:
+.. autovariable:: domdf_python_tools.words.SANS_SERIF_BOLD_ITALIC_LETTERS
+	:no-value:
+	:no-type:
 
-.. autodata:: domdf_python_tools.words.SCRIPT_LETTERS
-	:annotation:
+.. autovariable:: domdf_python_tools.words.SCRIPT_LETTERS
+	:no-value:
+	:no-type:
 
-.. autodata:: domdf_python_tools.words.FRAKTUR_LETTERS
-	:annotation:
+.. autovariable:: domdf_python_tools.words.FRAKTUR_LETTERS
+	:no-value:
+	:no-type:
 
-.. autodata:: domdf_python_tools.words.MONOSPACE_LETTERS
-	:annotation:
+.. autovariable:: domdf_python_tools.words.MONOSPACE_LETTERS
+	:no-value:
+	:no-type:
 
-.. autodata:: domdf_python_tools.words.DOUBLESTRUCK_LETTERS
-	:annotation:
+.. autovariable:: domdf_python_tools.words.DOUBLESTRUCK_LETTERS
+	:no-value:
+	:no-type:
 
 .. autofunction:: domdf_python_tools.words.as_text
 

doc-source/conf.py

@@ -17,7 +17,6 @@
 from __pkginfo__ import __version__
 
 domdf_python_tools.__docs = True
-overloads_location = "bottom"
 
 github_username = "domdfcoding"
 github_repository = "domdf_python_tools"
@@ -73,6 +72,7 @@
 		'rtd': ('https://docs.readthedocs.io/en/latest/', None),
 		"h5py": ('https://docs.h5py.org/en/latest/', None),
 		"sarge": ('https://sarge.readthedocs.io/en/latest/', None),
+		'pandas': ('https://pandas.pydata.org/docs/', None),
 		}
 
 html_theme = 'domdf_sphinx_theme'

domdf_python_tools/bases.py

@@ -51,13 +51,16 @@
 # 3rd party
 import pydash  # type: ignore
 
-__all__ = ["Dictable", "NamedList", "namedlist", "UserList"]
-
 # this package
 from domdf_python_tools.doctools import prettify_docstrings
 
+__all__ = ["Dictable", "NamedList", "namedlist", "UserList"]
+
+_V = TypeVar("_V")
+
 
-class Dictable(Iterable):
+@prettify_docstrings
+class Dictable(Iterable[Tuple[str, _V]]):
 	"""
 	The basic structure of a class that can be converted into a dictionary.
 	"""
@@ -66,13 +69,20 @@ class Dictable(Iterable):
 	def __init__(self, *args, **kwargs):
 		pass
 
+	def __repr__(self) -> str:
+		return super().__repr__()
+
 	def __str__(self) -> str:
 		return self.__repr__()
 
-	def __iter__(self) -> Iterable[Tuple[str, Any]]:  # type: ignore[override]
+	def __iter__(self) -> Iterator[Tuple[str, _V]]:
+		"""
+		Iterate over the attributes of the class.
+		"""
+
 		yield from self.__dict__.items()
 
-	def __getstate__(self) -> Dict[str, Any]:
+	def __getstate__(self) -> Dict[str, _V]:
 		return self.__dict__
 
 	def __setstate__(self, state):

domdf_python_tools/dates.py

@@ -32,6 +32,8 @@
 
 # stdlib
 import datetime
+import sys
+import typing
 from collections import OrderedDict
 from typing import Optional, Union
 
@@ -110,8 +112,6 @@ def get_timezone(tz: str, date: Optional[datetime.datetime] = None) -> Optional[
 def current_tzinfo() -> Optional[datetime.tzinfo]:
 	"""
 	Returns a tzinfo object for the current timezone.
-
-	:rtype: :class:`python:datetime.tzinfo`
 	"""
 
 	return datetime.datetime.now().astimezone().tzinfo  # pragma: no cover (hard to test)
@@ -126,7 +126,7 @@ def current_tzinfo() -> Optional[datetime.tzinfo]:
 # 	:type datetime: :class:`datetime.datetime`
 # 	:param current_tzinfo: A tzinfo object representing the current timezone.
 # 		If None it will be inferred.
-# 	:type current_tzinfo: :class:`~python:datetime.tzinfo`
+# 	:type current_tzinfo: :class:`datetime.tzinfo`
 #
 # 	:return: Timestamp in UTC timezone
 # 	:rtype: float
@@ -140,12 +140,10 @@ def set_timezone(obj: datetime.datetime, tzinfo: datetime.tzinfo) -> datetime.da
 	"""
 	Sets the timezone / tzinfo of the given :class:`datetime.datetime` object.
 	This will not convert the time (i.e. the hours will stay the same).
-	Use :meth:`python:datetime.datetime.astimezone` to accomplish that.
+	Use :meth:`datetime.datetime.astimezone` to accomplish that.
 
 	:param obj:
 	:param tzinfo:
-
-	:return:
 	"""
 
 	return obj.replace(tzinfo=tzinfo)
@@ -161,7 +159,7 @@ def utc_timestamp_to_datetime(
 	If ``output_tz`` is None the timestamp is converted to the platform’s local date and time,
 	and the local timezone is inferred and set for the object.
 
-	If ``output_tz`` is not None, it must be an instance of a :class:`~python:datetime.tzinfo` subclass,
+	If ``output_tz`` is not None, it must be an instance of a :class:`datetime.tzinfo` subclass,
 	and the timestamp is converted to ``output_tz``’s time zone.
 
 
@@ -171,7 +169,7 @@ def utc_timestamp_to_datetime(
 
 	:return: The timestamp as a datetime object.
 
-	:raises: :class:`~python:OverflowError` if the timestamp is out of the range
+	:raises OverflowError: if the timestamp is out of the range
 		of values supported by the platform C localtime() or gmtime() functions,
 		and OSError on localtime() or gmtime() failure. It’s common for this to
 		be restricted to years in 1970 through 2038.
@@ -181,8 +179,13 @@ def utc_timestamp_to_datetime(
 	return new_datetime.astimezone(output_tz)
 
 
-# Mapping of months to their 3-character shortcodes.
-months = OrderedDict(
+if sys.version_info <= (3, 7):
+	MonthsType = OrderedDict
+else:
+	MonthsType = typing.OrderedDict[str, str]
+
+#: Mapping of 3-character shortcodes to full month names.
+months: MonthsType = OrderedDict(
 		Jan="January",
 		Feb="February",
 		Mar="March",

domdf_python_tools/doctools.py

@@ -34,7 +34,6 @@
 from typing import Any, Callable, Dict, Optional, Sequence, Type, TypeVar, Union
 
 # this package
-from domdf_python_tools.stringlist import StringList
 from domdf_python_tools.typing import MethodDescriptorType, MethodWrapperType, WrapperDescriptorType
 
 __all__ = [
@@ -99,6 +98,9 @@ def append_doctring_from_another(target: Union[Type, Callable], original: Union[
 	:param original: The object to copy the docstring from
 	"""
 
+	# this package
+	from domdf_python_tools.stringlist import StringList
+
 	target_doc = target.__doc__
 	original_doc = original.__doc__
 
@@ -129,7 +131,7 @@ def make_sphinx_links(input_string: str, builtins_list: Optional[Sequence[str]]
 
 	.. code-block:: rest
 
-		:class:`~python:str`
+		:class:`str`
 
 	Make sure to have ``'python': ('https://docs.python.org/3/', None),`` in the
 	``intersphinx_mapping`` dict of your ``conf.py`` file for Sphinx.
@@ -147,7 +149,7 @@ def make_sphinx_links(input_string: str, builtins_list: Optional[Sequence[str]]
 	working_string = f"{input_string}"
 
 	for builtin in {x for x in builtins_list if not x.startswith("__") and x != "None"}:
-		working_string = working_string.replace(f"``{builtin}``", f":class:`~python:{builtin}`")
+		working_string = working_string.replace(f"``{builtin}``", f":class:`{builtin}`")
 
 	return working_string
 
@@ -185,7 +187,7 @@ def wrapper(target: F) -> F:
 	return wrapper
 
 
-def sphinxify_docstring() -> Callable:
+def sphinxify_docstring() -> Callable[[F], F]:
 	r"""
 	Decorator to make proper sphinx links out of double-backticked strings in the docstring.
 
@@ -199,7 +201,7 @@ def sphinxify_docstring() -> Callable:
 
 	.. code-block:: rest
 
-		:class:`~python:str`
+		:class:`str`
 
 	Make sure to have ``'python': ('https://docs.python.org/3/', None),`` in the
 	``intersphinx_mapping`` dict of your ``conf.py`` file for Sphinx.
@@ -345,11 +347,11 @@ def _do_prettify(obj: Type, base: Type, new_docstrings: Dict[str, str]):
 
 def prettify_docstrings(obj: Type) -> Type:
 	"""
-	Prettify the default :class:`object` docstrings for use in Sphinx documentation.
+	Decorator to prettify the default :class:`object` docstrings for use in Sphinx documentation.
 
 	:param obj: The object to prettify the method docstrings for.
 
-	:return: The object
+	:rtype:
 
 	.. versionadded:: 0.8.0
 	"""