transformers-mlinter 0.1.0__py3-none-any.whl

mlinter/__init__.py

@@ -0,0 +1,105 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Supported public API for transformers-mlinter.
+
+Import public helpers from ``mlinter`` instead of implementation modules such as
+``mlinter.mlinter`` or ``mlinter._helpers``.
+"""
+
+from ._helpers import (
+    MODELS_ROOT,
+    Violation,
+    full_name,
+    is_self_method_call,
+    is_super_method_call,
+    iter_pretrained_classes,
+)
+from ._helpers import (
+    _collect_class_bases as collect_class_bases,
+)
+from ._helpers import (
+    _has_rule_suppression as has_rule_suppression,
+)
+from ._helpers import (
+    _inherits_pretrained_model as inherits_pretrained_model,
+)
+from ._helpers import (
+    _model_dir_name as model_dir_name,
+)
+from ._version import __version__
+from .mlinter import (
+    DEFAULT_ENABLED_TRF_RULES,
+    TRF_MODEL_DIR_ALLOWLISTS,
+    TRF_RULE_CHECKS,
+    TRF_RULE_SPECS,
+    TRF_RULES,
+    analyze_file,
+    colored_error_message,
+    emit_violation,
+    format_rule_details,
+    format_rule_summary,
+    format_violation,
+    get_changed_modeling_files,
+    iter_modeling_files,
+    main,
+    maybe_handle_rule_docs_cli,
+    parse_args,
+    render_rules_reference,
+    resolve_enabled_rules,
+    should_show_progress,
+)
+from .mlinter import (
+    _is_rule_allowlisted_for_file as is_rule_allowlisted_for_file,
+)
+
+
+__all__ = [
+    "DEFAULT_ENABLED_TRF_RULES",
+    "MODELS_ROOT",
+    "TRF_MODEL_DIR_ALLOWLISTS",
+    "TRF_RULE_CHECKS",
+    "TRF_RULE_SPECS",
+    "TRF_RULES",
+    "Violation",
+    "__version__",
+    "analyze_file",
+    "collect_class_bases",
+    "colored_error_message",
+    "emit_violation",
+    "format_rule_details",
+    "format_rule_summary",
+    "format_violation",
+    "full_name",
+    "get_changed_modeling_files",
+    "has_rule_suppression",
+    "inherits_pretrained_model",
+    "is_rule_allowlisted_for_file",
+    "is_self_method_call",
+    "is_super_method_call",
+    "iter_modeling_files",
+    "iter_pretrained_classes",
+    "main",
+    "maybe_handle_rule_docs_cli",
+    "model_dir_name",
+    "parse_args",
+    "render_rules_reference",
+    "resolve_enabled_rules",
+    "should_show_progress",
+]
+
+for rule_id in sorted(TRF_RULE_CHECKS):
+    globals()[rule_id] = rule_id
+    __all__.append(rule_id)
+del rule_id

mlinter/__main__.py

@@ -0,0 +1,18 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from . import main
+
+
+raise SystemExit(main())

mlinter/_helpers.py

@@ -0,0 +1,194 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shared AST helper functions used across mlinter rule modules."""
+
+import ast
+from dataclasses import dataclass
+from pathlib import Path
+
+
+MODELS_ROOT = Path("src/transformers/models")
+
+
+@dataclass(frozen=True)
+class Violation:
+    file_path: Path
+    line_number: int
+    message: str
+    rule_id: str | None = None
+
+
+def full_name(node: ast.AST):
+    """Return full dotted name from an Attribute or Name node."""
+    if isinstance(node, ast.Name):
+        return node.id
+    elif isinstance(node, ast.Attribute):
+        return full_name(node.value) + "." + node.attr
+    else:
+        raise ValueError("Not a Name or Attribute node")
+
+
+def _simple_name(name: str) -> str:
+    return name.split(".")[-1]
+
+
+def _model_dir_name(file_path: Path) -> str | None:
+    try:
+        relative = file_path.resolve().relative_to(MODELS_ROOT.resolve())
+    except ValueError:
+        try:
+            relative = file_path.relative_to(MODELS_ROOT)
+        except ValueError:
+            return None
+    if len(relative.parts) < 2:
+        return None
+    return relative.parts[0]
+
+
+def _known_model_dirs() -> set[str]:
+    return {path.name for path in MODELS_ROOT.iterdir() if path.is_dir()}
+
+
+def _has_rule_suppression(lines: list[str], rule_id: str, line_number: int) -> bool:
+    if line_number <= 0:
+        return False
+    token = f"trf-ignore: {rule_id}".lower()
+    candidate_indexes = (line_number - 1, line_number - 2)
+    for idx in candidate_indexes:
+        if 0 <= idx < len(lines) and token in lines[idx].lower():
+            return True
+    return False
+
+
+def _collect_class_bases(tree: ast.Module) -> dict[str, list[str]]:
+    class_to_bases: dict[str, list[str]] = {}
+    for node in tree.body:
+        if not isinstance(node, ast.ClassDef):
+            continue
+        base_names = []
+        for base in node.bases:
+            try:
+                base_names.append(full_name(base))
+            except ValueError:
+                continue
+        class_to_bases[node.name] = base_names
+    return class_to_bases
+
+
+def _inherits_pretrained_model(
+    class_name: str, class_to_bases: dict[str, list[str]], visiting: set[str] | None = None
+) -> bool:
+    if visiting is None:
+        visiting = set()
+    if class_name in visiting:
+        return False
+    visiting.add(class_name)
+
+    for base_name in class_to_bases.get(class_name, []):
+        simple_base_name = _simple_name(base_name)
+        if simple_base_name.endswith("PreTrainedModel"):
+            return True
+        if simple_base_name in class_to_bases and _inherits_pretrained_model(
+            simple_base_name, class_to_bases, visiting
+        ):
+            return True
+    return False
+
+
+def iter_pretrained_classes(tree: ast.Module, source_lines: list[str], rule_id: str) -> list[ast.ClassDef]:
+    """Yield ClassDef nodes that inherit from PreTrainedModel (transitively), skipping suppressed ones."""
+    class_to_bases = _collect_class_bases(tree)
+    results = []
+    for node in tree.body:
+        if not isinstance(node, ast.ClassDef):
+            continue
+        if not _inherits_pretrained_model(node.name, class_to_bases):
+            continue
+        if _has_rule_suppression(source_lines, rule_id, node.lineno):
+            continue
+        results.append(node)
+    return results
+
+
+def _get_class_assignments(class_node: ast.ClassDef) -> dict[str, ast.AST]:
+    assignments: dict[str, ast.AST] = {}
+    for item in class_node.body:
+        if isinstance(item, ast.Assign) and len(item.targets) == 1 and isinstance(item.targets[0], ast.Name):
+            assignments[item.targets[0].id] = item.value
+        elif isinstance(item, ast.AnnAssign) and isinstance(item.target, ast.Name) and item.value is not None:
+            assignments[item.target.id] = item.value
+    return assignments
+
+
+def _class_methods(class_node: ast.ClassDef) -> dict[str, ast.FunctionDef]:
+    return {item.name: item for item in class_node.body if isinstance(item, ast.FunctionDef)}
+
+
+def _function_argument_names(function_node: ast.FunctionDef) -> set[str]:
+    names = {arg.arg for arg in function_node.args.args}
+    names.update(arg.arg for arg in function_node.args.kwonlyargs)
+    if function_node.args.vararg is not None:
+        names.add(function_node.args.vararg.arg)
+    if function_node.args.kwarg is not None:
+        names.add(function_node.args.kwarg.arg)
+    return names
+
+
+def _function_uses_name(function_node: ast.FunctionDef, name: str) -> bool:
+    return any(
+        isinstance(node, ast.Name) and node.id == name and isinstance(node.ctx, ast.Load)
+        for node in ast.walk(function_node)
+    )
+
+
+def is_self_method_call(node: ast.AST, method: str) -> bool:
+    """Check if `node` is a method call on `self`, such as `self.method(...)`"""
+    return (
+        isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Attribute)
+        and isinstance(node.func.value, ast.Name)
+        and node.func.value.id == "self"
+        and node.func.attr == method
+    )
+
+
+def is_super_method_call(node: ast.AST, method: str) -> bool:
+    """Check if `node` is a call to `super().method(...)`"""
+    return (
+        isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Attribute)
+        and isinstance(node.func.value, ast.Call)
+        and isinstance(node.func.value.func, ast.Name)
+        and node.func.value.func.id == "super"
+        and node.func.attr == method
+    )
+
+
+def _is_direct_pretrained_config_subclass(class_node: ast.ClassDef) -> bool:
+    for base in class_node.bases:
+        try:
+            if _simple_name(full_name(base)) in {"PreTrainedConfig", "PretrainedConfig"}:
+                return True
+        except ValueError:
+            continue
+    return False
+
+
+def _has_strict_decorator(class_node: ast.ClassDef) -> bool:
+    for decorator in class_node.decorator_list:
+        if isinstance(decorator, ast.Name) and decorator.id == "strict":
+            return True
+
+    return False

