Add type annotations and isort configuration

Author: domdfcoding

.isort.cfg

@@ -0,0 +1,13 @@
+[settings]
+line_length=115
+force_to_top=True
+indent=Tab
+multi_line_output=3
+import_heading_stdlib=stdlib
+import_heading_thirdparty=3rd party
+import_heading_firstparty=this package
+balanced_wrapping=False
+lines_between_types=0
+use_parentheses=True
+default_section=FIRSTPARTY
+no_lines_before=LOCALFOLDER

doc-source/conf.py

@@ -43,7 +43,7 @@
 		"notfound.extension",
 		"sphinx_tabs.tabs",
 		"sphinx-prompt",
-		'sphinx_autodoc_typehints',
+		"sphinx_autodoc_typehints",
 		]
 
 sphinxemoji_style = 'twemoji'

doc-source/requirements.txt

@@ -5,6 +5,7 @@ sphinx-autodoc-typehints >=1.10.3
 sphinx-notfound-page
 sphinx-prompt >=1.2.0
 sphinx-tabs >=1.1.13
+sphinx_autodoc_typehints >=1.10.3
 sphinx_rtd_theme
 sphinxcontrib-httpdomain >=1.7.0
 sphinxemoji >=0.1.6

domdf_python_tools/bases.py

@@ -30,7 +30,7 @@
 from pprint import pformat
 
 # 3rd party
-import pydash
+import pydash  # type: ignore
 
 
 class Dictable(ABC):

domdf_python_tools/dates.py

@@ -34,23 +34,24 @@
 # stdlib
 import datetime
 from collections import OrderedDict
-from typing import Union
+from typing import Optional, Union
 
 # 3rd party
 try:
 	import pytz
 
