pytest-testrex 0.1.0__py3-none-any.whl

pytest_testrex/__init__.py

@@ -0,0 +1 @@
+"""Hold a test suite to one layout and one standard of test quality."""

pytest_testrex/discovery.py

@@ -0,0 +1,151 @@
+# Imports
+import ast
+import functools
+import os
+
+###########################################################
+# The suites under test
+#
+# The meta suite reads every file under the suites and holds it to one
+# standard. It only parses; nothing here imports a test.
+###########################################################
+
+FUNCTION_DEFS = (ast.FunctionDef, ast.AsyncFunctionDef)
+
+
+def is_ignored(path, ignored_dirs):
+    return any(path == directory or path.startswith(directory + os.sep) for directory in ignored_dirs)
+
+
+# Every test_*.py under the suites, or with test_modules_only off every .py
+def discover_python_files(suite_dirs, test_modules_only, ignored_dirs = ()):
+    found = []
+    for suite_dir in suite_dirs:
+        for root, dirs, files in os.walk(suite_dir):
+            dirs[:] = [name for name in dirs if name != "__pycache__" and not is_ignored(os.path.join(root, name), ignored_dirs)]
+            for name in files:
+                if name.endswith(".py") and (not test_modules_only or name.startswith("test_")):
+                    found.append(os.path.join(root, name))
+    return sorted(found)
+
+
+@functools.lru_cache(maxsize = None)
+def parsed(path):
+    with open(path, "r", encoding = "utf-8") as handle:
+        return ast.parse(handle.read())
+
+
+def is_test_function(node):
+    return isinstance(node, FUNCTION_DEFS) and node.name.startswith("test_")
+
+
+def is_test_class(node):
+    return isinstance(node, ast.ClassDef) and node.name.startswith("Test")
+
+
+# Every test pytest would collect from this module's own definitions: module
+# level, or a method of a Test class
+def collected_tests(tree):
+    found = [node for node in tree.body if is_test_function(node)]
+    for node in tree.body:
+        if is_test_class(node):
+            found.extend(member for member in node.body if is_test_function(member))
+    return found
+
+
+# Whether a module defines tests, including a Test class that only inherits them
+def defines_tests(tree):
+    return any(is_test_function(node) or is_test_class(node) for node in tree.body)
+
+
+def parameter_names(function):
+    arguments = function.args
+    return [argument.arg for argument in arguments.posonlyargs + arguments.args + arguments.kwonlyargs]
+
+
+def is_fixture(function):
+    return any("fixture" in ast.unparse(decorator) for decorator in function.decorator_list)
+
+###########################################################
+# Checks
+#
+# What makes a test fail when its expectation is not met: an assert, a mock's
+# or recorder's assert_*, pytest.fail, a pytest.raises / warns block, or a
+# call to a helper that itself makes checks. Helpers are often imported by
+# name from a *_helpers.py beside the test, so those are followed too.
+###########################################################
+
+def is_raises_block(node):
+    return isinstance(node, ast.With) and any(
+        any(word in ast.unparse(item.context_expr) for word in ("raises", "warns"))
+        for item in node.items)
+
+
+def is_check_call(node, checkers = frozenset()):
+    if not isinstance(node, ast.Call):
+        return False
+    name = ast.unparse(node.func)
+    last = name.rsplit(".", maxsplit = 1)[-1]
+    return last.startswith("assert") or name.endswith("pytest.fail") or last in checkers
+
+
+# Checks reachable in statements without entering a node of a type in stop_at.
+# A try/finally with no handler runs its body straight through, so it is not a branch.
+def checks_in(statements, stop_at = (), checkers = frozenset()):
+    found = []
+
+    def visit(node):
+        if isinstance(node, stop_at) and not (isinstance(node, ast.Try) and not node.handlers):
+            return
+        if isinstance(node, ast.Assert) or is_check_call(node, checkers) or is_raises_block(node):
+            found.append(node)
+        for child in ast.iter_child_nodes(node):
+            visit(child)
+    for statement in statements:
+        visit(statement)
+    return found
+
+
+# Where a module imported by name from path lives: beside it, in a directory
+# above it within tests_dir, or at the top of tests_dir
+def find_helper_module(path, module_name, tests_dir):
+    directory = os.path.dirname(path)
+    while True:
+        candidate = os.path.join(directory, module_name.replace(".", os.sep) + ".py")
+        if os.path.isfile(candidate):
+            return candidate
+        if directory == tests_dir or not directory.startswith(tests_dir):
+            return None
+        directory = os.path.dirname(directory)
+
+
+# Names of the functions defined in tree that make checks, directly or through
+# another such function, given the checker names it can already see
+def local_checkers(tree, known = frozenset()):
+    functions = [node for node in ast.walk(tree) if isinstance(node, FUNCTION_DEFS) and not node.name.startswith("test_")]
+    checkers = set()
+    while True:
+        visible = frozenset(known | checkers)
+        found = {function.name for function in functions if checks_in(function.body, (), visible)}
+        if found <= checkers:
+            return frozenset(checkers)
+        checkers |= found
+
+
+# Every name a call in path can use to reach a checking helper
+@functools.lru_cache(maxsize = None)
+def checker_names(path, tests_dir, seen = frozenset()):
+    tree = parsed(path)
+    imported = set()
+    for node in tree.body:
+        if isinstance(node, ast.ImportFrom) and node.module and not node.level:
+            helper = find_helper_module(path, node.module, tests_dir)
+            if helper and helper not in seen:
+                theirs = checker_names(helper, tests_dir, seen | {path})
+                imported.update(alias.asname or alias.name for alias in node.names if alias.name in theirs)
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                helper = find_helper_module(path, alias.name, tests_dir)
+                if helper and helper not in seen:
+                    imported.update(checker_names(helper, tests_dir, seen | {path}))
+    return local_checkers(tree, frozenset(imported)) | frozenset(imported)

