Add code.

Author: domdfcoding

doc-source/api/flake8-helper.rst

@@ -3,3 +3,4 @@ flake8_helper
 ==============
 
 .. automodule:: flake8_helper
+	:member-order: bysource

doc-source/contributing.rst

@@ -1,6 +1,5 @@
-==============
-Contributing
-==============
+Overview
+---------
 
 .. This file based on https://github.com/PyGithub/PyGithub/blob/master/CONTRIBUTING.md
 

flake8_helper/__init__.py

@@ -26,8 +26,99 @@
 #  OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
+# stdlib
+import ast
+from abc import ABC, abstractmethod
+from typing import Iterator, List, Tuple, Type, TypeVar
+
+__all__ = ["Visitor", "_P", "Plugin"]
+
 __author__: str = "Dominic Davis-Foster"
 __copyright__: str = "2021 Dominic Davis-Foster"
 __license__: str = "MIT License"
 __version__: str = "0.0.0"
 __email__: str = "[email protected]"
+
+_P = TypeVar("_P", bound="Plugin")
+
+
+class Visitor(ast.NodeVisitor):
+	"""
+	AST node visitor.
+	"""
+
+	def __init__(self) -> None:
+		#: The list of Flake8 errors identified by the visitor.
+		self.errors: List[Tuple[int, int, str]] = []
+
+	def report_error(self, node: ast.AST, error: str):
+		"""
+		Report an error for the given node.
+
+		:param node:
+		:param error:
+		"""
+
+		self.errors.append((
+				node.lineno,
+				node.col_offset,
+				error,
+				))
+
+
+class Plugin(ABC):
+	"""
+	Abstract base class for Flake8 plugins.
+
+	:param tree: The abstract syntax tree (AST) to check.
+
+	**Minimum example:**
+
+	.. code=block:: python
+
+		class EncodingsPlugin(Plugin):
+			'''
+			A Flake8 plugin to identify incorrect use of encodings.
+
+			:param tree: The abstract syntax tree (AST) to check.
+			'''
+
+			name: str = __name__
+			version: str = __version__  #: The plugin version
+	"""
+
+	def __init__(self, tree: ast.AST):
+
+		#: The abstract syntax tree (AST) being checked.
+		self._tree = tree
+
+	@property
+	@abstractmethod
+	def name(self) -> str:
+		"""
+		The plugin name.
+		"""
+
+		raise NotImplementedError
+
+	@property
+	@abstractmethod
+	def version(self) -> str:
+		"""
+		The plugin version.
+		"""
+
+		raise NotImplementedError
+
+	def run(self: _P) -> Iterator[Tuple[int, int, str, Type[_P]]]:
+		"""
+		Traverse the Abstract Syntax Tree and identify errors.
+
+		Yields a tuple of (line number, column offset, error message, type(self))
+		"""
+
+		visitor = Visitor()
+		visitor.visit(self._tree)
+
+		for line, col, msg in visitor.errors:
+			yield line, col, msg, type(self)

formate.toml

@@ -31,5 +31,5 @@ lines_between_types = 0
 use_parentheses = true
 remove_redundant_aliases = true
 default_section = "THIRDPARTY"
-known_third_party = []
+known_third_party = [ "flake8",]
 known_first_party = "flake8_helper"

repo_helper.yml

@@ -36,7 +36,6 @@ extra_sphinx_extensions:
  - sphinx_toolbox.flake8
 
 sphinx_html_theme: furo
-standalone_contrib_guide: true
 
 keywords:
  - flake8

requirements.txt

@@ -0,0 +1 @@
+flake8>=3.8.4

tox.ini

@@ -116,3 +116,6 @@ package = flake8_helper
 [pytest]
 addopts = --color yes --durations 25
 timeout = 300
+
+[dep_checker]
+allowed_unused = flake8