nk-python-style 0.1.0__py3-none-any.whl

nk_python/__init__.py

@@ -0,0 +1 @@
+"""Python style checks inspired by the C++ tooling in this repository."""

nk_python/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

nk_python/ast_checks.py

@@ -0,0 +1,79 @@
+"""Checks that need Python syntax rather than regular expressions."""
+
+import ast
+from pathlib import Path
+
+from .model import Issue
+
+MAX_LINE_LENGTH = 120
+MAX_FILE_LINES = 120
+MAX_FUNCTION_LINES = 40
+MAX_PARAMETERS = 5
+
+
+def function_ranges(tree: ast.AST, source: str) -> list[tuple[int, int]]:
+    lines = source.splitlines()
+    ranges = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        end = node.end_lineno or node.lineno
+        for index in range(end, len(lines)):
+            stripped = lines[index].lstrip(" \t")
+            if not stripped:
+                continue
+            indentation = len(lines[index]) - len(stripped)
+            if stripped.startswith("#") and indentation > node.col_offset:
+                end = index + 1
+                continue
+            break
+        ranges.append((node.lineno, end))
+    return ranges
+
+
+def check_source(path: Path, source: str) -> tuple[list[Issue], list[tuple[int, int]]]:
+    issues: list[Issue] = []
+    lines = source.splitlines()
+    for number, line in enumerate(lines, 1):
+        if len(line) > MAX_LINE_LENGTH:
+            issues.append(Issue(path, number, "PY001", f"Line has {len(line)} characters (max {MAX_LINE_LENGTH})."))
+    if len(lines) > MAX_FILE_LINES:
+        issues.append(Issue(path, MAX_FILE_LINES + 1, "PY002", f"File has {len(lines)} lines (max {MAX_FILE_LINES})."))
+
+    try:
+        tree = ast.parse(source, filename=str(path))
+    except SyntaxError as error:
+        issues.append(Issue(path, error.lineno or 1, "PY000", f"Invalid Python syntax: {error.msg}."))
+        return issues, []
+
+    parents = {child: parent for parent in ast.walk(tree) for child in ast.iter_child_nodes(parent)}
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        length = (node.end_lineno or node.lineno) - node.lineno + 1
+        if length > MAX_FUNCTION_LINES:
+            issues.append(
+                Issue(
+                    path, node.lineno, "PY003", f"Function '{node.name}' has {length} lines (max {MAX_FUNCTION_LINES})."
+                )
+            )
+        count = _parameter_count(node, parents.get(node))
+        if count > MAX_PARAMETERS:
+            issues.append(
+                Issue(
+                    path, node.lineno, "PY004", f"Function '{node.name}' has {count} parameters (max {MAX_PARAMETERS})."
+                )
+            )
+    return issues, function_ranges(tree, source)
+
+
+def _parameter_count(node: ast.FunctionDef | ast.AsyncFunctionDef, parent: ast.AST | None) -> int:
+    positional = node.args.posonlyargs + node.args.args
+    count = len(positional) + len(node.args.kwonlyargs)
+    count += int(node.args.vararg is not None) + int(node.args.kwarg is not None)
+    is_static = any(
+        isinstance(decorator, ast.Name) and decorator.id == "staticmethod" for decorator in node.decorator_list
+    )
+    if isinstance(parent, ast.ClassDef) and not is_static and positional and positional[0].arg in {"self", "cls"}:
+        count -= 1
+    return count

nk_python/cli.py

