Adding docstrings and tidying up

Author: domdfcoding

coverage_pyver_pragma/__init__.py

@@ -27,11 +27,16 @@
 # stdlib
 import re
 import sys
-from typing import List, NamedTuple, Pattern
+from typing import TYPE_CHECKING, Any, List, NamedTuple, Pattern, Union
 
 # 3rd party
 import coverage  # type: ignore
 
+if TYPE_CHECKING:
+
+	# stdlib
+	from sys import _version_info as VersionInfo
+
 __author__: str = "Dominic Davis-Foster"
 __copyright__: str = "2020 Dominic Davis-Foster"
 
@@ -44,12 +49,31 @@
 
 
 class Version(NamedTuple):
+	"""
+	:class:`~typing.NamedTuple` with the same elements as :func:`sys.version_info`.
+
+	:type major: int
+	:type minor: int
+	:type micro: int
+
+	"""
+
 	major: int
 	minor: int
 	micro: int
+	releaselevel: str
+	serial: str
+
 
+def make_regexes(version_tuple: Union["Version", "VersionInfo"]) -> List[Pattern]:
+	"""
+	Generate a list of regular expressions to match all valid ignores for the given Python version.
 
-def make_regexes(version_tuple: Version) -> List[Pattern]:
+	:param version_tuple: The Python version.
+	:type version_tuple: :class:`~typing.NamedTuple` with the attributes ``major`` and ``minor``.
+
+	:return: List of regular expressions.
+	"""
 	if version_tuple.major == 3:
 		# Python 3.X
 
@@ -66,17 +90,28 @@ def make_regexes(version_tuple: Version) -> List[Pattern]:
 				re.compile(fr"{regex_main}\s*\(<(py|PY|Py)3({'|'.join(less_than_versions)})\)"),
 				re.compile(fr"{regex_main}\s*\(<=(py|PY|Py)3({'|'.join(less_equal_versions)})\)"),
 				re.compile(fr"{regex_main}\s*\(>(py|PY|Py)3({'|'.join(greater_than_versions)})\)"),
-				re.compile(fr"{regex_main}\s*\((py|PY|Py)3({'|'.join(greater_than_versions)})+\)"),
+				re.compile(fr"{regex_main}\s*\((py|PY|Py)3({'|'.join(greater_than_versions)})\+\)"),
 				re.compile(fr"{regex_main}\s*\(>=(py|PY|Py)3({'|'.join(greater_equal_versions)})\)"),
 				re.compile(fr"{regex_main}\s*\((py|PY|Py)3({'|'.join(exact_versions)})\)"),
 				]
 
 		return excludes
 
+	else:
+		raise ValueError("Unknown Python version.")
+
 
 class PyVerPragmaPlugin(coverage.CoveragePlugin):
+	"""
+	Plugin for Coverage.py to selectively ignore branches depending on the Python version.
+	"""
+
+	def configure(self, config: Any) -> None:
+		"""
+		Configure the plugin.
 
-	def configure(self, config):
+		:param config:
+		"""
 
 		# Coverage.py gives either a Coverage() object, or a CoverageConfig() object.
 		if isinstance(config, coverage.Coverage):
@@ -98,4 +133,16 @@ def configure(self, config):
 
 
 def coverage_init(reg, options):
+	"""
+	Initialise the plugin.
+
+	:param reg:
+	:type reg:
+	:param options:
+	:type options:
+
+	:return:
+	:rtype:
+	"""
+
 	reg.add_configurer(PyVerPragmaPlugin())  # pragma: no cover

tests/test_regex.py

@@ -16,32 +16,32 @@
 def test_not_version_regex():
 	counter = 1
 
-	for comment_string in ["#", "# ", "#  ", "#\t", "# \t", "# \t ", "#\t "]:
+	for comment_string in ['#', "# ", "#  ", "#\t", "# \t", "# \t ", "#\t "]:
 		for pragma_string in ["pragma", "PRAGMA"]:
 			for post_pragma_space in ['', ':', ": ", ":\t", "  "]:
 				for no_string in ["no", "NO"]:
-					for post_no_space in ['', " ", "\t", "  "]:
+					for post_no_space in ['', ' ', "\t", "  "]:
 						for cover_string in ["cover", "COVER"]:
-							for post_cover_space in ['', " ", "\t", "  "]:
-								for pre_version_sign in [">", "<", ">=", "<=", ""]:
+							for post_cover_space in ['', ' ', "\t", "  "]:
+								for pre_version_sign in ['>', '<', ">=", "<=", '']:
 									for py_string in ["Py", "PY", "py"]:
 										for version in [30, 31, 32, 33, 34, 35, 36, 37, 38, 39]:
-											for post_version_sign in ["+", ""]:
+											for post_version_sign in ['+', '']:
 												test_string = f"{comment_string}{pragma_string}{post_pragma_space}{no_string}{post_no_space}{cover_string}{post_cover_space}({pre_version_sign}{py_string}{version}{post_version_sign})"
 												# print(f"[{counter} TESTING: {test_string}]")
 
 												if re.match(not_version_regex, test_string):
 													raise AssertionError(f"[{counter} FAIL: {test_string}]")
 												counter += 1
 
-	for comment_string in ["#", "# ", "#  ", "#\t", "# \t", "# \t ", "#\t "]:
+	for comment_string in ['#', "# ", "#  ", "#\t", "# \t", "# \t ", "#\t "]:
 		for pragma_string in ["pragma", "PRAGMA"]:
 			for post_pragma_space in ['', ':', ": ", ":\t", "  "]:
 				for no_string in ["no", "NO"]:
-					for post_no_space in ['', " ", "\t", "  "]:
+					for post_no_space in ['', ' ', "\t", "  "]:
 						for cover_string in ["cover", "COVER"]:
-							for post_cover_space in ['', " ", "\t", "  "]:
-								for post_cover_text in ["", "abcdefg", "hello world"]:
+							for post_cover_space in ['', ' ', "\t", "  "]:
+								for post_cover_text in ['', "abcdefg", "hello world"]:
 									test_string = f"{comment_string}{pragma_string}{post_pragma_space}{no_string}{post_no_space}{cover_string}{post_cover_space}{post_cover_text}"
 									# print(f"[{counter} TESTING: {test_string}]")
 
@@ -83,21 +83,21 @@ def test_correct_version_regex():
 
 		# TODO: Plus
 		for pre_version_sign, minor_versions in zip(
-			[">", "<", ">=", "<=", ""],
+			['>', '<', ">=", "<=", ''],
 			[range(0, python_version.minor), range(python_version.minor + 1, 10), range(0, python_version.minor + 1), range(python_version.minor, 10), [python_version.minor], [python_version.minor]]
 			):
 			for minor_version in minor_versions:
 				version = 30 + minor_version
 
-				for comment_string in ["#", "# ", "#  ", "#\t", "# \t", "# \t ", "#\t "]:
+				for comment_string in ['#', "# ", "#  ", "#\t", "# \t", "# \t ", "#\t "]:
 					for pragma_string in ["pragma", "PRAGMA"]:
 						for post_pragma_space in ['', ':', ": ", ":\t", "  "]:
 							for no_string in ["no", "NO"]:
-								for post_no_space in ['', " ", "\t", "  "]:
+								for post_no_space in ['', ' ', '\t', "  "]:
 									for cover_string in ["cover", "COVER"]:
-										for post_cover_space in ['', " ", "\t", "  "]:
+										for post_cover_space in ['', ' ', '\t', "  "]:
 											for py_string in ["Py", "PY", "py"]:
-												# for post_version_sign in ["+", ""]:
+												# for post_version_sign in ['+', '']:
 
 												test_string = f"{comment_string}{pragma_string}{post_pragma_space}{no_string}{post_no_space}{cover_string}{post_cover_space}({pre_version_sign}{py_string}{version}{post_version_sign})"  # print(f"[{counter} TESTING: {test_string}]")