-	def get_utc_offset(tz, date: datetime.datetime = None) -> datetime.timedelta:
+	def get_utc_offset(tz, date: 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:
+		:param date: The date to obtain the UTC offset for
 		:type date: python:datetime.datetime, optional
+
 		:return:
-		:rtype: datetime.timedelta
+		:rtype: datetime.timedelta or None
 		"""
 
 		if date is None:
@@ -61,17 +62,18 @@ def get_utc_offset(tz, date: datetime.datetime = None) -> datetime.timedelta:
 
 		return date.replace(tzinfo=pytz.utc).astimezone(tz).utcoffset()
 
-	def get_timezone(tz: str, date: datetime.datetime = None) -> datetime.timedelta:
+	def get_timezone(tz: str, date: 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.
 
 		:param tz: A string representing a pytz timezone
 		:type tz: str
-		:param date:
-		:type date: python:datetime.datetime, optional
+		:param date: The date to obtain the timezone for
+		:type date: datetime.datetime, optional
+
 		:return:
-		:rtype: datetime.timedelta
+		:rtype: datetime.tzinfo or None
 		"""
 
 		if date is None:
@@ -187,7 +189,7 @@ def parse_month(month: Union[str, int]) -> str:
 			month = int(month)
 		except ValueError:
 			try:
-				return months[month.capitalize()[:3]]
+				return months[month.capitalize()[:3]]  # type: ignore
 			except KeyError:
 				raise ValueError("Unrecognised month value")
 

domdf_python_tools/doctools.py

@@ -29,7 +29,10 @@
 
 # stdlib
 import builtins
-from typing import Callable, Type, Union
+from textwrap import dedent
+from typing import Any, Callable, Type, TypeVar, Union
+
+F = TypeVar('F', bound=Callable[..., Any])
 
 
 def deindent_string(string: str) -> str:
@@ -76,10 +79,17 @@ def append_doctring_from_another(target: Union[Type, Callable], original: Union[
 	:param original: The object to copy the docstring from
 	"""
 
-	deindented_target_doc = deindent_string(target.__doc__)
-	deindented_original_doc = deindent_string(original.__doc__)
+	target_doc = target.__doc__
+	original_doc = original.__doc__
+
+	if isinstance(original_doc, str) and isinstance(target_doc, str):
+		deindented_target_doc = dedent(target_doc)
+		deindented_original_doc = dedent(original_doc)
+
+		target.__doc__ = deindented_target_doc + "\n" + deindented_original_doc
 
-	target.__doc__ = deindented_target_doc + "\n" + deindented_original_doc
+	elif not isinstance(target_doc, str) and isinstance(original_doc, str):
+		target.__doc__ = dedent(original_doc)
 
 
 def make_sphinx_links(input_string, builtins_list=None):
@@ -113,21 +123,21 @@ def make_sphinx_links(input_string, builtins_list=None):
 
 
 # Decorators that call the above functions
-def is_documented_by(original: Union[Type, Callable]):
+def is_documented_by(original: F) -> Callable:
 	"""
 	Decorator to set the docstring of the ``target`` function to that of the ``original`` function.
 
 	This may be useful for subclasses or wrappers that use the same arguments.
 	"""
 
-	def wrapper(target: Union[Type, Callable]):
+	def wrapper(target: F) -> F:
 		document_object_from_another(target, original)
 		return target
 
 	return wrapper
 
 
-def append_docstring_from(original: Union[Type, Callable]):
+def append_docstring_from(original: F) -> Callable:
 	"""
 	Decorator to appends the docstring from the ``original`` function to the ``target`` function.
 
@@ -138,14 +148,14 @@ def append_docstring_from(original: Union[Type, Callable]):
 	Bear this in mind if additional indentation is used in the docstring.
 	"""
 
-	def wrapper(target: Union[Type, Callable]):
+	def wrapper(target: F) -> F:
 		append_doctring_from_another(target, original)
 		return target
 
 	return wrapper
 
 
-def sphinxify_docstring():
+def sphinxify_docstring() -> Callable:
 	r"""
 	Decorator to make proper sphinx links out of double-backticked strings in the docstring.
 
@@ -155,7 +165,7 @@ def sphinxify_docstring():
 	`intersphinx_mapping` dict of your conf.py for sphinx.
 	"""
 
-	def wrapper(target: Union[Type, Callable]):
+	def wrapper(target: F) -> F:
 		target.__doc__ = make_sphinx_links(target.__doc__)
 		return target
 

domdf_python_tools/enums.py

@@ -24,7 +24,7 @@
 #  MA 02110-1301, USA.
 #
 
-from aenum import Enum, IntEnum
+from aenum import Enum, IntEnum  # type: ignore
 
 __all__ = ["IntEnum", "StrEnum"]
 

domdf_python_tools/pagesizes/_types.py

@@ -0,0 +1,5 @@
+# stdlib
+from decimal import Decimal
+from typing import Union
+
+AnyNumber = Union[float, int, Decimal]

domdf_python_tools/pagesizes/classes.py

@@ -33,7 +33,9 @@
 
 from collections import namedtuple
 from collections.abc import Sequence
+from typing import List, Tuple
 
+from ._types import AnyNumber
 from .units import (
 		cicero,
 		cm,
@@ -66,20 +68,17 @@
 
 
 class BaseSize(namedtuple("__BaseSize", "width, height")):
-	__slots__ = []
+	__slots__: List[str] = []
+	_unit: float = pt
 
-	def __new__(cls, width, height):
-		return super().__new__(
-				cls,
-				_rounders(width, "0.000000"),
-				_rounders(height, "0.000000"),
-				)
+	def __new__(cls, width: AnyNumber, height: AnyNumber):
+		return super().__new__(cls, float(width), float(height))
 
 	def __str__(self):
 		return f"{self.__class__.__name__}(width={_rounders(self.width, '0')}, height={_rounders(self.height, '0')})"
 
 	@classmethod
-	def from_size(cls, size):
+	def from_size(cls, size: Tuple[AnyNumber, AnyNumber]):
 		"""
 
 		:param size:
@@ -91,7 +90,7 @@ def from_size(cls, size):
 
 		return cls(*size)
 
-	def landscape(self):
+	def landscape(self) -> "BaseSize":
 		"""
 		Returns the pagesize in landscape orientation
 
@@ -104,7 +103,7 @@ def landscape(self):
 		else:
 			return self
 
-	def is_landscape(self):
+	def is_landscape(self) -> bool:
 		"""
 		Returns whether the pagesize is in the landscape orientation
 
@@ -114,7 +113,7 @@ def is_landscape(self):
 
 		return self.width >= self.height
 
-	def portrait(self):
+	def portrait(self) -> "BaseSize":
 		"""
 		Returns the pagesize in portrait orientation
 
@@ -127,7 +126,7 @@ def portrait(self):
 		else:
 			return self
 
-	def is_portrait(self):
+	def is_portrait(self) -> bool:
 		"""
 		Returns whether the pagesize is in the portrait orientation
 
@@ -137,7 +136,7 @@ def is_portrait(self):
 
 		return self.width < self.height
 
-	def is_square(self):
+	def is_square(self) -> bool:
 		"""
 		Returns whether the given pagesize is square
 
@@ -147,10 +146,8 @@ def is_square(self):
 
 		return self.width == self.height
 
-	_unit = pt
-
 	@classmethod
-	def from_pt(cls, size):
+	def from_pt(cls, size: "PageSize"):
 		"""
 
 		:param size:
@@ -164,7 +161,7 @@ def from_pt(cls, size):
 
 		return cls(size.width / cls._unit, size.height / cls._unit)
 
-	def to_pt(self):
+	def to_pt(self) -> "PageSize":
 		"""
 
 		:return:
@@ -218,7 +215,7 @@ class Size_scaled_point(BaseSize):
 
 
 class PageSize(BaseSize):
-	__slots__ = []
+	__slots__: List[str] = []
 
 	def __new__(cls, width, height, unit=pt):
 		width, height = convert_from((width, height), unit)

domdf_python_tools/pagesizes/units.py

@@ -31,8 +31,6 @@
 #  MA 02110-1301, USA.
 #
 
-from decimal import Decimal
-
 __all__ = [
 		"pt",
 		"inch",
@@ -54,26 +52,15 @@
 		]
 
 
-class Unit(Decimal):
-
-	def __mul__(self, other):
-		if isinstance(other, float):
-			other = Decimal(str(other))
-
-		return self.__class__(super().__mul__(other))
-
-	__rmul__ = __mul__
-
-
 # Units
 pt = 1
-inch = Unit("72.0")
-cm = inch / Unit("2.54")
-mm = cm * Unit("0.1")
-um = mm * Unit("0.01")
-pc = pica = Unit("12.0")
-dd = didot = Unit("1.07")
+inch = 72.0
+cm = inch / 2.54
+mm = cm * 0.1
+um = mm * 0.01
+pc = pica = 12.0
+dd = didot = 1.07
 cc = cicero = dd * 12
-nd = new_didot = Unit("1.067")
+nd = new_didot = 1.067
 nc = new_cicero = nd * 12
 sp = scaled_point = 1 / 65536