@@ -0,0 +1,100 @@
+"""Command line entry point for formatting and checking Python projects."""
+
+import argparse
+import importlib.util
+import re
+import sys
+from pathlib import Path
+
+from .ast_checks import check_source
+from .comment_checks import LANGUAGE_AVAILABLE, check_comments
+from .model import Issue
+from .ruff_runner import run_ruff
+from .structure_checks import discover
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="nk-python")
+    parser.add_argument("command", choices=("check", "format"), help="Check without writing, or format in place.")
+    parser.add_argument(
+        "paths", nargs="*", default=["."], help="Python files or directories (default: current directory)."
+    )
+    parser.add_argument("--max-files", type=_positive_int, default=8, help="Maximum direct Python files per directory.")
+    arguments = parser.parse_args(argv)
+
+    if importlib.util.find_spec("ruff") is None:
+        print("Ruff is required. Install this tool with: pip install -e ./python", file=sys.stderr)
+        return 2
+    try:
+        files, structure_issues = discover([Path(value) for value in arguments.paths], arguments.max_files)
+    except (FileNotFoundError, ValueError) as error:
+        print(error, file=sys.stderr)
+        return 2
+    if not files:
+        print("No Python files found.", file=sys.stderr)
+        return 2
+
+    if arguments.command == "format":
+        import_status = run_ruff("check", files, "--select", "I", "--fix")
+        format_status = run_ruff("format", files)
+        return max(import_status, format_status)
+
+    return _check(files, structure_issues)
+
+
+def _check(files: list[Path], structure_issues: list[Issue]) -> int:
+    lint_output: list[str] = []
+    import_output: list[str] = []
+    format_output: list[str] = []
+    lint_status = run_ruff("check", files, "--ignore", "I", "--unfixable", "ALL", "--quiet", output=lint_output)
+    issues = structure_issues + _check_files(files)
+    import_status = run_ruff("check", files, "--select", "I", "--quiet", output=import_output)
+    format_status = run_ruff("format", files, "--check", output=format_output)
+    lint_text, import_text, format_text = ("".join(output) for output in (lint_output, import_output, format_output))
+    diagnostic_pattern = r"^.+:\d+:\d+: "
+    lint_count = len(re.findall(diagnostic_pattern, lint_text, re.MULTILINE)) + len(issues)
+    import_count = len(re.findall(diagnostic_pattern, import_text, re.MULTILINE))
+    format_count = sum(
+        int(count) for count in re.findall(r"^(\d+) files? would be reformatted", format_text, re.MULTILINE)
+    )
+    print("=== Check summary ===")
+    print(f"Files checked: {len(files)}")
+    print(f"Linter: {lint_count} warnings")
+    print(f"Formatter: {import_count} import diagnostics; {format_count} files to reformat")
+    if 2 in (lint_status, import_status, format_status):
+        print("Ruff could not complete the check; counts may be incomplete.")
+    elif not (lint_status or import_status or format_status or issues):
+        print("All checks passed!")
+
+    print("\n=== Linter diagnostics ===")
+    print(lint_text, end="")
+    for issue in sorted(issues):
+        print(issue)
+    if not LANGUAGE_AVAILABLE:
+        print("Comment language check skipped (install nk-python-style[comments] to enable it).")
+
+    print("\n=== Formatter: corrections available via 'format' ===")
+    print(import_text, end="")
+    print(format_text, end="")
+    return int(bool(lint_status or import_status or format_status or issues))
+
+
+def _positive_int(value: str) -> int:
+    result = int(value)
+    if result < 1:
+        raise argparse.ArgumentTypeError("--max-files must be positive")
+    return result
+
+
+def _check_files(files: list[Path]) -> list[Issue]:
+    issues: list[Issue] = []
+    for path in files:
+        try:
+            source = path.read_text(encoding="utf-8-sig")
+        except (OSError, UnicodeError) as error:
+            issues.append(Issue(path, 1, "PY000", f"Cannot read UTF-8 source: {error}."))
+            continue
+        source_issues, functions = check_source(path, source)
+        issues.extend(source_issues)
+        issues.extend(check_comments(path, source, functions))
+    return issues

nk_python/comment_checks.py

