Added more type annotations

Author: domdfcoding

doc-source/dates.rst

@@ -2,12 +2,15 @@
 :mod:`domdf_python_tools.dates`
 *********************************
 
+.. extras-require:: dates
+
+	pytz >=2019.1
+
 .. contents:: Table of Contents
 
 
 .. warning:: This module has not been fully tested. Use with caution.
 
-.. note:: This module requires the `pytz <https://pypi.org/project/pytz/>`_ package to be installed.
 
 .. automodule:: domdf_python_tools.dates
 	:members:

domdf_python_tools/dates.py

@@ -34,22 +34,23 @@
 # stdlib
 import datetime
 from collections import OrderedDict
+from typing import Union
 
 # 3rd party
 try:
 	import pytz
 
-	def get_utc_offset(tz, date=None):
+	def get_utc_offset(tz, date: datetime.datetime = None) -> 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: :class:`pytz.timezone` or a string representing the timezone
+		:param tz: ``pytz.timezone`` or a string representing the timezone
 		:type tz:
 		:param date:
-		:type date: :class:`python:datetime.datetime` or None, optional
+		:type date: python:datetime.datetime, optional
 		:return:
-		:rtype: :class:`python:datetime.timedelta`
+		:rtype: datetime.timedelta
 		"""
 
 		if date is None:
@@ -60,17 +61,18 @@ def get_utc_offset(tz, date=None):
 
 		return date.replace(tzinfo=pytz.utc).astimezone(tz).utcoffset()
 
-	def get_timezone(tz, date=None):
+
+	def get_timezone(tz: str, date: datetime.datetime = None) -> datetime.timedelta:
 		"""
 		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:
+		:type tz: str
 		:param date:
-		:type date: :class:`python:datetime.datetime` or None, optional
+		:type date: python:datetime.datetime, optional
 		:return:
-		:rtype: :class:`python:datetime.timedelta`
+		:rtype: datetime.timedelta
 		"""
 
 		if date is None:
@@ -80,6 +82,7 @@ def get_timezone(tz, date=None):
 
 		return pytz.timezone(tz).localize(d).tzinfo
 
+
 	def current_tzinfo():
 		"""
 		Returns a tzinfo object for the current timezone
@@ -124,7 +127,8 @@ def set_timezone(obj, tzinfo):
 
 		return obj.replace(tzinfo=tzinfo)
 
-	def utc_timestamp_to_datetime(utc_timestamp, output_tz=None):
+
+	def utc_timestamp_to_datetime(utc_timestamp: Union[float, int], output_tz: datetime.tzinfo = None) -> datetime.datetime:
 		"""
 		Convert UTC timestamp (seconds from UNIX epoch) to a :class:`datetime.datetime` object
 
@@ -139,10 +143,10 @@ def utc_timestamp_to_datetime(utc_timestamp, output_tz=None):
 		: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: :class:`~python:datetime.tzinfo`
+		:type output_tz: datetime.tzinfo
 
 		:return: The timestamp as a datetime object.
-		:rtype: :class:`datetime.datetime`
+		:rtype: datetime.datetime
 
 		:raises: :class:`~python:OverflowError` if the timestamp is out of the range
 			of values supported by the platform C localtime() or gmtime() functions,
@@ -153,6 +157,7 @@ def utc_timestamp_to_datetime(utc_timestamp, output_tz=None):
 		new_datetime = datetime.datetime.fromtimestamp(utc_timestamp, output_tz)
 		return new_datetime.astimezone(output_tz)
 
+
 	# List of months and their 3-character shortcodes.
 	months = OrderedDict(
 			Jan="January",
@@ -169,7 +174,8 @@ def utc_timestamp_to_datetime(utc_timestamp, output_tz=None):
 			Dec="December",
 			)
 
-	def parse_month(month):
+
+	def parse_month(month: Union[str, int]) -> str:
 		"""
 		Converts an integer or shorthand month into the full month name
 
@@ -194,7 +200,8 @@ def parse_month(month):
 		else:
 			raise ValueError("Unrecognised month value")
 
-	def get_month_number(month):
+
+	def get_month_number(month: Union[str, int]) -> int:
 		"""
 		Returns the number of the given month. If ``month`` is already a
 		number between 1 and 12 it will be returned immediately.
@@ -203,7 +210,7 @@ def get_month_number(month):
 		:type month: str or int
 
 		:return: The number of the month
-		:rtype:
+		:rtype: int
 		"""
 
 		if isinstance(month, int):
