Current File : //opt/cloudlinux/venv/lib/python3.11/site-packages/pylint/checkers/imports.py
# Licensed under the GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
# For details: https://github.com/PyCQA/pylint/blob/main/LICENSE
# Copyright (c) https://github.com/PyCQA/pylint/blob/main/CONTRIBUTORS.txt
"""Imports checkers for Python code."""
from __future__ import annotations
import collections
import copy
import os
import sys
from collections import defaultdict
from collections.abc import ItemsView, Sequence
from typing import TYPE_CHECKING, Any, Dict, List, Union
import astroid
from astroid import nodes
from astroid.nodes._base_nodes import ImportNode
from pylint.checkers import BaseChecker, DeprecatedMixin
from pylint.checkers.utils import (
get_import_name,
in_type_checking_block,
is_from_fallback_block,
is_sys_guard,
node_ignores_exception,
)
from pylint.exceptions import EmptyReportError
from pylint.graph import DotBackend, get_cycles
from pylint.interfaces import HIGH
from pylint.reporters.ureports.nodes import Paragraph, Section, VerbatimText
from pylint.typing import MessageDefinitionTuple
from pylint.utils import IsortDriver
from pylint.utils.linterstats import LinterStats
if TYPE_CHECKING:
from pylint.lint import PyLinter
if sys.version_info >= (3, 8):
from functools import cached_property
else:
from astroid.decorators import cachedproperty as cached_property
# The dictionary with Any should actually be a _ImportTree again
# but mypy doesn't support recursive types yet
_ImportTree = Dict[str, Union[List[Dict[str, Any]], List[str]]]
DEPRECATED_MODULES = {
(0, 0, 0): {"tkinter.tix", "fpectl"},
(3, 2, 0): {"optparse"},
(3, 3, 0): {"xml.etree.cElementTree"},
(3, 4, 0): {"imp"},
(3, 5, 0): {"formatter"},
(3, 6, 0): {"asynchat", "asyncore", "smtpd"},
(3, 7, 0): {"macpath"},
(3, 9, 0): {"lib2to3", "parser", "symbol", "binhex"},
(3, 10, 0): {"distutils", "typing.io", "typing.re"},
(3, 11, 0): {
"aifc",
"audioop",
"cgi",
"cgitb",
"chunk",
"crypt",
"imghdr",
"msilib",
"mailcap",
"nis",
"nntplib",
"ossaudiodev",
"pipes",
"sndhdr",
"spwd",
"sunau",
"sre_compile",
"sre_constants",
"sre_parse",
"telnetlib",
"uu",
"xdrlib",
},
}
def _qualified_names(modname: str | None) -> list[str]:
"""Split the names of the given module into subparts.
For example,
_qualified_names('pylint.checkers.ImportsChecker')
returns
['pylint', 'pylint.checkers', 'pylint.checkers.ImportsChecker']
"""
names = modname.split(".") if modname is not None else ""
return [".".join(names[0 : i + 1]) for i in range(len(names))]
def _get_first_import(
node: ImportNode,
context: nodes.LocalsDictNodeNG,
name: str,
base: str | None,
level: int | None,
alias: str | None,
) -> tuple[nodes.Import | nodes.ImportFrom | None, str | None]:
"""Return the node where [base.]<name> is imported or None if not found."""
fullname = f"{base}.{name}" if base else name
first = None
found = False
msg = "reimported"
for first in context.body:
if first is node:
continue
if first.scope() is node.scope() and first.fromlineno > node.fromlineno:
continue
if isinstance(first, nodes.Import):
if any(fullname == iname[0] for iname in first.names):
found = True
break
for imported_name, imported_alias in first.names:
if not imported_alias and imported_name == alias:
found = True
msg = "shadowed-import"
break
if found:
break
elif isinstance(first, nodes.ImportFrom):
if level == first.level:
for imported_name, imported_alias in first.names:
if fullname == f"{first.modname}.{imported_name}":
found = True
break
if (
name != "*"
and name == imported_name
and not (alias or imported_alias)
):
found = True
break
if not imported_alias and imported_name == alias:
found = True
msg = "shadowed-import"
break
if found:
break
if found and not astroid.are_exclusive(first, node):
return first, msg
return None, None
def _ignore_import_failure(
node: ImportNode,
modname: str | None,
ignored_modules: Sequence[str],
) -> bool:
for submodule in _qualified_names(modname):
if submodule in ignored_modules:
return True
# Ignore import failure if part of guarded import block
# I.e. `sys.version_info` or `typing.TYPE_CHECKING`
if in_type_checking_block(node):
return True
if isinstance(node.parent, nodes.If) and is_sys_guard(node.parent):
return True
return node_ignores_exception(node, ImportError)
# utilities to represents import dependencies as tree and dot graph ###########
def _make_tree_defs(mod_files_list: ItemsView[str, set[str]]) -> _ImportTree:
"""Get a list of 2-uple (module, list_of_files_which_import_this_module),
it will return a dictionary to represent this as a tree.
"""
tree_defs: _ImportTree = {}
for mod, files in mod_files_list:
node: list[_ImportTree | list[str]] = [tree_defs, []]
for prefix in mod.split("."):
assert isinstance(node[0], dict)
node = node[0].setdefault(prefix, ({}, [])) # type: ignore[arg-type,assignment]
assert isinstance(node[1], list)
node[1].extend(files)
return tree_defs
def _repr_tree_defs(data: _ImportTree, indent_str: str | None = None) -> str:
"""Return a string which represents imports as a tree."""
lines = []
nodes_items = data.items()
for i, (mod, (sub, files)) in enumerate(sorted(nodes_items, key=lambda x: x[0])):
files_list = "" if not files else f"({','.join(sorted(files))})"
if indent_str is None:
lines.append(f"{mod} {files_list}")
sub_indent_str = " "
else:
lines.append(rf"{indent_str}\-{mod} {files_list}")
if i == len(nodes_items) - 1:
sub_indent_str = f"{indent_str} "
else:
sub_indent_str = f"{indent_str}| "
if sub and isinstance(sub, dict):
lines.append(_repr_tree_defs(sub, sub_indent_str))
return "\n".join(lines)
def _dependencies_graph(filename: str, dep_info: dict[str, set[str]]) -> str:
"""Write dependencies as a dot (graphviz) file."""
done = {}
printer = DotBackend(os.path.splitext(os.path.basename(filename))[0], rankdir="LR")
printer.emit('URL="." node[shape="box"]')
for modname, dependencies in sorted(dep_info.items()):
sorted_dependencies = sorted(dependencies)
done[modname] = 1
printer.emit_node(modname)
for depmodname in sorted_dependencies:
if depmodname not in done:
done[depmodname] = 1
printer.emit_node(depmodname)
for depmodname, dependencies in sorted(dep_info.items()):
for modname in sorted(dependencies):
printer.emit_edge(modname, depmodname)
return printer.generate(filename)
def _make_graph(
filename: str, dep_info: dict[str, set[str]], sect: Section, gtype: str
) -> None:
"""Generate a dependencies graph and add some information about it in the
report's section.
"""
outputfile = _dependencies_graph(filename, dep_info)
sect.append(Paragraph((f"{gtype}imports graph has been written to {outputfile}",)))
# the import checker itself ###################################################
MSGS: dict[str, MessageDefinitionTuple] = {
"E0401": (
"Unable to import %s",
"import-error",
"Used when pylint has been unable to import a module.",
{"old_names": [("F0401", "old-import-error")]},
),
"E0402": (
"Attempted relative import beyond top-level package",
"relative-beyond-top-level",
"Used when a relative import tries to access too many levels "
"in the current package.",
),
"R0401": (
"Cyclic import (%s)",
"cyclic-import",
"Used when a cyclic import between two or more modules is detected.",
),
"R0402": (
"Use 'from %s import %s' instead",
"consider-using-from-import",
"Emitted when a submodule of a package is imported and "
"aliased with the same name, "
"e.g., instead of ``import concurrent.futures as futures`` use "
"``from concurrent import futures``.",
),
"W0401": (
"Wildcard import %s",
"wildcard-import",
"Used when `from module import *` is detected.",
),
"W0404": (
"Reimport %r (imported line %s)",
"reimported",
"Used when a module is imported more than once.",
),
"W0406": (
"Module import itself",
"import-self",
"Used when a module is importing itself.",
),
"W0407": (
"Prefer importing %r instead of %r",
"preferred-module",
"Used when a module imported has a preferred replacement module.",
),
"W0410": (
"__future__ import is not the first non docstring statement",
"misplaced-future",
"Python 2.5 and greater require __future__ import to be the "
"first non docstring statement in the module.",
),
"C0410": (
"Multiple imports on one line (%s)",
"multiple-imports",
"Used when import statement importing multiple modules is detected.",
),
"C0411": (
"%s should be placed before %s",
"wrong-import-order",
"Used when PEP8 import order is not respected (standard imports "
"first, then third-party libraries, then local imports).",
),
"C0412": (
"Imports from package %s are not grouped",
"ungrouped-imports",
"Used when imports are not grouped by packages.",
),
"C0413": (
'Import "%s" should be placed at the top of the module',
"wrong-import-position",
"Used when code and imports are mixed.",
),
"C0414": (
"Import alias does not rename original package",
"useless-import-alias",
"Used when an import alias is same as original package, "
"e.g., using import numpy as numpy instead of import numpy as np.",
),
"C0415": (
"Import outside toplevel (%s)",
"import-outside-toplevel",
"Used when an import statement is used anywhere other than the module "
"toplevel. Move this import to the top of the file.",
),
"W0416": (
"Shadowed %r (imported line %s)",
"shadowed-import",
"Used when a module is aliased with a name that shadows another import.",
),
}
DEFAULT_STANDARD_LIBRARY = ()
DEFAULT_KNOWN_THIRD_PARTY = ("enchant",)
DEFAULT_PREFERRED_MODULES = ()
class ImportsChecker(DeprecatedMixin, BaseChecker):
"""BaseChecker for import statements.
Checks for
* external modules dependencies
* relative / wildcard imports
* cyclic imports
* uses of deprecated modules
* uses of modules instead of preferred modules
"""
name = "imports"
msgs = {**DeprecatedMixin.DEPRECATED_MODULE_MESSAGE, **MSGS}
default_deprecated_modules = ()
options = (
(
"deprecated-modules",
{
"default": default_deprecated_modules,
"type": "csv",
"metavar": "<modules>",
"help": "Deprecated modules which should not be used,"
" separated by a comma.",
},
),
(
"preferred-modules",
{
"default": DEFAULT_PREFERRED_MODULES,
"type": "csv",
"metavar": "<module:preferred-module>",
"help": "Couples of modules and preferred modules,"
" separated by a comma.",
},
),
(
"import-graph",
{
"default": "",
"type": "path",
"metavar": "<file.gv>",
"help": "Output a graph (.gv or any supported image format) of"
" all (i.e. internal and external) dependencies to the given file"
" (report RP0402 must not be disabled).",
},
),
(
"ext-import-graph",
{
"default": "",
"type": "path",
"metavar": "<file.gv>",
"help": "Output a graph (.gv or any supported image format)"
" of external dependencies to the given file"
" (report RP0402 must not be disabled).",
},
),
(
"int-import-graph",
{
"default": "",
"type": "path",
"metavar": "<file.gv>",
"help": "Output a graph (.gv or any supported image format)"
" of internal dependencies to the given file"
" (report RP0402 must not be disabled).",
},
),
(
"known-standard-library",
{
"default": DEFAULT_STANDARD_LIBRARY,
"type": "csv",
"metavar": "<modules>",
"help": "Force import order to recognize a module as part of "
"the standard compatibility libraries.",
},
),
(
"known-third-party",
{
"default": DEFAULT_KNOWN_THIRD_PARTY,
"type": "csv",
"metavar": "<modules>",
"help": "Force import order to recognize a module as part of "
"a third party library.",
},
),
(
"allow-any-import-level",
{
"default": (),
"type": "csv",
"metavar": "<modules>",
"help": (
"List of modules that can be imported at any level, not just "
"the top level one."
),
},
),
(
"allow-wildcard-with-all",
{
"default": False,
"type": "yn",
"metavar": "<y or n>",
"help": "Allow wildcard imports from modules that define __all__.",
},
),
(
"allow-reexport-from-package",
{
"default": False,
"type": "yn",
"metavar": "<y or n>",
"help": "Allow explicit reexports by alias from a package __init__.",
},
),
)
def __init__(self, linter: PyLinter) -> None:
BaseChecker.__init__(self, linter)
self.import_graph: defaultdict[str, set[str]] = defaultdict(set)
self._imports_stack: list[tuple[ImportNode, str]] = []
self._first_non_import_node = None
self._module_pkg: dict[
Any, Any
] = {} # mapping of modules to the pkg they belong in
self._allow_any_import_level: set[Any] = set()
self.reports = (
("RP0401", "External dependencies", self._report_external_dependencies),
("RP0402", "Modules dependencies graph", self._report_dependencies_graph),
)
def open(self) -> None:
"""Called before visiting project (i.e set of modules)."""
self.linter.stats.dependencies = {}
self.linter.stats = self.linter.stats
self.import_graph = defaultdict(set)
self._module_pkg = {} # mapping of modules to the pkg they belong in
self._current_module_package = False
self._excluded_edges: defaultdict[str, set[str]] = defaultdict(set)
self._ignored_modules: Sequence[str] = self.linter.config.ignored_modules
# Build a mapping {'module': 'preferred-module'}
self.preferred_modules = dict(
module.split(":")
for module in self.linter.config.preferred_modules
if ":" in module
)
self._allow_any_import_level = set(self.linter.config.allow_any_import_level)
self._allow_reexport_package = self.linter.config.allow_reexport_from_package
def _import_graph_without_ignored_edges(self) -> defaultdict[str, set[str]]:
filtered_graph = copy.deepcopy(self.import_graph)
for node in filtered_graph:
filtered_graph[node].difference_update(self._excluded_edges[node])
return filtered_graph
def close(self) -> None:
"""Called before visiting project (i.e set of modules)."""
if self.linter.is_message_enabled("cyclic-import"):
graph = self._import_graph_without_ignored_edges()
vertices = list(graph)
for cycle in get_cycles(graph, vertices=vertices):
self.add_message("cyclic-import", args=" -> ".join(cycle))
def deprecated_modules(self) -> set[str]:
"""Callback returning the deprecated modules."""
# First get the modules the user indicated
all_deprecated_modules = set(self.linter.config.deprecated_modules)
# Now get the hard-coded ones from the stdlib
for since_vers, mod_set in DEPRECATED_MODULES.items():
if since_vers <= sys.version_info:
all_deprecated_modules = all_deprecated_modules.union(mod_set)
return all_deprecated_modules
def visit_module(self, node: nodes.Module) -> None:
"""Store if current module is a package, i.e. an __init__ file."""
self._current_module_package = node.package
def visit_import(self, node: nodes.Import) -> None:
"""Triggered when an import statement is seen."""
self._check_reimport(node)
self._check_import_as_rename(node)
self._check_toplevel(node)
names = [name for name, _ in node.names]
if len(names) >= 2:
self.add_message("multiple-imports", args=", ".join(names), node=node)
for name in names:
self.check_deprecated_module(node, name)
self._check_preferred_module(node, name)
imported_module = self._get_imported_module(node, name)
if isinstance(node.parent, nodes.Module):
# Allow imports nested
self._check_position(node)
if isinstance(node.scope(), nodes.Module):
self._record_import(node, imported_module)
if imported_module is None:
continue
self._add_imported_module(node, imported_module.name)
def visit_importfrom(self, node: nodes.ImportFrom) -> None:
"""Triggered when a from statement is seen."""
basename = node.modname
imported_module = self._get_imported_module(node, basename)
absolute_name = get_import_name(node, basename)
self._check_import_as_rename(node)
self._check_misplaced_future(node)
self.check_deprecated_module(node, absolute_name)
self._check_preferred_module(node, basename)
self._check_wildcard_imports(node, imported_module)
self._check_same_line_imports(node)
self._check_reimport(node, basename=basename, level=node.level)
self._check_toplevel(node)
if isinstance(node.parent, nodes.Module):
# Allow imports nested
self._check_position(node)
if isinstance(node.scope(), nodes.Module):
self._record_import(node, imported_module)
if imported_module is None:
return
for name, _ in node.names:
if name != "*":
self._add_imported_module(node, f"{imported_module.name}.{name}")
else:
self._add_imported_module(node, imported_module.name)
def leave_module(self, node: nodes.Module) -> None:
# Check imports are grouped by category (standard, 3rd party, local)
std_imports, ext_imports, loc_imports = self._check_imports_order(node)
# Check that imports are grouped by package within a given category
met_import: set[str] = set() # set for 'import x' style
met_from: set[str] = set() # set for 'from x import y' style
current_package = None
for import_node, import_name in std_imports + ext_imports + loc_imports:
met = met_from if isinstance(import_node, nodes.ImportFrom) else met_import
package, _, _ = import_name.partition(".")
if (
current_package
and current_package != package
and package in met
and not in_type_checking_block(import_node)
and not (
isinstance(import_node.parent, nodes.If)
and is_sys_guard(import_node.parent)
)
):
self.add_message("ungrouped-imports", node=import_node, args=package)
current_package = package
if not self.linter.is_message_enabled(
"ungrouped-imports", import_node.fromlineno
):
continue
met.add(package)
self._imports_stack = []
self._first_non_import_node = None
def compute_first_non_import_node(
self,
node: nodes.If
| nodes.Expr
| nodes.Comprehension
| nodes.IfExp
| nodes.Assign
| nodes.AssignAttr
| nodes.TryExcept
| nodes.TryFinally,
) -> None:
# if the node does not contain an import instruction, and if it is the
# first node of the module, keep a track of it (all the import positions
# of the module will be compared to the position of this first
# instruction)
if self._first_non_import_node:
return
if not isinstance(node.parent, nodes.Module):
return
nested_allowed = [nodes.TryExcept, nodes.TryFinally]
is_nested_allowed = [
allowed for allowed in nested_allowed if isinstance(node, allowed)
]
if is_nested_allowed and any(
node.nodes_of_class((nodes.Import, nodes.ImportFrom))
):
return
if isinstance(node, nodes.Assign):
# Add compatibility for module level dunder names
# https://www.python.org/dev/peps/pep-0008/#module-level-dunder-names
valid_targets = [
isinstance(target, nodes.AssignName)
and target.name.startswith("__")
and target.name.endswith("__")
for target in node.targets
]
if all(valid_targets):
return
self._first_non_import_node = node
visit_tryfinally = (
visit_tryexcept
) = (
visit_assignattr
) = (
visit_assign
) = (
visit_ifexp
) = visit_comprehension = visit_expr = visit_if = compute_first_non_import_node
def visit_functiondef(
self, node: nodes.FunctionDef | nodes.While | nodes.For | nodes.ClassDef
) -> None:
# If it is the first non import instruction of the module, record it.
if self._first_non_import_node:
return
# Check if the node belongs to an `If` or a `Try` block. If they
# contain imports, skip recording this node.
if not isinstance(node.parent.scope(), nodes.Module):
return
root = node
while not isinstance(root.parent, nodes.Module):
root = root.parent
if isinstance(root, (nodes.If, nodes.TryFinally, nodes.TryExcept)):
if any(root.nodes_of_class((nodes.Import, nodes.ImportFrom))):
return
self._first_non_import_node = node
visit_classdef = visit_for = visit_while = visit_functiondef
def _check_misplaced_future(self, node: nodes.ImportFrom) -> None:
basename = node.modname
if basename == "__future__":
# check if this is the first non-docstring statement in the module
prev = node.previous_sibling()
if prev:
# consecutive future statements are possible
if not (
isinstance(prev, nodes.ImportFrom) and prev.modname == "__future__"
):
self.add_message("misplaced-future", node=node)
return
def _check_same_line_imports(self, node: nodes.ImportFrom) -> None:
# Detect duplicate imports on the same line.
names = (name for name, _ in node.names)
counter = collections.Counter(names)
for name, count in counter.items():
if count > 1:
self.add_message("reimported", node=node, args=(name, node.fromlineno))
def _check_position(self, node: ImportNode) -> None:
"""Check `node` import or importfrom node position is correct.
Send a message if `node` comes before another instruction
"""
# if a first non-import instruction has already been encountered,
# it means the import comes after it and therefore is not well placed
if self._first_non_import_node:
if self.linter.is_message_enabled(
"wrong-import-position", self._first_non_import_node.fromlineno
):
self.add_message(
"wrong-import-position", node=node, args=node.as_string()
)
else:
self.linter.add_ignored_message(
"wrong-import-position", node.fromlineno, node
)
def _record_import(
self,
node: ImportNode,
importedmodnode: nodes.Module | None,
) -> None:
"""Record the package `node` imports from."""
if isinstance(node, nodes.ImportFrom):
importedname = node.modname
else:
importedname = importedmodnode.name if importedmodnode else None
if not importedname:
importedname = node.names[0][0].split(".")[0]
if isinstance(node, nodes.ImportFrom) and (node.level or 0) >= 1:
# We need the importedname with first point to detect local package
# Example of node:
# 'from .my_package1 import MyClass1'
# the output should be '.my_package1' instead of 'my_package1'
# Example of node:
# 'from . import my_package2'
# the output should be '.my_package2' instead of '{pyfile}'
importedname = "." + importedname
self._imports_stack.append((node, importedname))
@staticmethod
def _is_fallback_import(
node: ImportNode, imports: list[tuple[ImportNode, str]]
) -> bool:
imports = [import_node for (import_node, _) in imports]
return any(astroid.are_exclusive(import_node, node) for import_node in imports)
# pylint: disable = too-many-statements
def _check_imports_order(
self, _module_node: nodes.Module
) -> tuple[
list[tuple[ImportNode, str]],
list[tuple[ImportNode, str]],
list[tuple[ImportNode, str]],
]:
"""Checks imports of module `node` are grouped by category.
Imports must follow this order: standard, 3rd party, local
"""
std_imports: list[tuple[ImportNode, str]] = []
third_party_imports: list[tuple[ImportNode, str]] = []
first_party_imports: list[tuple[ImportNode, str]] = []
# need of a list that holds third or first party ordered import
external_imports: list[tuple[ImportNode, str]] = []
local_imports: list[tuple[ImportNode, str]] = []
third_party_not_ignored: list[tuple[ImportNode, str]] = []
first_party_not_ignored: list[tuple[ImportNode, str]] = []
local_not_ignored: list[tuple[ImportNode, str]] = []
isort_driver = IsortDriver(self.linter.config)
for node, modname in self._imports_stack:
if modname.startswith("."):
package = "." + modname.split(".")[1]
else:
package = modname.split(".")[0]
nested = not isinstance(node.parent, nodes.Module)
ignore_for_import_order = not self.linter.is_message_enabled(
"wrong-import-order", node.fromlineno
)
import_category = isort_driver.place_module(package)
node_and_package_import = (node, package)
if import_category in {"FUTURE", "STDLIB"}:
std_imports.append(node_and_package_import)
wrong_import = (
third_party_not_ignored
or first_party_not_ignored
or local_not_ignored
)
if self._is_fallback_import(node, wrong_import):
continue
if wrong_import and not nested:
self.add_message(
"wrong-import-order",
node=node,
args=(
f'standard import "{node.as_string()}"',
f'"{wrong_import[0][0].as_string()}"',
),
)
elif import_category == "THIRDPARTY":
third_party_imports.append(node_and_package_import)
external_imports.append(node_and_package_import)
if not nested:
if not ignore_for_import_order:
third_party_not_ignored.append(node_and_package_import)
else:
self.linter.add_ignored_message(
"wrong-import-order", node.fromlineno, node
)
wrong_import = first_party_not_ignored or local_not_ignored
if wrong_import and not nested:
self.add_message(
"wrong-import-order",
node=node,
args=(
f'third party import "{node.as_string()}"',
f'"{wrong_import[0][0].as_string()}"',
),
)
elif import_category == "FIRSTPARTY":
first_party_imports.append(node_and_package_import)
external_imports.append(node_and_package_import)
if not nested:
if not ignore_for_import_order:
first_party_not_ignored.append(node_and_package_import)
else:
self.linter.add_ignored_message(
"wrong-import-order", node.fromlineno, node
)
wrong_import = local_not_ignored
if wrong_import and not nested:
self.add_message(
"wrong-import-order",
node=node,
args=(
f'first party import "{node.as_string()}"',
f'"{wrong_import[0][0].as_string()}"',
),
)
elif import_category == "LOCALFOLDER":
local_imports.append((node, package))
if not nested:
if not ignore_for_import_order:
local_not_ignored.append((node, package))
else:
self.linter.add_ignored_message(
"wrong-import-order", node.fromlineno, node
)
return std_imports, external_imports, local_imports
def _get_imported_module(
self, importnode: ImportNode, modname: str | None
) -> nodes.Module | None:
try:
return importnode.do_import_module(modname)
except astroid.TooManyLevelsError:
if _ignore_import_failure(importnode, modname, self._ignored_modules):
return None
self.add_message("relative-beyond-top-level", node=importnode)
except astroid.AstroidSyntaxError as exc:
message = f"Cannot import {modname!r} due to '{exc.error}'"
self.add_message(
"syntax-error", line=importnode.lineno, args=message, confidence=HIGH
)
except astroid.AstroidBuildingError:
if not self.linter.is_message_enabled("import-error"):
return None
if _ignore_import_failure(importnode, modname, self._ignored_modules):
return None
if (
not self.linter.config.analyse_fallback_blocks
and is_from_fallback_block(importnode)
):
return None
dotted_modname = get_import_name(importnode, modname)
self.add_message("import-error", args=repr(dotted_modname), node=importnode)
except Exception as e: # pragma: no cover
raise astroid.AstroidError from e
return None
def _add_imported_module(self, node: ImportNode, importedmodname: str) -> None:
"""Notify an imported module, used to analyze dependencies."""
module_file = node.root().file
context_name = node.root().name
base = os.path.splitext(os.path.basename(module_file))[0]
try:
importedmodname = astroid.modutils.get_module_part(
importedmodname, module_file
)
except ImportError:
pass
if context_name == importedmodname:
self.add_message("import-self", node=node)
elif not astroid.modutils.is_stdlib_module(importedmodname):
# if this is not a package __init__ module
if base != "__init__" and context_name not in self._module_pkg:
# record the module's parent, or the module itself if this is
# a top level module, as the package it belongs to
self._module_pkg[context_name] = context_name.rsplit(".", 1)[0]
# handle dependencies
dependencies_stat: dict[str, set[str]] = self.linter.stats.dependencies
importedmodnames = dependencies_stat.setdefault(importedmodname, set())
if context_name not in importedmodnames:
importedmodnames.add(context_name)
# update import graph
self.import_graph[context_name].add(importedmodname)
if not self.linter.is_message_enabled(
"cyclic-import", line=node.lineno
) or in_type_checking_block(node):
self._excluded_edges[context_name].add(importedmodname)
def _check_preferred_module(self, node: ImportNode, mod_path: str) -> None:
"""Check if the module has a preferred replacement."""
mod_compare = [mod_path]
# build a comparison list of possible names using importfrom
if isinstance(node, astroid.nodes.node_classes.ImportFrom):
mod_compare = [f"{node.modname}.{name[0]}" for name in node.names]
# find whether there are matches with the import vs preferred_modules keys
matches = [
k
for k in self.preferred_modules
for mod in mod_compare
# exact match
if k == mod
# checks for base module matches
or k in mod.split(".")[0]
]
# if we have matches, add message
if matches:
self.add_message(
"preferred-module",
node=node,
args=(self.preferred_modules[matches[0]], matches[0]),
)
def _check_import_as_rename(self, node: ImportNode) -> None:
names = node.names
for name in names:
if not all(name):
return
splitted_packages = name[0].rsplit(".", maxsplit=1)
import_name = splitted_packages[-1]
aliased_name = name[1]
if import_name != aliased_name:
continue
if len(splitted_packages) == 1 and (
self._allow_reexport_package is False
or self._current_module_package is False
):
self.add_message("useless-import-alias", node=node, confidence=HIGH)
elif len(splitted_packages) == 2:
self.add_message(
"consider-using-from-import",
node=node,
args=(splitted_packages[0], import_name),
)
def _check_reimport(
self,
node: ImportNode,
basename: str | None = None,
level: int | None = None,
) -> None:
"""Check if a module with the same name is already imported or aliased."""
if not self.linter.is_message_enabled(
"reimported"
) and not self.linter.is_message_enabled("shadowed-import"):
return
frame = node.frame(future=True)
root = node.root()
contexts = [(frame, level)]
if root is not frame:
contexts.append((root, None))
for known_context, known_level in contexts:
for name, alias in node.names:
first, msg = _get_first_import(
node, known_context, name, basename, known_level, alias
)
if first is not None and msg is not None:
name = name if msg == "reimported" else alias
self.add_message(
msg, node=node, args=(name, first.fromlineno), confidence=HIGH
)
def _report_external_dependencies(
self, sect: Section, _: LinterStats, _dummy: LinterStats | None
) -> None:
"""Return a verbatim layout for displaying dependencies."""
dep_info = _make_tree_defs(self._external_dependencies_info.items())
if not dep_info:
raise EmptyReportError()
tree_str = _repr_tree_defs(dep_info)
sect.append(VerbatimText(tree_str))
def _report_dependencies_graph(
self, sect: Section, _: LinterStats, _dummy: LinterStats | None
) -> None:
"""Write dependencies as a dot (graphviz) file."""
dep_info = self.linter.stats.dependencies
if not dep_info or not (
self.linter.config.import_graph
or self.linter.config.ext_import_graph
or self.linter.config.int_import_graph
):
raise EmptyReportError()
filename = self.linter.config.import_graph
if filename:
_make_graph(filename, dep_info, sect, "")
filename = self.linter.config.ext_import_graph
if filename:
_make_graph(filename, self._external_dependencies_info, sect, "external ")
filename = self.linter.config.int_import_graph
if filename:
_make_graph(filename, self._internal_dependencies_info, sect, "internal ")
def _filter_dependencies_graph(self, internal: bool) -> defaultdict[str, set[str]]:
"""Build the internal or the external dependency graph."""
graph: defaultdict[str, set[str]] = defaultdict(set)
for importee, importers in self.linter.stats.dependencies.items():
for importer in importers:
package = self._module_pkg.get(importer, importer)
is_inside = importee.startswith(package)
if is_inside and internal or not is_inside and not internal:
graph[importee].add(importer)
return graph
@cached_property
def _external_dependencies_info(self) -> defaultdict[str, set[str]]:
"""Return cached external dependencies information or build and
cache them.
"""
return self._filter_dependencies_graph(internal=False)
@cached_property
def _internal_dependencies_info(self) -> defaultdict[str, set[str]]:
"""Return cached internal dependencies information or build and
cache them.
"""
return self._filter_dependencies_graph(internal=True)
def _check_wildcard_imports(
self, node: nodes.ImportFrom, imported_module: nodes.Module | None
) -> None:
if node.root().package:
# Skip the check if in __init__.py issue #2026
return
wildcard_import_is_allowed = self._wildcard_import_is_allowed(imported_module)
for name, _ in node.names:
if name == "*" and not wildcard_import_is_allowed:
self.add_message("wildcard-import", args=node.modname, node=node)
def _wildcard_import_is_allowed(self, imported_module: nodes.Module | None) -> bool:
return (
self.linter.config.allow_wildcard_with_all
and imported_module is not None
and "__all__" in imported_module.locals
)
def _check_toplevel(self, node: ImportNode) -> None:
"""Check whether the import is made outside the module toplevel."""
# If the scope of the import is a module, then obviously it is
# not outside the module toplevel.
if isinstance(node.scope(), nodes.Module):
return
module_names = [
f"{node.modname}.{name[0]}"
if isinstance(node, nodes.ImportFrom)
else name[0]
for name in node.names
]
# Get the full names of all the imports that are only allowed at the module level
scoped_imports = [
name for name in module_names if name not in self._allow_any_import_level
]
if scoped_imports:
self.add_message(
"import-outside-toplevel", args=", ".join(scoped_imports), node=node
)
def register(linter: PyLinter) -> None:
linter.register_checker(ImportsChecker(linter))
Mini Shell