@@ -0,0 +1,82 @@
+"""Token-based comment placement and optional language checks."""
+
+import io
+import re
+import tokenize
+from pathlib import Path
+
+from .model import Issue
+
+try:
+    from lingua import Language, LanguageDetectorBuilder
+except ImportError:
+    Language = None
+    LanguageDetectorBuilder = None
+
+LANGUAGE_AVAILABLE = LanguageDetectorBuilder is not None
+_detector = None
+_DIRECTIVE = re.compile(
+    r"^(?:!|coding[:=]|noqa\b|type:\s*ignore\b|pyright:\s*ignore\b|"
+    r"pylint:|fmt:|ruff:|isort:|pragma:\s*no cover\b)",
+    re.IGNORECASE,
+)
+_WORD = re.compile(r"[A-Za-zÀ-ÖØ-öø-ÿ]+")
+_META_WORD = re.compile(r"^(?:TODO|FIXME|XXX|HACK|NOTE|WIP)$", re.IGNORECASE)
+
+
+def check_comments(path: Path, source: str, functions: list[tuple[int, int]]) -> list[Issue]:
+    issues: list[Issue] = []
+    source_lines = source.splitlines()
+    try:
+        tokens = tokenize.generate_tokens(io.StringIO(source).readline)
+        for token in tokens:
+            if token.type != tokenize.COMMENT:
+                continue
+            line_number, column = token.start
+            comment = token.string[1:].strip()
+            if _DIRECTIVE.match(comment):
+                continue
+            inside = any(start <= line_number <= end for start, end in functions)
+            if inside:
+                issues.append(
+                    Issue(path, line_number, "PY006", "Use a docstring or clear code instead of a function comment.")
+                )
+            elif source_lines[line_number - 1][:column].strip():
+                issues.append(Issue(path, line_number, "PY005", "Place the comment on its own line."))
+            language = _comment_language(comment)
+            if language:
+                issues.append(Issue(path, line_number, "PY007", f"Comment appears to be in {language}; use English."))
+    except (tokenize.TokenError, IndentationError):
+        pass
+    return issues
+
+
+def _comment_language(comment: str) -> str | None:
+    if not LANGUAGE_AVAILABLE:
+        return None
+    words = [word for word in _WORD.findall(comment) if _natural_word(word)]
+    if len(words) < 3 or len(" ".join(words)) < 20:
+        return None
+    confidences = _get_detector().compute_language_confidence_values(" ".join(words))
+    if not confidences or confidences[0].language == Language.ENGLISH:
+        return None
+    english = next((item.value for item in confidences if item.language == Language.ENGLISH), 0.0)
+    margin = 0.35 if len(words) <= 5 else 0.15
+    if confidences[0].value - english < margin:
+        return None
+    return confidences[0].language.name.title()
+
+
+def _natural_word(word: str) -> bool:
+    if _META_WORD.fullmatch(word) or word.isupper():
+        return False
+    return not any(left.islower() and right.isupper() for left, right in zip(word, word[1:], strict=False))
+
+
+def _get_detector():
+    global _detector
+    if _detector is None:
+        _detector = LanguageDetectorBuilder.from_languages(
+            Language.ENGLISH, Language.FRENCH, Language.SPANISH, Language.GERMAN
+        ).build()
+    return _detector

nk_python/model.py

@@ -0,0 +1,14 @@
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, order=True)
+class Issue:
+    path: Path
+    line: int
+    code: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{os.path.relpath(self.path)}:{self.line}: {self.code} {self.message}"

nk_python/ruff.toml

@@ -0,0 +1,13 @@
+line-length = 120
+indent-width = 4
+target-version = "py310"
+output-format = "concise"
+extend-exclude = [".git", ".venv*", "venv", "__pycache__", "build", "dist", "node_modules"]
+
+[lint]
+select = ["E4", "E7", "E9", "F", "I", "B", "UP", "RET504"]
+
+[format]
+indent-style = "space"
+quote-style = "double"
+line-ending = "lf"

nk_python/ruff_runner.py

@@ -0,0 +1,34 @@
+"""Run Ruff in batches, optionally collecting its output for a check summary."""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+RUFF_CONFIG = Path(__file__).with_name("ruff.toml")
+
+
+def run_ruff(command: str, files: list[Path], *options: str, output: list[str] | None = None) -> int:
+    status = 0
+    for offset in range(0, len(files), 50):
+        batch = files[offset : offset + 50]
+        result = subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "ruff",
+                command,
+                "--config",
+                str(RUFF_CONFIG),
+                *options,
+                *(os.path.relpath(path) for path in batch),
+            ],
+            stdout=subprocess.PIPE if output is not None else None,
+            stderr=subprocess.STDOUT if output is not None else None,
+            text=True,
+            check=False,
+        )
+        if output is not None:
+            output.append(result.stdout)
+        status = max(status, result.returncode)
+    return status