pytest_testrex/hookspecs.py

@@ -0,0 +1,15 @@
+# Third-party imports
+import pytest
+
+# Hooks a repository's conftest.py can implement
+
+
+@pytest.hookspec
+def pytest_testrex_requirement_checkers(config):
+    """Return {marker name: check} for requirement markers beyond requires_binary.
+
+    Each check takes the names a test's markers list and returns a label for
+    each one that is unavailable, such as "XorrISO (JoyBox tool)". A test with
+    any unavailable name is skipped while collecting, before its fixtures run.
+    Every marker in [tool.testrex] requirement_markers needs a check.
+    """

pytest_testrex/hygiene.py

@@ -0,0 +1,59 @@
+# Imports
+import ast
+import collections
+
+# Local imports
+from pytest_testrex.discovery import FUNCTION_DEFS, is_test_function
+
+###########################################################
+# File hygiene
+#
+# A test defined twice in one file silently replaces the first, which then
+# never runs again and reports nothing when it would have failed. Large files
+# are where this happens, so they are also kept to a size where it stays
+# visible.
+###########################################################
+
+def duplicated(names):
+    return sorted(name for name, count in collections.Counter(names).items() if count > 1)
+
+
+def duplicate_tests(tree):
+    return duplicated(node.name for node in tree.body if is_test_function(node))
+
+
+# {class: names} for test methods defined twice within one class
+def duplicate_test_methods(tree):
+    return {
+        node.name: names for node in tree.body if isinstance(node, ast.ClassDef)
+        for names in [duplicated(member.name for member in node.body if is_test_function(member))]
+        if names}
+
+
+def duplicate_definitions(tree):
+    return duplicated(node.name for node in tree.body if isinstance(node, FUNCTION_DEFS + (ast.ClassDef,)))
+
+
+def duplicate_constants(tree):
+    return duplicated(
+        target.id for node in tree.body if isinstance(node, ast.Assign)
+        for target in node.targets if isinstance(target, ast.Name) and target.id.isupper())
+
+
+# Lines of imports that come after the first real statement
+def late_imports(tree):
+    first_statement = None
+    late = []
+    for node in tree.body:
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            if first_statement is not None:
+                late.append(node.lineno)
+        elif not (isinstance(node, ast.Expr) and isinstance(node.value, ast.Constant)):
+            if first_statement is None:
+                first_statement = node.lineno
+    return late
+
+
+def line_count(path):
+    with open(path, "r", encoding = "utf-8") as handle:
+        return sum(1 for _ in handle)

pytest_testrex/layout.py