mlinter/_version.py

@@ -0,0 +1,127 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+import subprocess
+from importlib.metadata import PackageNotFoundError, distribution
+from pathlib import Path
+
+
+try:
+    import tomllib  # Python >= 3.11
+except ModuleNotFoundError:
+    import tomli as tomllib  # Python 3.10 fallback
+
+
+PACKAGE_NAME = "transformers-mlinter"
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_BASE_VERSION = "0.1.0"
+
+
+def _read_version_from_pyproject() -> str | None:
+    pyproject_path = PROJECT_ROOT / "pyproject.toml"
+    try:
+        data = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, OSError, tomllib.TOMLDecodeError):
+        return None
+
+    project = data.get("project")
+    if not isinstance(project, dict):
+        return None
+
+    version = project.get("version")
+    if not isinstance(version, str) or not version.strip():
+        return None
+    return version
+
+
+def _installed_distribution():
+    try:
+        return distribution(PACKAGE_NAME)
+    except PackageNotFoundError:
+        return None
+
+
+def _short_commit_id(commit_id: str | None) -> str | None:
+    if commit_id is None:
+        return None
+
+    commit_id = commit_id.strip()
+    if not commit_id:
+        return None
+    return commit_id[:7]
+
+
+def _read_git_hash_from_direct_url(dist) -> str | None:
+    if dist is None:
+        return None
+
+    direct_url = dist.read_text("direct_url.json")
+    if not direct_url:
+        return None
+
+    try:
+        direct_url_data = json.loads(direct_url)
+    except json.JSONDecodeError:
+        return None
+
+    vcs_info = direct_url_data.get("vcs_info")
+    if not isinstance(vcs_info, dict) or vcs_info.get("vcs") != "git":
+        return None
+
+    commit_id = vcs_info.get("commit_id")
+    if not isinstance(commit_id, str):
+        return None
+    return _short_commit_id(commit_id)
+
+
+def _read_git_hash_from_checkout() -> str | None:
+    if not (PROJECT_ROOT / ".git").exists():
+        return None
+
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(PROJECT_ROOT), "rev-parse", "--short", "HEAD"],
+            capture_output=True,
+            check=False,
+            text=True,
+        )
+    except OSError:
+        return None
+
+    if result.returncode != 0:
+        return None
+    return _short_commit_id(result.stdout)
+
+
+def _append_git_hash(base_version: str, git_hash: str | None) -> str:
+    if git_hash is None or "+" in base_version:
+        return base_version
+    return f"{base_version}+g{git_hash}"
+
+
+def _resolve_base_version(dist) -> str:
+    if dist is not None:
+        return dist.version
+    return _read_version_from_pyproject() or DEFAULT_BASE_VERSION
+
+
+def _resolve_version() -> str:
+    dist = _installed_distribution()
+    base_version = _resolve_base_version(dist)
+    git_hash = _read_git_hash_from_direct_url(dist) or _read_git_hash_from_checkout()
+    return _append_git_hash(base_version, git_hash)
+
+
+__version__ = _resolve_version()