nk_python/structure_checks.py

@@ -0,0 +1,53 @@
+"""Collect Python files and check direct file counts in each directory."""
+
+import os
+from fnmatch import fnmatchcase
+from pathlib import Path
+
+from .model import Issue
+
+IGNORED_DIRECTORIES = {
+    ".git",
+    ".hg",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".tox",
+    ".venv*",
+    "venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "node_modules",
+}
+SUFFIXES = {".py", ".pyi"}
+
+
+def discover(paths: list[Path], max_files: int = 8) -> tuple[list[Path], list[Issue]]:
+    files: set[Path] = set()
+    issues: list[Issue] = []
+    seen_directories: set[Path] = set()
+    for target in paths:
+        target = target.resolve()
+        if not target.exists():
+            raise FileNotFoundError(target)
+        if target.is_file():
+            if target.suffix not in SUFFIXES:
+                raise ValueError(f"Unsupported source file: {target}")
+            files.add(target)
+            continue
+        for root, directory_names, file_names in os.walk(target):
+            directory_names[:] = sorted(
+                name
+                for name in directory_names
+                if not any(fnmatchcase(name, pattern) for pattern in IGNORED_DIRECTORIES)
+            )
+            directory = Path(root).resolve()
+            source_names = sorted(name for name in file_names if Path(name).suffix in SUFFIXES)
+            files.update(directory / name for name in source_names)
+            if directory not in seen_directories and len(source_names) > max_files:
+                issues.append(
+                    Issue(directory, 1, "PY008", f"Directory has {len(source_names)} Python files (max {max_files}).")
+                )
+            seen_directories.add(directory)
+    return sorted(files), sorted(issues)

nk_python_style-0.1.0.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: nk-python-style
+Version: 0.1.0
+Summary: Python formatter and linter following the repository's conventions
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: ruff<1,>=0.16
+Provides-Extra: comments
+Requires-Dist: lingua-language-detector<3,>=2.2; extra == "comments"
+
+# Python : linter et formatter
+
+Cette version garde les limites générales du projet C++ et confie les règles Python courantes à Ruff. Elle utilise l'AST et `tokenize` pour distinguer code, chaînes, docstrings et commentaires.
+
+## Installation
+
+Depuis ce dépôt :
+
+```bash
+python -m pip install -e ./python
+```
+
+Pour activer la détection de la langue des commentaires, installer l'extra optionnel (Lingua est volumineux) :
+
+```bash
+python -m pip install -e "./python[comments]"
+```
+
+Depuis un autre projet, une installation non éditable fonctionne aussi : `python -m pip install <chemin-vers-ce-dépôt>/python`. La commande `nk-python` est ensuite disponible dans le même environnement Python. On peut également utiliser `python -m nk_python`.
+
+## Utilisation
+
+```bash
+nk-python check Src Tests              # Ruff et règles propres, sans écriture
+nk-python format Src Tests             # trie les imports et formate en place
+nk-python check fichier.py            # fichier précis
+nk-python check . --max-files 10       # seuil de dossier personnalisé
+```
+
+Sans chemin, la commande traite le dossier courant. Les sous-dossiers de cache, d'environnement virtuel et de construction sont ignorés. Cela inclut tous les dossiers dont le nom commence par `.venv`, comme `.venv-cardd` et `.venv-vision`. `check` contrôle **aussi** le formatage Ruff et retourne un code non nul si une règle échoue. `format` applique le tri des imports Ruff et `ruff format`; relancer `check` pour les diagnostics qui ne se corrigent pas automatiquement.
+
+Les diagnostics s'affichent sans extraits de code, avec des chemins relatifs au dossier courant.
+La sortie de `check` commence par un résumé : fichiers analysés, nombre de warnings du linter (Ruff et règles `PY…`), problèmes d'ordre des imports et fichiers à reformater. Elle présente ensuite les diagnostics du linter, puis une section formatter à la fin : ordre des imports et fichiers à reformater. Cette dernière correspond aux corrections appliquées par `format`. Les autres corrections automatiques proposées par Ruff ne sont pas appliquées par cette commande.
+
+## Règles
+
+| Code | Contrôle |
+| --- | --- |
+| `PY001` | Ligne de 120 caractères maximum, commentaires compris. |
+| `PY002` | Fichier de 120 lignes maximum. |
+| `PY003` | Fonction ou méthode de 40 lignes maximum, signature comprise. |
+| `PY004` | Cinq paramètres maximum ; `self` ou `cls` est exclu pour les méthodes. |
+| `PY005` | Commentaire de fin de ligne interdit, sauf directive d'outil. |
+| `PY006` | Commentaire dans une fonction interdit, sauf directive d'outil ; utiliser une docstring ou clarifier le code. |
+| `PY007` | Commentaire qui semble non anglais ; actif si l'extra `comments` est installé. Les textes trop courts ou ambigus sont ignorés. |
+| `PY008` | Huit fichiers `.py`/`.pyi` directs maximum dans un dossier parcouru. |
+
+Ruff vérifie en plus les erreurs Python (`E4`, `E7`, `E9`, `F`), l'ordre des imports (`I`), les erreurs fréquentes (`B`), certaines modernisations sûres (`UP`) et la variable créée uniquement pour être retournée (`RET504`). Sa configuration est fournie par l'outil, donc les mêmes règles s'appliquent depuis un autre projet. Le formatter impose une indentation de quatre espaces, des guillemets doubles et des fins de ligne LF. Les règles C++ propres aux accolades, `#include`, modules et initialiseurs désignés ne s'appliquent pas à Python.
+
+Les directives usuelles (`# noqa`, `# type: ignore`, `# pylint:`, `# fmt:`, `# ruff:`, `# isort:` et `# pragma: no cover`) restent permises. Les docstrings ne sont pas des commentaires `#` et restent autorisées dans les fonctions.