@@ -0,0 +1,94 @@
+# Imports
+import os
+
+# Local imports
+from pytest_testrex.discovery import defines_tests, is_ignored, parsed
+
+###########################################################
+# Layout
+#
+# Each suite mirrors the repository: a test lives at the path of the code it
+# covers. A test module that outgrows the size limit becomes a directory of
+# the same name, test_<module>/, holding test_<area>.py files, a conftest.py
+# and a <module>_helpers.py they share. The hazards are quiet: a file that
+# holds tests but is not named test_*.py is never collected, and a directory
+# that mirrors nothing puts tests where nobody looks for them.
+###########################################################
+
+# Files in a split package that are not test modules by design
+SUPPORT_FILES = {"conftest.py"}
+
+
+def walk_directories(suite_dirs, ignored_dirs = ()):
+    for suite_dir in suite_dirs:
+        for root, dirs, _ in os.walk(suite_dir):
+            dirs[:] = sorted(
+                name for name in dirs if name != "__pycache__" and not name.startswith(".")
+                and not is_ignored(os.path.join(root, name), ignored_dirs))
+            yield root, dirs
+
+
+# Every test_<module> directory under the suites
+def discover_split_packages(suite_dirs, ignored_dirs = ()):
+    return sorted(os.path.join(root, name) for root, dirs in walk_directories(suite_dirs, ignored_dirs)
+                  for name in dirs if name.startswith("test_"))
+
+
+def holds_python(directory):
+    return any(name.endswith(".py") for _, _, files in os.walk(directory) for name in files)
+
+
+# Every directory that must mirror the repository: neither a split package nor
+# inside one, and holding Python (a directory of fixture data mirrors nothing)
+def discover_mirror_directories(suite_dirs, ignored_dirs = ()):
+    found = []
+    for root, dirs in walk_directories(suite_dirs, ignored_dirs):
+        dirs[:] = [name for name in dirs if not name.startswith("test_")]
+        found.extend(os.path.join(root, name) for name in dirs if holds_python(os.path.join(root, name)))
+    return sorted(found)
+
+
+def suite_of(path, suite_dirs):
+    return next(suite for suite in suite_dirs if path.startswith(suite + os.sep))
+
+
+def python_files(directory):
+    return sorted(name for name in os.listdir(directory)
+                  if name.endswith(".py") and os.path.isfile(os.path.join(directory, name)))
+
+
+def is_test_module_name(name):
+    return name.startswith("test_") and name.endswith(".py")
+
+
+# Files that define tests but are not named test_*.py, so pytest skips them
+def uncollected_test_files(directory):
+    return [name for name in python_files(directory)
+            if name not in SUPPORT_FILES and not is_test_module_name(name)
+            and defines_tests(parsed(os.path.join(directory, name)))]
+
+
+# Where the code a split package covers would live: <repo>/<path>/<name> with
+# one of the source extensions, or a package directory
+def source_candidates(package, suite_dir, repo_root, extensions):
+    relative_parts = os.path.relpath(package, suite_dir).split(os.sep)
+    base = os.path.join(repo_root, *relative_parts[:-1], relative_parts[-1][len("test_"):])
+    return [base + extension for extension in extensions] + [base]
+
+
+# The repository directories a test directory may mirror; a hidden one, such
+# as .githooks, is mirrored without its dot
+def mirror_targets(directory, suite_dir, repo_root):
+    relative_path = os.path.relpath(directory, suite_dir)
+    return [os.path.join(repo_root, relative_path), os.path.join(repo_root, "." + relative_path)]
+
+
+def single_file_twin(package):
+    twin = package + ".py"
+    return twin if os.path.exists(twin) else None
+
+
+# Whether directory sits at or under one of the meta directories, relative to tests_dir
+def is_meta(directory, tests_dir, meta_dirs):
+    relative_path = os.path.relpath(directory, tests_dir)
+    return any(relative_path == meta or relative_path.startswith(meta + os.sep) for meta in meta_dirs)

pytest_testrex/lint.py

@@ -0,0 +1,41 @@
+# Imports
+import os
+import subprocess
+import sys
+
+###########################################################
+# Pylint
+#
+# Pylint runs over every test file with the rcfile, and any message fails.
+# The shipped rcfile only turns off rules that are pytest idioms rather than
+# defects; everything else, such as unused variables, undefined names, calls
+# that do not match a signature and files opened without an encoding, is
+# enforced. Library code gets only the few rules its own linter lacks.
+###########################################################
+
+# Tests import the helpers beside them by name, through each conftest's
+# sys.path entry, which pylint has to be told about
+def import_roots(tests_dir, all_files):
+    roots = {tests_dir}
+    roots.update(os.path.dirname(path) for path in all_files if os.path.basename(path) == "conftest.py")
+    return sorted(roots)
+
+
+# Every file in the suites, and the .py files at the top of tests_dir that
+# they share. Files, not directories: given a directory, pylint names its
+# modules after it, and a test directory mirroring a package, such as
+# Tests/unit/mypackage, would then shadow the package itself.
+def pylint_targets(tests_dir, suite_files):
+    return list(suite_files) + [
+        os.path.join(tests_dir, name) for name in sorted(os.listdir(tests_dir)) if name.endswith(".py")]
+
+
+def run_pylint(rcfile, cwd, roots, *arguments):
+    env = dict(os.environ, PYTHONPATH = os.pathsep.join(roots))
+    return subprocess.run(
+        [sys.executable, "-m", "pylint", "--rcfile=" + rcfile, "--score=no", *arguments],
+        cwd = cwd, env = env, capture_output = True, text = True, check = False)
+
+
+def only_rules(rules):
+    return ["--disable=all", "--enable=" + ",".join(rules)]

