Document areas of code complexity

Author: cclauss

isort/api.py

@@ -66,7 +66,7 @@ class ImportKey(Enum):
     ALIAS = 4
 
 
-def sort_code_string(
+def sort_code_string(  # noqa: PLR0913
     code: str,
     extension: Optional[str] = None,
     config: Config = DEFAULT_CONFIG,
@@ -85,6 +85,12 @@ def sort_code_string(
     - **show_diff**: If `True` the changes that need to be done will be printed to stdout, if a
     TextIO stream is provided results will be written to it, otherwise no diff will be computed.
     - ****config_kwargs**: Any config modifications.
+
+    Future modifications should consider refactoring to reduce complexity.
+
+    * There are currently 6 function argurments vs 5 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
     """
     input_stream = StringIO(code)
     output_stream = StringIO()
@@ -102,7 +108,7 @@ def sort_code_string(
     return output_stream.read()
 
 
-def check_code_string(
+def check_code_string(  # noqa: PLR0913
     code: str,
     show_diff: Union[bool, TextIO] = False,
     extension: Optional[str] = None,
@@ -122,6 +128,12 @@ def check_code_string(
     - **file_path**: The disk location where the code string was pulled from.
     - **disregard_skip**: set to `True` if you want to ignore a skip set in config for this file.
     - ****config_kwargs**: Any config modifications.
+
+    Future modifications should consider refactoring to reduce complexity.
+
+    * There are currently 6 function argurments vs 5 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
     """
     config = _config(path=file_path, config=config, **config_kwargs)
     return check_stream(
@@ -134,7 +146,7 @@ def check_code_string(
     )
 
 
-def sort_stream(
+def sort_stream(  # noqa: C901,PLR0913,PLR0912
     input_stream: TextIO,
     output_stream: TextIO,
     extension: Optional[str] = None,
@@ -157,6 +169,14 @@ def sort_stream(
     - **show_diff**: If `True` the changes that need to be done will be printed to stdout, if a
     TextIO stream is provided results will be written to it, otherwise no diff will be computed.
     - ****config_kwargs**: Any config modifications.
+
+    Future modifications should consider refactoring to reduce complexity.
+
+    * The McCabe cyclomatic complexity is currently 14 vs 10 recommended.
+    * There are currently 8 function argurments vs 5 recommended.
+    * There are currently 13 branches vs 12 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
     """
     extension = extension or (file_path and file_path.suffix.lstrip(".")) or "py"
     if show_diff:
@@ -237,7 +257,7 @@ def sort_stream(
     return changed
 
 
-def check_stream(
+def check_stream(  # noqa: PLR0913
     input_stream: TextIO,
     show_diff: Union[bool, TextIO] = False,
     extension: Optional[str] = None,
@@ -257,6 +277,12 @@ def check_stream(
     - **file_path**: The disk location where the code string was pulled from.
     - **disregard_skip**: set to `True` if you want to ignore a skip set in config for this file.
     - ****config_kwargs**: Any config modifications.
+
+    Future modifications should consider refactoring to reduce complexity.
+
+    * There are currently 6 function argurments vs 5 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
     """
     config = _config(path=file_path, config=config, **config_kwargs)
 
@@ -304,7 +330,7 @@ def check_stream(
     return False
 
 
-def check_file(
+def check_file(  # noqa: PLR0913
     filename: Union[str, Path],
     show_diff: Union[bool, TextIO] = False,
     config: Config = DEFAULT_CONFIG,
@@ -324,6 +350,12 @@ def check_file(
     - **disregard_skip**: set to `True` if you want to ignore a skip set in config for this file.
     - **extension**: The file extension that contains imports. Defaults to filename extension or py.
     - ****config_kwargs**: Any config modifications.
+
+    Future modifications should consider refactoring to reduce complexity.
+
+    * There are currently 6 function argurments vs 5 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
     """
     file_config: Config = config
 
@@ -368,7 +400,7 @@ def _file_output_stream_context(filename: Union[str, Path], source_file: File) -
 # Ignore DeepSource cyclomatic complexity check for this function. It is one
 # the main entrypoints so sort of expected to be complex.
 # skipcq: PY-R1000
-def sort_file(
+def sort_file(  # noqa: C901,PLR0913,PLR0912,PLR0915
     filename: Union[str, Path],
     extension: Optional[str] = None,
     config: Config = DEFAULT_CONFIG,
@@ -395,6 +427,15 @@ def sort_file(
     - **output**: If a TextIO is provided, results will be written there rather than replacing
     the original file content.
     - ****config_kwargs**: Any config modifications.
+
+    Future modifications should consider refactoring to reduce complexity.
+
+    * The McCabe cyclomatic complexity is currently 18 vs 10 recommended.
+    * There are currently 9 function argurments vs 5 recommended.
+    * There are currently 21 branches vs 12 recommended.
+    * There are currently 59 statements vs 50 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
     """
     file_config: Config = config
 

isort/core.py

@@ -29,7 +29,7 @@
 
 # Ignore DeepSource cyclomatic complexity check for this function.
 # skipcq: PY-R1000
-def process(
+def process(  # noqa: C901,PLR0912,PLR0915
     input_stream: TextIO,
     output_stream: TextIO,
     extension: str = "py",
@@ -51,6 +51,14 @@ def process(
 
     Returns `True` if there were changes that needed to be made (errors present) from what
     was provided in the input_stream, otherwise `False`.
+
+    Future modifications should consider refactoring to reduce complexity.
+
+    * The McCabe cyclomatic complexity is currently 91 vs 10 recommended.
+    * There are currently 104 branches vs 12 recommended.
+    * There are currently 293 statements vs 50 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
     """
     line_separator: str = config.line_ending
     add_imports: List[str] = [format_natural(addition) for addition in config.add_imports]

isort/files.py

@@ -5,10 +5,18 @@
 from isort.settings import Config
 
 
-def find(
+def find(  # noqa: C901,PLR0912
     paths: Iterable[str], config: Config, skipped: List[str], broken: List[str]
 ) -> Iterator[str]:
-    """Fines and provides an iterator for all Python source files defined in paths."""
+    """Fines and provides an iterator for all Python source files defined in paths.
+
+    Future modifications should consider refactoring to reduce complexity.
+
+    * The McCabe cyclomatic complexity is currently 11 vs 10 recommended.
+    * There are currently 13 branches vs 12 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
+    """
     visited_dirs: Set[Path] = set()
 
     for path in paths:

isort/identify.py

@@ -40,13 +40,22 @@ def __str__(self) -> str:
         )
 
 
-def imports(
+def imports(  # noqa: C901,PLR0912,PLR0915
     input_stream: TextIO,
     config: Config = DEFAULT_CONFIG,
     file_path: Optional[Path] = None,
     top_only: bool = False,
 ) -> Iterator[Import]:
-    """Parses a python file taking out and categorizing imports."""
+    """Parses a python file taking out and categorizing imports.
+
+    Future modifications should consider refactoring to reduce complexity.
+
+    * The McCabe cyclomatic complexity is currently 33 vs 10 recommended.
+    * There are currently 40 branches vs 12 recommended.
+    * There are currently 109 statements vs 50 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
+    """
     in_quote = ""
 
     indexed_input = enumerate(input_stream)

isort/main.py

@@ -131,7 +131,13 @@ def _print_hard_fail(
     printer.error(message)
 
 
-def _build_arg_parser() -> argparse.ArgumentParser:
+def _build_arg_parser() -> argparse.ArgumentParser:  # noqa: PLR0915
+    """Future modifications should consider refactoring to reduce complexity.
+
+    * There are currently 113 statements vs 50 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
+    """
     parser = argparse.ArgumentParser(
         description="Sort Python import definitions alphabetically "
         "within logical sections. Run with no arguments to see a quick "
@@ -1057,7 +1063,17 @@ def identify_imports_main(
             print(str(identified_import))
 
 
-def main(argv: Optional[Sequence[str]] = None, stdin: Optional[TextIOWrapper] = None) -> None:
+def main(  # noqa: C901,PLR0912,PLR0915
+    argv: Optional[Sequence[str]] = None, stdin: Optional[TextIOWrapper] = None
+) -> None:
+    """Future modifications should consider refactoring to reduce complexity.
+
+    * The McCabe cyclomatic complexity is currently 46 vs 10 recommended.
+    * There are currently 51 branches vs 12 recommended.
+    * There are currently 138 statements vs 50 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
+    """
     arguments = parse_args(argv)
     if arguments.get("show_version"):
         print(ASCII_ART)

isort/output.py

@@ -11,7 +11,7 @@
 from .settings import DEFAULT_CONFIG, Config
 
 
-def sorted_imports(
+def sorted_imports(  # noqa: C901,PLR0912,PLR0915
     parsed: parse.ParsedContent,
     config: Config = DEFAULT_CONFIG,
     extension: str = "py",
@@ -21,6 +21,13 @@ def sorted_imports(
 
     (at the index of the first import) sorted alphabetically and split between groups
 
+    Future modifications should consider refactoring to reduce complexity.
+
+    * The McCabe cyclomatic complexity is currently 49 vs 10 recommended.
+    * There are currently 53 branches vs 12 recommended.
+    * There are currently 133 statements vs 50 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
     """
     if parsed.import_index == -1:
         return _output_as_string(parsed.lines_without_imports, parsed.line_separator)
@@ -243,14 +250,23 @@ def sorted_imports(
 # Ignore DeepSource cyclomatic complexity check for this function. It was
 # already complex when this check was enabled.
 # skipcq: PY-R1000
-def _with_from_imports(
+def _with_from_imports(  # noqa: C901,PLR0913,PLR0912,PLR0915
     parsed: parse.ParsedContent,
     config: Config,
     from_modules: Iterable[str],
     section: str,
     remove_imports: List[str],
     import_type: str,
 ) -> List[str]:
+    """Future modifications should consider refactoring to reduce complexity.
+
+    * The McCabe cyclomatic complexity is currently 43 vs 10 recommended.
+    * There are currently 6 function argurments vs 5 recommended.
+    * There are currently 47 branches vs 12 recommended.
+    * There are currently 110 statements vs 50 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
+    """
     output: List[str] = []
     for module in from_modules:
         if module in remove_imports:
@@ -559,14 +575,22 @@ def _with_from_imports(
     return output
 
 
-def _with_straight_imports(
+def _with_straight_imports(  # noqa: C901,PLR0913,PLR0912
     parsed: parse.ParsedContent,
     config: Config,
     straight_modules: Iterable[str],
     section: str,
     remove_imports: List[str],
     import_type: str,
 ) -> List[str]:
+    """Future modifications should consider refactoring to reduce complexity.
+
+    * The McCabe cyclomatic complexity is currently 13 vs 10 recommended.
+    * There are currently 6 function argurments vs 5 recommended.
+    * There are currently 15 branches vs 12 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
+    """
     output: List[str] = []
 
     as_imports = any(module in parsed.as_map["straight"] for module in straight_modules)

isort/parse.py

@@ -80,7 +80,7 @@ def strip_syntax(import_string: str) -> str:
     return import_string.replace("{ ", "{|").replace(" }", "|}")
 
 
-def skip_line(
+def skip_line(  # noqa: C901
     line: str,
     in_quote: str,
     index: int,
@@ -93,6 +93,12 @@ def skip_line(
 
     (skip_line: bool,
      in_quote: str,)
+
+    Future modifications should consider refactoring to reduce complexity.
+
+    * The McCabe cyclomatic complexity is currently 12 vs 10 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
     """
     should_skip = bool(in_quote)
     if '"' in line or "'" in line:
@@ -143,8 +149,19 @@ class ParsedContent(NamedTuple):
     trailing_commas: Set[str]
 
 
-def file_contents(contents: str, config: Config = DEFAULT_CONFIG) -> ParsedContent:
-    """Parses a python file taking out and categorizing imports."""
+def file_contents(  # noqa: C901,PLR0912,PLR0915
+    contents: str, config: Config = DEFAULT_CONFIG
+) -> ParsedContent:
+    """Parses a python file taking out and categorizing imports.
+
+    Future modifications should consider refactoring to reduce complexity.
+
+    * The McCabe cyclomatic complexity is currently 80 vs 10 recommended.
+    * There are currently 93 branches vs 12 recommended.
+    * There are currently 258 statements vs 50 recommended.
+
+    To revalidate these numbers, run `ruff check --select=C901,PLR091`.
+    """
     line_separator: str = config.line_ending or _infer_line_separator(contents)
     in_lines = contents.splitlines()
     if contents and contents[-1] in ("\n", "\r"):