nk_python_style-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+nk_python/__init__.py,sha256=Bzh-uQ6uWnIE5R-1opQqMpR6NfWELL4XjX2y_nR46qc,74
+nk_python/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+nk_python/ast_checks.py,sha256=auhtwbCkcdzU0FmBwI_NOAMIZ6SPtdlpvbsV4s_mmNs,3139
+nk_python/cli.py,sha256=4wL23RUARVZBz8sfsJ7z-LKFLoR2G6LOHw_41giS7Mg,4217
+nk_python/comment_checks.py,sha256=GDJ0QzlbGLp5ulQ6cgnM_5ixpCkbG8EFeK7DixvVnCM,3051
+nk_python/model.py,sha256=qSwiwnbXA4eWGkReSe74QBq_L2YJM6yVkd-g-AjNjLg,298
+nk_python/ruff.toml,sha256=dkjak3D4VS6hnGcKXzDaqQ5CpA723Xbp7lEDV7Y5cYI,320
+nk_python/ruff_runner.py,sha256=v_aLQVajD56Z51exlVvmUlLXOgJOSDfBZmD93dcbcd4,1053
+nk_python/structure_checks.py,sha256=HCbm_g01i0g3vzGl_cDZu0tcMsoMKtjtj-DZVx-tqAw,1748
+nk_python_style-0.1.0.dist-info/METADATA,sha256=rdKc_ry8CHQcmkh7W4-r_gFDp-naS5WNFydGVBAyLhM,4056
+nk_python_style-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+nk_python_style-0.1.0.dist-info/entry_points.txt,sha256=rjz1wN9VFSj7FcgYsnWZxqoIk-UpzyfMx-_t7U39Rnc,49
+nk_python_style-0.1.0.dist-info/top_level.txt,sha256=pGStA10dDoyVVsTrGpFRzp_cSnrOWUDP4ZNeEfWTd8E,10
+nk_python_style-0.1.0.dist-info/RECORD,,

nk_python_style-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nk_python_style-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nk-python = nk_python.cli:main

nk_python_style-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nk_python