pytest_testrex/plugin.py

@@ -0,0 +1,135 @@
+# Imports
+import shutil
+import socket
+
+# Third-party imports
+import pytest
+
+# Local imports
+from pytest_testrex import hookspecs, seal, settings as settings_module, suite
+
+###########################################################
+# The plugin
+#
+# Loaded by pytest from the pytest11 entry point. It does nothing until the
+# repository has a [tool.testrex] table; then it registers the markers, seals
+# the programs tests may not start, closes outbound network, skips tests whose
+# required programs are missing, and parametrizes the meta suite.
+###########################################################
+
+SETTINGS_KEY = pytest.StashKey()
+SURVEY_KEY = pytest.StashKey()
+SEALED_KEY = pytest.StashKey()
+
+
+def pytest_addhooks(pluginmanager):
+    pluginmanager.add_hookspecs(hookspecs)
+
+
+def get_settings(config):
+    return config.stash.get(SETTINGS_KEY, None)
+
+
+def pytest_configure(config):
+    try:
+        loaded = settings_module.load(str(config.rootpath))
+    except settings_module.SettingsError as error:
+        raise pytest.UsageError(str(error)) from error
+    config.stash[SETTINGS_KEY] = loaded
+    if loaded is None:
+        return
+    config.addinivalue_line(
+        "markers", 'requires_binary(*names): skips, before its fixtures run, unless every named program is on PATH ("a|b" takes either)')
+    for marker in loaded.requirement_markers[1:]:
+        config.addinivalue_line("markers", "%s(*names): skips, before its fixtures run, unless every name is available" % marker)
+    config.addinivalue_line("markers", "allow_network: may open outbound connections")
+    # A pytest run inside a test, such as pytester's, finds the seal in place
+    # and must leave it for the session that applied it to remove
+    config.stash[SEALED_KEY] = bool(loaded.sealed_programs) and seal.seal(loaded.sealed_programs)
+
+
+def pytest_unconfigure(config):
+    if config.stash.get(SEALED_KEY, False):
+        seal.unseal()
+
+###########################################################
+# Required programs
+###########################################################
+
+def missing_binaries(names):
+    return [name for name in names if not any(shutil.which(option) for option in name.split("|"))]
+
+
+def requirement_checkers(config):
+    checkers = {"requires_binary": missing_binaries}
+    for result in config.hook.pytest_testrex_requirement_checkers(config = config):
+        checkers.update(result)
+    return checkers
+
+
+def pytest_collection_modifyitems(config, items):
+    loaded = get_settings(config)
+    if loaded is None:
+        return
+    checkers = requirement_checkers(config)
+    unchecked = [marker for marker in loaded.requirement_markers if marker not in checkers]
+    if unchecked:
+        raise pytest.UsageError(
+            "requirement markers with no pytest_testrex_requirement_checkers hook to enforce them: %s" % unchecked)
+    for item in items:
+        missing = []
+        for marker in loaded.requirement_markers:
+            names = [name for mark in item.iter_markers(marker) for name in mark.args]
+            if names:
+                missing.extend(checkers[marker](names))
+        if missing:
+            item.add_marker(pytest.mark.skip(reason = "%s not installed" % ", ".join(missing)))
+
+###########################################################
+# Network
+#
+# A test that quietly reaches the internet passes on a connected machine and
+# fails in CI, and its result depends on a third party. Subprocess based tests
+# are unaffected; this only closes the in-process path.
+###########################################################
+
+def refuse_connection(*args, **kwargs):
+    raise RuntimeError(
+        "outbound network access is not available to tests; "
+        "mark the test with @pytest.mark.allow_network if it truly needs it")
+
+
+@pytest.fixture(autouse = True)
+def no_outbound_network(request):
+    loaded = get_settings(request.config)
+    if loaded is None or not loaded.block_network or request.node.get_closest_marker("allow_network"):
+        return
+    monkeypatch = request.getfixturevalue("monkeypatch")
+    monkeypatch.setattr(socket.socket, "connect", refuse_connection)
+    monkeypatch.setattr(socket.socket, "connect_ex", refuse_connection)
+    monkeypatch.setattr(socket, "create_connection", refuse_connection)
+
+###########################################################
+# The meta suite
+###########################################################
+
+def get_survey(config):
+    if SURVEY_KEY not in config.stash:
+        loaded = get_settings(config)
+        if loaded is None:
+            raise pytest.UsageError("the TestRex suite needs a [tool.testrex] table in pyproject.toml")
+        config.stash[SURVEY_KEY] = suite.survey(loaded)
+    return config.stash[SURVEY_KEY]
+
+
+def pytest_generate_tests(metafunc):
+    if metafunc.cls is None or not issubclass(metafunc.cls, suite.TestRex):
+        return
+    for argument, (values, ids) in get_survey(metafunc.config).parameters().items():
+        if argument in metafunc.fixturenames:
+            metafunc.parametrize(argument, values, ids = ids)
+
+
+@pytest.fixture(scope = "session")
+def testrex_survey(request):
+    return get_survey(request.config)