@@ -215,7 +222,7 @@ def get_month_number(month):
 			month = parse_month(month)
 			return list(months.values()).index(month) + 1
 
-	def check_date(month, day, leap_year=True):
+	def check_date(month: Union[str, int], day: int, leap_year: bool = True) -> bool:
 		"""
 		Returns ``True`` if the day number is valid for the given month.
 		Note that this will return ``True`` for the 29th Feb. If you don't
@@ -225,8 +232,8 @@ def check_date(month, day, leap_year=True):
 		:type month: str, int
 		:param day: The day number to test
 		:type day: int
-		:param leap_year: Whether to return ``True`` for 29th Feb
-		:type leap_year: bool
+		:param leap_year: Whether to return ``True`` for 29th Feb. Default ``True``
+		:type leap_year: bool, optional
 
 		:return: ``True`` if the date is valid
 		:rtype: bool

domdf_python_tools/doctools.py

@@ -27,10 +27,12 @@
 #  MA 02110-1301, USA.
 #
 
+# stdlib
 import builtins
+from typing import Callable, Type, Union
 
 
-def deindent_string(string):
+def deindent_string(string: str) -> str:
 	"""
 	Removes all indentation from the given string
 
@@ -47,22 +49,20 @@ def deindent_string(string):
 
 
 # Functions that do the work
-def document_object_from_another(target, original):
+def document_object_from_another(target: Union[Type, Callable], original: Union[Type, Callable]):
 	"""
 	Sets 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.
 
 	:param target: The object to set the docstring for
-	:type target: any
 	:param original: The object to copy the docstring from
-	:type original: any
 	"""
 
 	target.__doc__ = original.__doc__
 
 
-def append_doctring_from_another(target, original):
+def append_doctring_from_another(target: Union[Type, Callable], original: Union[Type, Callable]):
 	"""
 	Sets the docstring of the ``target`` function to that of the ``original`` function.
 
@@ -73,9 +73,7 @@ def append_doctring_from_another(target, original):
 	Bear this in mind if additional indentation is used in the docstring.
 
 	:param target: The object to append the docstring to
-	:type target: any
 	:param original: The object to copy the docstring from
-	:type original: any
 	"""
 
 	deindented_target_doc = deindent_string(target.__doc__)
@@ -115,23 +113,23 @@ def make_sphinx_links(input_string, builtins_list=None):
 
 
 # Decorators that call the above functions
-def is_documented_by(original):
+def is_documented_by(original: Union[Type, Callable]):
 	"""
-	Sets the docstring of the ``target`` function to that of the ``original`` function.
+	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):
+	def wrapper(target: Union[Type, Callable]):
 		document_object_from_another(target, original)
 		return target
 
 	return wrapper
 
 
-def append_docstring_from(original):
+def append_docstring_from(original: Union[Type, Callable]):
 	"""
-	Appends the docstring from the ``original`` function to the ``target`` function.
+	Decorator to appends the docstring from the ``original`` function to the ``target`` function.
 
 	This may be useful for subclasses or wrappers that use the same arguments.
 
@@ -140,7 +138,7 @@ def append_docstring_from(original):
 	Bear this in mind if additional indentation is used in the docstring.
 	"""
 
-	def wrapper(target):
+	def wrapper(target: Union[Type, Callable]):
 		append_doctring_from_another(target, original)
 		return target
 
@@ -149,15 +147,15 @@ def wrapper(target):
 
 def sphinxify_docstring():
 	r"""
-	Make proper sphinx links out of double-backticked strings in docstring.
+	Decorator to make proper sphinx links out of double-backticked strings in the docstring.
 
 	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.
 	"""
 
-	def wrapper(target):
+	def wrapper(target: Union[Type, Callable]):
 		target.__doc__ = make_sphinx_links(target.__doc__)
 		return target
 

tests/test_enums.py

@@ -26,6 +26,7 @@ def test_str_enum():
 	assert DramatisPersonae("The sender") == DramatisPersonae.Bob == "The sender"
 	assert repr(DramatisPersonae.Bob) == "<DramatisPersonae.Bob: 'The sender'>"
 
+
 class Numbers(enums.IntEnum):
 	One = 1
 	Two = 2