Current File : //opt/cloudlinux/venv/lib/python3.11/site-packages/pylint/extensions/private_import.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
"""Check for imports on private external modules and names."""
from __future__ import annotations
from pathlib import Path
from typing import TYPE_CHECKING
from astroid import nodes
from pylint.checkers import BaseChecker, utils
from pylint.interfaces import HIGH
if TYPE_CHECKING:
from pylint.lint.pylinter import PyLinter
class PrivateImportChecker(BaseChecker):
name = "import-private-name"
msgs = {
"C2701": (
"Imported private %s (%s)",
"import-private-name",
"Used when a private module or object prefixed with _ is imported. "
"PEP8 guidance on Naming Conventions states that public attributes with "
"leading underscores should be considered private.",
),
}
def __init__(self, linter: PyLinter) -> None:
BaseChecker.__init__(self, linter)
# A mapping of private names used as a type annotation to whether it is an acceptable import
self.all_used_type_annotations: dict[str, bool] = {}
self.populated_annotations = False
@utils.only_required_for_messages("import-private-name")
def visit_import(self, node: nodes.Import) -> None:
if utils.in_type_checking_block(node):
return
names = [name[0] for name in node.names]
private_names = self._get_private_imports(names)
private_names = self._get_type_annotation_names(node, private_names)
if private_names:
imported_identifier = "modules" if len(private_names) > 1 else "module"
private_name_string = ", ".join(private_names)
self.add_message(
"import-private-name",
node=node,
args=(imported_identifier, private_name_string),
confidence=HIGH,
)
@utils.only_required_for_messages("import-private-name")
def visit_importfrom(self, node: nodes.ImportFrom) -> None:
if utils.in_type_checking_block(node):
return
# Only check imported names if the module is external
if self.same_root_dir(node, node.modname):
return
names = [n[0] for n in node.names]
# Check the imported objects first. If they are all valid type annotations,
# the package can be private
private_names = self._get_type_annotation_names(node, names)
if not private_names:
return
# There are invalid imported objects, so check the name of the package
private_module_imports = self._get_private_imports([node.modname])
private_module_imports = self._get_type_annotation_names(
node, private_module_imports
)
if private_module_imports:
self.add_message(
"import-private-name",
node=node,
args=("module", private_module_imports[0]),
confidence=HIGH,
)
return # Do not emit messages on the objects if the package is private
private_names = self._get_private_imports(private_names)
if private_names:
imported_identifier = "objects" if len(private_names) > 1 else "object"
private_name_string = ", ".join(private_names)
self.add_message(
"import-private-name",
node=node,
args=(imported_identifier, private_name_string),
confidence=HIGH,
)
def _get_private_imports(self, names: list[str]) -> list[str]:
"""Returns the private names from input names by a simple string check."""
return [name for name in names if self._name_is_private(name)]
@staticmethod
def _name_is_private(name: str) -> bool:
"""Returns true if the name exists, starts with `_`, and if len(name) > 4
it is not a dunder, i.e. it does not begin and end with two underscores.
"""
return (
bool(name)
and name[0] == "_"
and (len(name) <= 4 or name[1] != "_" or name[-2:] != "__")
)
def _get_type_annotation_names(
self, node: nodes.Import | nodes.ImportFrom, names: list[str]
) -> list[str]:
"""Removes from names any names that are used as type annotations with no other
illegal usages.
"""
if names and not self.populated_annotations:
self._populate_type_annotations(node.root(), self.all_used_type_annotations)
self.populated_annotations = True
return [
n
for n in names
if n not in self.all_used_type_annotations
or (
n in self.all_used_type_annotations
and not self.all_used_type_annotations[n]
)
]
def _populate_type_annotations(
self, node: nodes.LocalsDictNodeNG, all_used_type_annotations: dict[str, bool]
) -> None:
"""Adds to `all_used_type_annotations` all names ever used as a type annotation
in the node's (nested) scopes and whether they are only used as annotation.
"""
for name in node.locals:
# If we find a private type annotation, make sure we do not mask illegal usages
private_name = None
# All the assignments using this variable that we might have to check for
# illegal usages later
name_assignments = []
for usage_node in node.locals[name]:
if isinstance(usage_node, nodes.AssignName) and isinstance(
usage_node.parent, (nodes.AnnAssign, nodes.Assign)
):
assign_parent = usage_node.parent
if isinstance(assign_parent, nodes.AnnAssign):
name_assignments.append(assign_parent)
private_name = self._populate_type_annotations_annotation(
usage_node.parent.annotation, all_used_type_annotations
)
elif isinstance(assign_parent, nodes.Assign):
name_assignments.append(assign_parent)
if isinstance(usage_node, nodes.FunctionDef):
self._populate_type_annotations_function(
usage_node, all_used_type_annotations
)
if isinstance(usage_node, nodes.LocalsDictNodeNG):
self._populate_type_annotations(
usage_node, all_used_type_annotations
)
if private_name is not None:
# Found a new private annotation, make sure we are not accessing it elsewhere
all_used_type_annotations[
private_name
] = self._assignments_call_private_name(name_assignments, private_name)
def _populate_type_annotations_function(
self, node: nodes.FunctionDef, all_used_type_annotations: dict[str, bool]
) -> None:
"""Adds all names used as type annotation in the arguments and return type of
the function node into the dict `all_used_type_annotations`.
"""
if node.args and node.args.annotations:
for annotation in node.args.annotations:
self._populate_type_annotations_annotation(
annotation, all_used_type_annotations
)
if node.returns:
self._populate_type_annotations_annotation(
node.returns, all_used_type_annotations
)
def _populate_type_annotations_annotation(
self,
node: nodes.Attribute | nodes.Subscript | nodes.Name | None,
all_used_type_annotations: dict[str, bool],
) -> str | None:
"""Handles the possibility of an annotation either being a Name, i.e. just type,
or a Subscript e.g. `Optional[type]` or an Attribute, e.g. `pylint.lint.linter`.
"""
if isinstance(node, nodes.Name) and node.name not in all_used_type_annotations:
all_used_type_annotations[node.name] = True
return node.name # type: ignore[no-any-return]
if isinstance(node, nodes.Subscript): # e.g. Optional[List[str]]
# slice is the next nested type
self._populate_type_annotations_annotation(
node.slice, all_used_type_annotations
)
# value is the current type name: could be a Name or Attribute
return self._populate_type_annotations_annotation(
node.value, all_used_type_annotations
)
if isinstance(node, nodes.Attribute):
# An attribute is a type like `pylint.lint.pylinter`. node.expr is the next level
# up, could be another attribute
return self._populate_type_annotations_annotation(
node.expr, all_used_type_annotations
)
return None
@staticmethod
def _assignments_call_private_name(
assignments: list[nodes.AnnAssign | nodes.Assign], private_name: str
) -> bool:
"""Returns True if no assignments involve accessing `private_name`."""
if all(not assignment.value for assignment in assignments):
# Variable annotated but unassigned is not allowed because there may be
# possible illegal access elsewhere
return False
for assignment in assignments:
current_attribute = None
if isinstance(assignment.value, nodes.Call):
current_attribute = assignment.value.func
elif isinstance(assignment.value, nodes.Attribute):
current_attribute = assignment.value
elif isinstance(assignment.value, nodes.Name):
current_attribute = assignment.value.name
if not current_attribute:
continue
while isinstance(current_attribute, (nodes.Attribute, nodes.Call)):
if isinstance(current_attribute, nodes.Call):
current_attribute = current_attribute.func
if not isinstance(current_attribute, nodes.Name):
current_attribute = current_attribute.expr
if (
isinstance(current_attribute, nodes.Name)
and current_attribute.name == private_name
):
return False
return True
@staticmethod
def same_root_dir(
node: nodes.Import | nodes.ImportFrom, import_mod_name: str
) -> bool:
"""Does the node's file's path contain the base name of `import_mod_name`?"""
if not import_mod_name: # from . import ...
return True
if node.level: # from .foo import ..., from ..bar import ...
return True
base_import_package = import_mod_name.split(".")[0]
return base_import_package in Path(node.root().file).parent.parts
def register(linter: PyLinter) -> None:
linter.register_checker(PrivateImportChecker(linter))