pytest_testrex/pylintrc

@@ -0,0 +1,45 @@
+# Pylint for the tests; the meta suite runs it and fails on any message.
+#
+# Tests get pylint's deeper checks (fakes whose calls no longer match the real
+# signature, names a fixture never sets, unused results), minus the rules
+# that are pytest idioms rather than defects: a fixture is requested by naming
+# it as a parameter (redefined-outer-name, unused-argument), tests are
+# described by their names (docstrings, invalid-name), and a test reaches into
+# the code under test on purpose (protected-access). Line length is left to
+# the repository's formatter. A repository with its own
+# conventions points [tool.testrex] pylint_rcfile at a copy of this file.
+
+[MAIN]
+jobs = 0
+
+[TYPECHECK]
+# Attributes of the MagicMocks tests swap in, which pylint may infer as the real object
+generated-members = assert_.*,return_value,side_effect,call_args,call_args_list,call_count,called,mock_calls,method_calls,reset_mock
+
+[MESSAGES CONTROL]
+disable =
+    too-many-arguments,
+    too-many-positional-arguments,
+    too-many-instance-attributes,
+    too-many-locals,
+    too-many-branches,
+    too-many-statements,
+    too-many-return-statements,
+    too-many-nested-blocks,
+    too-many-public-methods,
+    too-many-lines,
+    too-few-public-methods,
+    duplicate-code,
+    import-outside-toplevel,
+    broad-exception-caught,
+    broad-exception-raised,
+    missing-module-docstring,
+    missing-class-docstring,
+    missing-function-docstring,
+    redefined-outer-name,
+    unused-argument,
+    protected-access,
+    invalid-name,
+    attribute-defined-outside-init,
+    use-implicit-booleaness-not-comparison,
+    line-too-long,

pytest_testrex/quality.py

