~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
#!/usr/bin/env python3
"""
Pre-commit hook to enforce using pathlib.Path instead of os.path.
This hook checks for os.path usage in Python files and suggests
using pathlib.Path instead for better cross-platform compatibility
and more modern Python code.
"""
import argparse
import ast
import sys
from pathlib import Path
class OsPathChecker(ast.NodeVisitor):
"""AST visitor to find os.path usage."""
def __init__(self, filename: str):
self.filename = filename
self.violations: list[tuple[int, str]] = []
# Local names bound to the ``os`` module. Includes aliases from
# ``import os as <alias>`` so they cannot bypass the check.
self.os_module_names: set[str] = set()
# Local names bound directly to ``os.path`` by
# ``from os import path [as <alias>]``.
self.os_path_names: set[str] = set()
self.has_os_path_import = False
def visit_Import(self, node: ast.Import) -> None:
"""Check for 'import os' statements (incl. ``import os as <alias>``)."""
for alias in node.names:
if alias.name == "os":
self.os_module_names.add(alias.asname or "os")
self.generic_visit(node)
def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
"""Check for 'from os import path' or 'from os.path import ...' statements."""
if node.module == "os" and any(
alias.name == "path" for alias in node.names
):
for alias in node.names:
if alias.name == "path":
self.os_path_names.add(alias.asname or "path")
self.has_os_path_import = True
self.violations.append(
(
node.lineno,
"Found 'from os import path' - use 'from pathlib import Path' instead",
)
)
elif node.module == "os.path":
self.has_os_path_import = True
imported_names = [alias.name for alias in node.names]
self.violations.append(
(
node.lineno,
f"Found 'from os.path import {', '.join(imported_names)}' - use pathlib.Path methods instead",
)
)
self.generic_visit(node)
def visit_Attribute(self, node: ast.Attribute) -> None:
"""Check for os.path.* usage."""
if (
isinstance(node.value, ast.Name)
and node.value.id in self.os_module_names
and node.attr == "path"
):
# This is os.path usage
# Try to get the specific method being called
parent = getattr(node, "parent", None)
if parent and isinstance(parent, ast.Attribute):
method = parent.attr
# Skip os.path.expandvars as it has no pathlib equivalent
if method == "expandvars":
return
suggestion = get_pathlib_equivalent(f"os.path.{method}")
else:
suggestion = "Use pathlib.Path instead"
self.violations.append(
(node.lineno, f"Found os.path usage - {suggestion}")
)
self.generic_visit(node)
def _get_os_path_call_method(self, func: ast.AST) -> str | None:
"""Return the os.path method name for recognized call forms."""
if not isinstance(func, ast.Attribute):
return None
# os.path.join(...) or _os.path.join(...)
if (
isinstance(func.value, ast.Attribute)
and isinstance(func.value.value, ast.Name)
and func.value.value.id in self.os_module_names
and func.value.attr == "path"
):
return func.attr
# path.join(...) or _path.join(...) from
# ``from os import path [as _path]``.
if (
isinstance(func.value, ast.Name)
and func.value.id in self.os_path_names
):
return func.attr
return None
def visit_Call(self, node: ast.Call) -> None:
"""Check for direct calls to os.path functions."""
method = self._get_os_path_call_method(node.func)
if method is not None:
if method != "expandvars":
suggestion = get_pathlib_equivalent(f"os.path.{method}")
self.violations.append(
(
node.lineno,
f"Found os.path.{method}() - {suggestion}",
)
)
# Do not visit node.func here; visit_Attribute would otherwise
# report the same os.path.<method>(...) call a second time.
for arg in node.args:
self.visit(arg)
for keyword in node.keywords:
self.visit(keyword.value)
return
self.generic_visit(node)
def get_pathlib_equivalent(os_path_call: str) -> str:
"""Get the pathlib equivalent for common os.path operations."""
equivalents = {
"os.path.join": "Use Path() / 'subpath' or Path().joinpath()",
"os.path.exists": "Use Path().exists()",
"os.path.isfile": "Use Path().is_file()",
"os.path.isdir": "Use Path().is_dir()",
"os.path.dirname": "Use Path().parent",
"os.path.basename": "Use Path().name",
"os.path.abspath": "Use Path().resolve()",
"os.path.realpath": "Use Path().resolve()",
"os.path.expanduser": "Use Path().expanduser()",
"os.path.split": "Use Path().parent and Path().name",
"os.path.splitext": "Use Path().stem and Path().suffix",
"os.path.getsize": "Use Path().stat().st_size",
"os.path.getmtime": "Use Path().stat().st_mtime",
"os.path.normpath": "Use Path() - it normalizes automatically",
# Note: os.path.expandvars has no pathlib equivalent and is allowed
"os.path.expandvars": "(No pathlib equivalent - allowed)",
}
return equivalents.get(os_path_call, "Use pathlib.Path equivalent method")
def check_file(
filepath: Path, allow_legacy: bool = False
) -> list[tuple[str, int, str]]:
"""
Check a Python file for os.path usage.
Args:
filepath: Path to the Python file to check
allow_legacy: If True, only check modified lines (not implemented yet)
Returns:
List of (filename, line_number, violation_message) tuples
"""
try:
content = filepath.read_text(encoding="utf-8")
tree = ast.parse(content, filename=str(filepath))
except SyntaxError as e:
print(f"Syntax error in {filepath}: {e}", file=sys.stderr)
return []
except Exception as e:
print(f"Error reading {filepath}: {e}", file=sys.stderr)
return []
checker = OsPathChecker(str(filepath))
checker.visit(tree)
return [(str(filepath), line, msg) for line, msg in checker.violations]
def main() -> int:
"""Main entry point for the pre-commit hook."""
parser = argparse.ArgumentParser(
description="Check for os.path usage and suggest pathlib alternatives"
)
parser.add_argument(
"filenames",
nargs="*",
help="Python files to check",
)
parser.add_argument(
"--allow-legacy",
action="store_true",
help="Allow os.path in existing code (only check new/modified lines)",
)
args = parser.parse_args()
# List of files that are allowed to use os.path (legacy or special cases)
ALLOWED_FILES = {
"src/local_deep_research/utilities/log_utils.py", # May need os.path for low-level operations
"src/local_deep_research/config/paths.py", # Already migrated but may have legacy code
".pre-commit-hooks/check-pathlib-usage.py", # This file itself
}
violations = []
for filename in args.filenames:
filepath = Path(filename)
# Skip non-Python files
if not filename.endswith(".py"):
continue
# Skip allowed files
if any(filename.endswith(allowed) for allowed in ALLOWED_FILES):
continue
file_violations = check_file(filepath, args.allow_legacy)
violations.extend(file_violations)
if violations:
print("\n❌ Found os.path usage - please use pathlib.Path instead:\n")
for filename, line, message in violations:
print(f" {filename}:{line}: {message}")
print(
"\n💡 Tip: pathlib.Path provides a more modern and cross-platform API."
)
print(
" Example: Path('dir') / 'file.txt' instead of os.path.join('dir', 'file.txt')"
)
print(
"\n📚 See https://docs.python.org/3/library/pathlib.html for more information.\n"
)
return 1
return 0
if __name__ == "__main__":
sys.exit(main())