Added additional type annotations

Author: domdfcoding

domdf_python_tools/bases.py

@@ -28,6 +28,7 @@
 from abc import ABC, abstractmethod
 from collections import UserList
 from pprint import pformat
+from typing import Any, Callable, Dict, Iterable, Tuple
 
 # 3rd party
 import pydash  # type: ignore
@@ -42,14 +43,14 @@ class Dictable(ABC):
 	def __init__(self, *args, **kwargs):
 		pass
 
-	def __str__(self):
+	def __str__(self) -> str:
 		return self.__repr__()
 
-	def __iter__(self):
+	def __iter__(self) -> Iterable[Tuple[str, Any]]:
 		for key, value in self.__dict__.items():
 			yield key, value
 
-	def __getstate__(self):
+	def __getstate__(self) -> Dict[str, Any]:
 		return self.__dict__
 
 	def __setstate__(self, state):
@@ -66,14 +67,14 @@ def __deepcopy__(self, memodict={}):
 	def __dict__(self):
 		return dict()
 
-	def __eq__(self, other):
+	def __eq__(self, other) -> bool:
 		if isinstance(other, self.__class__):
 			return pydash.predicates.is_match(other.__dict__, self.__dict__)
 
 		return NotImplemented
 
 
-def namedlist(name="NamedList"):
+def namedlist(name="NamedList") -> Callable:
 	"""
 	A factory function to return a custom list subclass with a name
 
@@ -88,10 +89,10 @@ class NamedList(UserList):
 		A list with a name
 		"""
 
-		def __repr__(self):
+		def __repr__(self) -> str:
 			return f"{super().__repr__()}"
 
-		def __str__(self):
+		def __str__(self) -> str:
 			return f"{self.__class__.__name__}{pformat(list(self))}"
 
 	NamedList.__name__ = name

domdf_python_tools/dates.py

@@ -39,29 +39,34 @@
 try:
 	import pytz
 
-	def get_utc_offset(tz, date: datetime.datetime = None) -> Optional[datetime.timedelta]:
+	def get_utc_offset(
+			tz: Union[datetime.tzinfo, str],
+			date: Optional[datetime.datetime] = None,
+			) -> Optional[datetime.timedelta]:
 		"""
 		Returns the offset between UTC and the requested timezone on the given date.
 		If ``date`` is ``None`` then the current date is used.
 
 		:param tz: ``pytz.timezone`` or a string representing the timezone
 		:type tz:
 		:param date: The date to obtain the UTC offset for
-		:type date: python:datetime.datetime, optional
 
 		:return:
-		:rtype: datetime.timedelta or None
 		"""
 
 		if date is None:
 			date = datetime.datetime.utcnow()
 
+		timezone: Optional[datetime.tzinfo]
+
 		if isinstance(tz, str):
-			tz = get_timezone(tz, date)
+			timezone = get_timezone(tz, date)
+		else:
+			timezone = tz
 
-		return date.replace(tzinfo=pytz.utc).astimezone(tz).utcoffset()
+		return date.replace(tzinfo=pytz.utc).astimezone(timezone).utcoffset()
 
-	def get_timezone(tz: str, date: datetime.datetime = None) -> Optional[datetime.tzinfo]:
+	def get_timezone(tz: str, date: Optional[datetime.datetime] = None) -> Optional[datetime.tzinfo]:
 		"""
 		Returns a localized :class:`pytz.timezone` object for the given date.
 		If ``date`` is ``None`` then the current date is used.
@@ -72,7 +77,6 @@ def get_timezone(tz: str, date: datetime.datetime = None) -> Optional[datetime.t
 		:type date: datetime.datetime, optional
 
 		:return:
-		:rtype: datetime.tzinfo or None
 		"""
 
 		if date is None:
@@ -82,7 +86,7 @@ def get_timezone(tz: str, date: datetime.datetime = None) -> Optional[datetime.t
 
 		return pytz.timezone(tz).localize(d).tzinfo
 
-	def current_tzinfo():
+	def current_tzinfo() -> Optional[datetime.tzinfo]:
 		"""
 		Returns a tzinfo object for the current timezone
 
@@ -109,25 +113,23 @@ def current_tzinfo():
 	# 	return datetime.astimezone(current_tzinfo).timestamp()
 	#
 
-	def set_timezone(obj, tzinfo):
+	def set_timezone(obj: datetime.datetime, tzinfo: datetime.tzinfo) -> datetime.datetime:
 		"""
 		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.
 
 		:param obj:
-		:type obj:
 		:param tzinfo:
-		:type tzinfo:
 
 		:return:
-		:rtype:
 		"""
 
 		return obj.replace(tzinfo=tzinfo)
 
 	def utc_timestamp_to_datetime(
-			utc_timestamp: Union[float, int], output_tz: datetime.tzinfo = None
+			utc_timestamp: Union[float, int],
+			output_tz: Optional[datetime.tzinfo] = None,
 			) -> datetime.datetime:
 		"""
 		Convert UTC timestamp (seconds from UNIX epoch) to a :class:`datetime.datetime` object
@@ -143,7 +145,7 @@ def utc_timestamp_to_datetime(
 		:type utc_timestamp: float, int
 		:param output_tz: The timezone to output the datetime object for.
 			If None it will be inferred.
-		:type output_tz: datetime.tzinfo
+		:type output_tz: datetime.tzinfo, optional
 
 		:return: The timestamp as a datetime object.
 		:rtype: datetime.datetime

domdf_python_tools/doctools.py

@@ -30,7 +30,7 @@
 # stdlib
 import builtins
 from textwrap import dedent
-from typing import Any, Callable, Type, TypeVar, Union
+from typing import Any, Callable, Optional, Sequence, Type, TypeVar, Union
 
 F = TypeVar('F', bound=Callable[..., Any])
 
@@ -92,7 +92,7 @@ def append_doctring_from_another(target: Union[Type, Callable], original: Union[
 		target.__doc__ = dedent(original_doc)
 
 
-def make_sphinx_links(input_string, builtins_list=None):
+def make_sphinx_links(input_string: str, builtins_list: Optional[Sequence[str]] = None) -> str:
 	r"""
 	Make proper sphinx links out of double-backticked strings in docstring.
 
@@ -166,7 +166,11 @@ def sphinxify_docstring() -> Callable:
 	"""
 
 	def wrapper(target: F) -> F:
-		target.__doc__ = make_sphinx_links(target.__doc__)
+		target_doc = target.__doc__
+
+		if target_doc:
+			target.__doc__ = make_sphinx_links(target_doc)
+
 		return target
 
 	return wrapper

domdf_python_tools/enums.py

@@ -49,7 +49,7 @@ class StrEnum(str, Enum):
 	An Enum that can be converted into a string
 	"""
 
-	def __str__(self):
+	def __str__(self) -> str:
 		return self.value
 
 	#

domdf_python_tools/pagesizes/classes.py

@@ -61,9 +61,9 @@ class BaseSize(namedtuple("__BaseSize", "width, height")):
 	Base class namedtuple representing a page size, in point
 
 	:param width: The page width
-	:type width: float
+	:type width: int, float, Decimal or Unit
 	:param height: The page height
-	:type height: float
+	:type height: int, float, Decimal or Unit
 	"""
 
 	__slots__: List[str] = []
@@ -78,7 +78,7 @@ def __new__(cls, width: AnyNumber, height: AnyNumber):
 				cls._unit(height),
 				)
 
-	def __str__(self):
+	def __str__(self) -> str:
 		return f"{self.__class__.__name__}(width={_rounders(self.width, '0')}, height={_rounders(self.height, '0')})"
 
 	@classmethod
@@ -162,9 +162,9 @@ class Size_mm(BaseSize):
 	representing a pagesize in millimeters.
 
 	:param width: The page width
-	:type width: float
+	:type width: int, float, Decimal or Unit
 	:param height: The page height
-	:type height: float
+	:type height: int, float, Decimal or Unit
 	"""
 
 	_unit = mm
@@ -176,9 +176,9 @@ class Size_inch(BaseSize):
 	representing a pagesize in inches.
 
 	:param width: The page width
-	:type width: float
+	:type width: int, float, Decimal or Unit
 	:param height: The page height
-	:type height: float
+	:type height: int, float, Decimal or Unit
 	"""
 
 	_unit = inch
@@ -190,9 +190,9 @@ class Size_cm(BaseSize):
 	representing a pagesize in centimeters.
 
 	:param width: The page width
-	:type width: float
+	:type width: int, float, Decimal or Unit
 	:param height: The page height
-	:type height: float
+	:type height: int, float, Decimal or Unit
 	"""
 
 	_unit = cm
@@ -204,9 +204,9 @@ class Size_um(BaseSize):
 	representing a pagesize in micrometers.
 
 	:param width: The page width
-	:type width: float
+	:type width: int, float, Decimal or Unit
 	:param height: The page height
-	:type height: float
+	:type height: int, float, Decimal or Unit
 	"""
 
 	_unit = um
@@ -218,9 +218,9 @@ class Size_pica(BaseSize):
 	representing a pagesize in pica.
 
 	:param width: The page width
-	:type width: float
+	:type width: int, float, Decimal or Unit
 	:param height: The page height
-	:type height: float
+	:type height: int, float, Decimal or Unit
 	"""
 
 	_unit = pica
@@ -232,9 +232,9 @@ class Size_didot(BaseSize):
 	representing a pagesize in didots / French Points.
 
 	:param width: The page width
-	:type width: float
+	:type width: int, float, Decimal or Unit
 	:param height: The page height
-	:type height: float
+	:type height: int, float, Decimal or Unit
 	"""
 
 	_unit = didot
@@ -246,9 +246,9 @@ class Size_cicero(BaseSize):
 	representing a pagesize in ciceros.
 
 	:param width: The page width
-	:type width: float
+	:type width: int, float, Decimal or Unit
 	:param height: The page height
-	:type height: float
+	:type height: int, float, Decimal or Unit
 	"""
 
 	_unit = cicero
@@ -260,9 +260,9 @@ class Size_new_didot(BaseSize):
 	representing a pagesize in new didots.
 
 	:param width: The page width
-	:type width: float
+	:type width: int, float, Decimal or Unit
 	:param height: The page height
-	:type height: float
+	:type height: int, float, Decimal or Unit
 	"""
 
 	_unit = new_didot
@@ -274,9 +274,9 @@ class Size_new_cicero(BaseSize):
 	representing a pagesize in ciceros.
 
 	:param width: The page width
-	:type width: float
+	:type width: int, float, Decimal or Unit
 	:param height: The page height
-	:type height: float
+	:type height: int, float, Decimal or Unit
 	"""
 
 	_unit = new_cicero
@@ -288,9 +288,9 @@ class Size_scaled_point(BaseSize):
 	representing a pagesize in scaled points.
 
 	:param width: The page width
-	:type width: float
+	:type width: int, float, Decimal or Unit
 	:param height: The page height
-	:type height: float
+	:type height: int, float, Decimal or Unit
 	"""
 
 	_unit = scaled_point
@@ -302,9 +302,9 @@ class PageSize(BaseSize):
 	representing a pagesize in point.
 
 	:param width: The page width
-	:type width: float
+	:type width: int, float, Decimal or Unit
 	:param height: The page height
-	:type height: float
+	:type height: int, float, Decimal or Unit
 
 	The pagesize can be converted to other units using the properties below.
 	"""

domdf_python_tools/pagesizes/utils.py

@@ -74,9 +74,12 @@ def _sequence_convert_from(seq: Sequence[AnyNumber], from_: AnyNumber) -> Tuple[
 	return tuple(float(x) * from_ for x in seq)
 
 
+_measurement_re = re.compile(r"(\d*\.?\d+) *([A-Za-z]*)")
+
+
 def parse_measurement(measurement):
 	# TODO: docstring
-	match = re.findall(r"(\d*\.?\d+) *([A-Za-z]*)", measurement)[0]
+	match = _measurement_re.findall(measurement)[0]
 	print(match)
 	print(len(match))
 	if len(match) < 2:

domdf_python_tools/paths.py

@@ -48,7 +48,7 @@
 import os
 import pathlib
 import shutil
-from typing import AnyStr, Callable, Union
+from typing import Callable, Optional, Union
 
 
 def append(var: str, filename: Union[str, pathlib.Path, os.PathLike]):
@@ -74,7 +74,7 @@ def copytree(
 		src: Union[str, pathlib.Path, os.PathLike],
 		dst: Union[str, pathlib.Path, os.PathLike],
 		symlinks: bool = False,
-		ignore: Callable = None,
+		ignore: Optional[Callable] = None,
 		):
 	"""
 	Alternative to :func:`shutil.copytree` to work in some situations where it doesn't.
@@ -203,7 +203,7 @@ def read(filename: Union[str, pathlib.Path, os.PathLike]) -> str:
 
 def relpath(
 		path: Union[str, pathlib.Path, os.PathLike],
-		relative_to: Union[str, pathlib.Path, os.PathLike] = None
+		relative_to: Optional[Union[str, pathlib.Path, os.PathLike]] = None
 		) -> pathlib.Path:
 	"""
 	Returns the path for the given file or directory relative to the given