@@ -0,0 +1,136 @@
+# Imports
+import ast
+import collections
+import hashlib
+
+# Local imports
+from pytest_testrex.discovery import FUNCTION_DEFS, checks_in, collected_tests
+
+###########################################################
+# Test quality
+#
+# A test that cannot fail reads as coverage and protects nothing. These catch
+# the shapes that let a test pass whatever the code does: asserting nothing,
+# asserting only inside a branch that may not run, swallowing the exception it
+# exists to see, an assertion true by construction, checking only that a value
+# exists or has a type, and a helper pasted into several files that then drift
+# apart. There are no exemption lists: a test that trips one is fixed.
+###########################################################
+
+CONDITIONAL = (ast.If, ast.For, ast.AsyncFor, ast.While, ast.Try)
+
+
+def has_any_check(function, checkers = frozenset()):
+    return bool(checks_in(function.body, (), checkers))
+
+
+# A check that runs whenever the test does: not inside a branch, loop or try
+def has_unconditional_check(function, checkers = frozenset()):
+    return bool(checks_in(function.body, CONDITIONAL, checkers))
+
+
+def label(function):
+    return "%s (line %d)" % (function.name, function.lineno)
+
+
+# Tests that make no check at all
+def unchecked_tests(tree, checkers = frozenset()):
+    return [label(function) for function in collected_tests(tree) if not has_any_check(function, checkers)]
+
+
+# Tests whose every check sits in a branch, loop or try
+def conditional_tests(tree, checkers = frozenset()):
+    return [
+        label(function) for function in collected_tests(tree)
+        if has_any_check(function, checkers) and not has_unconditional_check(function, checkers)]
+
+
+# Lines of except handlers whose whole body is pass (or a bare string)
+def swallowed_handlers(tree):
+    lines = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Try):
+            for handler in node.handlers:
+                body = [statement for statement in handler.body
+                        if not (isinstance(statement, ast.Expr) and isinstance(statement.value, ast.Constant))]
+                if all(isinstance(statement, ast.Pass) for statement in body):
+                    lines.append(handler.lineno)
+    return sorted(lines)
+
+
+# Why an assertion cannot fail, or None
+def tautology(assertion):
+    test = assertion.test
+    if isinstance(test, ast.Constant) and test.value:
+        return "a constant that is always true"
+    if isinstance(test, ast.Compare) and len(test.ops) == 1 and isinstance(test.ops[0], (ast.Eq, ast.Is)):
+        left, right = test.left, test.comparators[0]
+        if ast.unparse(left) == ast.unparse(right):
+            return "compares a value with itself"
+        if isinstance(right, ast.BoolOp) and isinstance(right.op, ast.Or) and ast.unparse(right.values[0]) == ast.unparse(left):
+            return "compares a value with itself or a fallback"
+    if isinstance(test, ast.BoolOp) and isinstance(test.op, ast.Or):
+        if any(isinstance(value, ast.Constant) and value.value for value in test.values):
+            return "has an or branch that is always true"
+    return None
+
+
+# "test line N: why" for each assertion in a test that cannot fail
+def tautologies(tree):
+    return [
+        "%s line %d: %s" % (function.name, node.lineno, tautology(node))
+        for function in collected_tests(tree) for node in ast.walk(function)
+        if isinstance(node, ast.Assert) and tautology(node)]
+
+
+# An assert that only says a value exists or has a type
+def is_weak_assertion(assertion):
+    test = assertion.test
+    if isinstance(test, ast.Call):
+        return ast.unparse(test.func) == "isinstance"
+    return (isinstance(test, ast.Compare) and len(test.ops) == 1 and isinstance(test.ops[0], ast.IsNot)
+            and isinstance(test.comparators[0], ast.Constant) and test.comparators[0].value is None)
+
+
+# Tests whose only checks are weak, so they pass for almost any value
+def weak_only_tests(tree, checkers = frozenset()):
+    weak = []
+    for function in collected_tests(tree):
+        checks = checks_in(function.body, (), checkers)
+        if checks and all(isinstance(check, ast.Assert) and is_weak_assertion(check) for check in checks):
+            weak.append(label(function))
+    return weak
+
+
+# Lines that build a raising callable as (_ for _ in ()).throw(...), which
+# reads as a puzzle; a def that raises says the same thing
+def generator_throws(tree):
+    return sorted(
+        node.lineno for node in ast.walk(tree)
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr == "throw"
+        and isinstance(node.func.value, ast.GeneratorExp))
+
+
+# (name, source) of every module level function that is not a test. The source
+# includes the module constants it reads, so the same function over a
+# different table is not mistaken for a copy.
+def module_helpers(tree):
+    constants = {
+        target.id: ast.unparse(node) for node in tree.body if isinstance(node, ast.Assign)
+        for target in node.targets if isinstance(target, ast.Name)}
+    found = []
+    for node in tree.body:
+        if isinstance(node, FUNCTION_DEFS) and not node.name.startswith("test_") and not node.name.startswith("__"):
+            names = sorted({name.id for name in ast.walk(node) if isinstance(name, ast.Name)})
+            found.append((node.name, ast.unparse(node) + "".join("\n" + constants[name] for name in names if name in constants)))
+    return found
+
+
+# (name, files) for each helper whose identical source is in several files;
+# two different helpers sharing a name are reported apart
+def copied_helpers(sources_by_file):
+    where = collections.defaultdict(set)
+    for path, helpers in sources_by_file.items():
+        for name, source in helpers:
+            where[(name, hashlib.sha256(source.encode()).hexdigest())].add(path)
+    return sorted((name, sorted(files)) for (name, _), files in where.items() if len(files) > 1)