graphlens-python 0.1.1__py3-none-any.whl

graphlens_python/__init__.py

@@ -0,0 +1,5 @@
+"""Python language adapter for graphlens."""
+
+from graphlens_python._adapter import PythonAdapter
+
+__all__ = ["PythonAdapter"]

graphlens_python/_adapter.py

@@ -0,0 +1,291 @@
+"""PythonAdapter — orchestrates Python project analysis."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from graphlens import (
+    GraphLens,
+    LanguageAdapter,
+    Node,
+    NodeKind,
+    Relation,
+    RelationKind,
+)
+from graphlens.utils import make_node_id
+
+from graphlens_python._deps import (
+    PYTHON_DEFAULT_DEP_PARSERS,
+    get_stdlib_names,
+)
+from graphlens_python._module_resolver import (
+    file_to_qualified_name,
+    find_source_roots,
+)
+from graphlens_python._project_detector import (
+    detect_project_name,
+    find_python_roots,
+    is_python_project,
+)
+from graphlens_python._visitor import (
+    ImportClassifier,
+    PythonASTVisitor,
+    VisitorContext,
+    parse_python,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from graphlens.contracts import DependencyFileParser
+
+logger = logging.getLogger("graphlens_python")
+
+_STDLIB = get_stdlib_names()
+
+
+class PythonAdapter(LanguageAdapter):
+    """Language adapter for Python projects."""
+
+    def __init__(
+        self,
+        dep_parsers: list[DependencyFileParser] | None = None,
+    ) -> None:
+        """
+        Initialize the Python adapter.
+
+        Args:
+            dep_parsers: parsers used to extract third-party dependency
+                names from manifest files (pyproject.toml,
+                requirements.txt, etc.). Pass a custom list to support
+                non-standard package managers (poetry-only setup,
+                pip-tools, pnpm, etc.).
+                Defaults to ``PYTHON_DEFAULT_DEP_PARSERS``.
+
+        """
+        self._dep_parsers = (
+            dep_parsers
+            if dep_parsers is not None
+            else PYTHON_DEFAULT_DEP_PARSERS
+        )
+
+    def language(self) -> str:
+        return "python"
+
+    def file_extensions(self) -> set[str]:
+        return {".py", ".pyi"}
+
+    def can_handle(self, project_root: Path) -> bool:
+        return is_python_project(project_root)
+
+    def analyze(
+        self,
+        project_root: Path,
+        files: list[Path] | None = None,
+    ) -> GraphLens:
+        graph = GraphLens()
+
+        if files is not None:
+            _analyze_root(
+                graph,
+                project_root,
+                project_root,
+                files,
+                self._dep_parsers,
+            )
+        else:
+            for py_root in find_python_roots(project_root):
+                root_files = self.collect_files(py_root)
+                _analyze_root(
+                    graph,
+                    project_root,
+                    py_root,
+                    root_files,
+                    self._dep_parsers,
+                )
+
+        return graph
+
+
+def _analyze_root(
+    graph: GraphLens,
+    project_root: Path,
+    py_root: Path,
+    files: list[Path],
+    dep_parsers: list[DependencyFileParser],
+) -> None:
+    """Analyze one Python project root and populate graph in-place."""
+    project_name = detect_project_name(py_root)
+    source_roots = find_source_roots(py_root, files)
+
+    # --- Pre-pass: collect all internal module top-level names ---------------
+    # Derive module qnames from file paths without parsing source — so the
+    # ImportClassifier knows which imports are internal before visiting.
+    internal_tops: set[str] = set()
+    for f in files:
+        sr = _find_source_root_for(f, source_roots) or source_roots[0]
+        try:
+            qname = file_to_qualified_name(f, sr)
+            internal_tops.add(qname.split(".")[0])
+        except ValueError:
+            pass
+
+    # --- Third-party: parse dependency manifests ----------------------------
+    third_party: set[str] = set()
+    for parser in dep_parsers:
+        if parser.can_parse(py_root):
+            third_party.update(parser.parse(py_root))
+
+    classifier = ImportClassifier(
+        stdlib=_STDLIB,
+        third_party=frozenset(third_party),
+        internal=frozenset(internal_tops),
+    )
+
+    project_id = make_node_id(
+        project_name, project_name, NodeKind.PROJECT.value
+    )
+    if project_id not in graph.nodes:
+        graph.add_node(
+            Node(
+                id=project_id,
+                kind=NodeKind.PROJECT,
+                qualified_name=project_name,
+                name=project_name,
+            )
+        )
+
+    modules: dict[str, str] = {}
+
+    for file in files:
+        source_root = (
+            _find_source_root_for(file, source_roots) or source_roots[0]
+        )
+
+        try:
+            module_qname = file_to_qualified_name(file, source_root)
+        except ValueError:
+            logger.warning(
+                "Cannot compute qualified name for %s, skipping", file
+            )
+            continue
+
+        _ensure_module_chain(graph, project_name, module_qname, modules)
+
+        # FILE node — path stays relative to the original project_root so that
+        # all file paths in a monorepo share the same reference point.
+        try:
+            relative_path = str(file.relative_to(project_root))
+        except ValueError:
+            relative_path = str(file.relative_to(py_root))
+
+        file_id = make_node_id(
+            project_name, relative_path, NodeKind.FILE.value
+        )
+        if file_id not in graph.nodes:
+            graph.add_node(
+                Node(
+                    id=file_id,
+                    kind=NodeKind.FILE,
+                    qualified_name=relative_path,
+                    name=file.name,
+                    file_path=relative_path,
+                )
+            )
+            leaf_module_id = modules[module_qname]
+            graph.add_relation(
+                Relation(
+                    source_id=leaf_module_id,
+                    target_id=file_id,
+                    kind=RelationKind.CONTAINS,
+                )
+            )
+
+        try:
+            source_bytes = file.read_bytes()
+        except OSError as e:
+            logger.warning("Cannot read %s: %s — skipping", file, e)
+            continue
+
+        tree = parse_python(source_bytes)
+        if tree.root_node.has_error:
+            logger.warning(
+                "Parse errors in %s — continuing with partial results",
+                file,
+            )
+
+        ctx = VisitorContext(
+            project_name=project_name,
+            file_path=file,
+            source_root=source_root,
+            module_qualified_name=module_qname,
+        )
+        visitor = PythonASTVisitor(
+            ctx, graph, file_id, source_bytes, classifier
+        )
+        visitor.visit(tree.root_node)
+
+    # PROJECT --CONTAINS--> top-level modules
+    top_level = {qn: mid for qn, mid in modules.items() if "." not in qn}
+    for module_id in top_level.values():
+        graph.add_relation(
+            Relation(
+                source_id=project_id,
+                target_id=module_id,
+                kind=RelationKind.CONTAINS,
+            )
+        )
+
+
+def _find_source_root_for(file: Path, source_roots: list[Path]) -> Path | None:
+    for root in source_roots:
+        try:
+            file.relative_to(root)
+            return root
+        except ValueError:
+            continue
+    return None
+
+
+def _ensure_module_chain(
+    graph: GraphLens,
+    project_name: str,
+    module_qname: str,
+    modules: dict[str, str],
+) -> str:
+    """
+    Ensure MODULE nodes exist for the full chain a.b.c.
+
+    Returns the node ID of the leaf module.
+    Creates CONTAINS relations between parent and child modules.
+    """
+    parts = module_qname.split(".")
+    parent_id: str | None = None
+
+    for i in range(1, len(parts) + 1):
+        qname = ".".join(parts[:i])
+        if qname not in modules:
+            node_id = make_node_id(project_name, qname, NodeKind.MODULE.value)
+            graph.add_node(
+                Node(
+                    id=node_id,
+                    kind=NodeKind.MODULE,
+                    qualified_name=qname,
+                    name=parts[i - 1],
+                )
+            )
+            modules[qname] = node_id
+
+            if parent_id is not None:
+                graph.add_relation(
+                    Relation(
+                        source_id=parent_id,
+                        target_id=node_id,
+                        kind=RelationKind.CONTAINS,
+                    )
+                )
+
+        parent_id = modules[qname]
+
+    return modules[module_qname]

graphlens_python/_deps.py

@@ -0,0 +1,191 @@
+"""Dependency file parsers for Python projects."""
+
+from __future__ import annotations
+
+import configparser
+import re
+import sys
+from typing import TYPE_CHECKING
+
+import tomllib
+from graphlens.contracts import DependencyFileParser, normalize_pkg_name
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class PyprojectDepsParser(DependencyFileParser):
+    """
+    Reads declared dependencies from ``pyproject.toml``.
+
+    Supports:
+
+    - PEP 621: ``[project.dependencies]`` and
+      ``[project.optional-dependencies]``
+    - Poetry: ``[tool.poetry.dependencies]`` and
+      ``[tool.poetry.group.*.dependencies]``
+
+    Dev / test dependency groups are included so that test-only imports
+    (e.g. ``pytest``) are classified as ``third_party`` rather than
+    ``unknown``.
+    """
+
+    def can_parse(self, project_root: Path) -> bool:
+        return (project_root / "pyproject.toml").exists()
+
+    def parse(  # noqa: PLR0912
+        self, project_root: Path
+    ) -> frozenset[str]:
+        path = project_root / "pyproject.toml"
+        try:
+            with path.open("rb") as f:
+                data = tomllib.load(f)
+        except (tomllib.TOMLDecodeError, OSError):
+            return frozenset()
+
+        names: set[str] = set()
+
+        # PEP 621 -------------------------------------------------------
+        project = data.get("project", {})
+        for dep in project.get("dependencies", []):
+            n = normalize_pkg_name(dep)
+            if n:
+                names.add(n)
+        for group_deps in project.get("optional-dependencies", {}).values():
+            for dep in group_deps:
+                n = normalize_pkg_name(dep)
+                if n:
+                    names.add(n)
+
+        # Poetry --------------------------------------------------------
+        poetry = data.get("tool", {}).get("poetry", {})
+        for dep in poetry.get("dependencies", {}):
+            n = normalize_pkg_name(dep)
+            if n and n != "python":
+                names.add(n)
+        for dep in poetry.get("dev-dependencies", {}):
+            n = normalize_pkg_name(dep)
+            if n:
+                names.add(n)
+        # Poetry dependency groups (poetry >= 1.2)
+        for group in poetry.get("group", {}).values():
+            for dep in group.get("dependencies", {}):
+                n = normalize_pkg_name(dep)
+                if n:
+                    names.add(n)
+
+        return frozenset(names)
+
+
+class RequirementsTxtParser(DependencyFileParser):
+    """
+    Reads ``requirements*.txt`` files in the project root.
+
+    Handles:
+
+    - Plain package names: ``requests``
+    - Version specifiers: ``requests>=2.28``
+    - Extras: ``requests[security]``
+    - URL / VCS requirements: skipped (no importable name can be reliably
+      extracted)
+    - ``-r other.txt`` recursive includes: followed one level deep
+    - Inline comments: stripped
+    """
+
+    # Matches lines that are URL or VCS requirements (skip them)
+    _SKIP_RE = re.compile(r"^\s*(-r|-c|-e|https?://|git\+|svn\+|hg\+|bzr\+)")
+
+    def can_parse(self, project_root: Path) -> bool:
+        return any(project_root.glob("requirements*.txt"))
+
+    def parse(self, project_root: Path) -> frozenset[str]:
+        names: set[str] = set()
+        for req_file in sorted(project_root.glob("requirements*.txt")):
+            self._parse_file(req_file, names, project_root)
+        return frozenset(names)
+
+    def _parse_file(self, path: Path, names: set[str], root: Path) -> None:
+        try:
+            lines = path.read_text(encoding="utf-8").splitlines()
+        except OSError:
+            return
+        for raw in lines:
+            line = raw.strip()
+            if not line or line.startswith("#"):
+                continue
+            if self._SKIP_RE.match(line):
+                # Follow -r includes one level deep
+                if line.startswith("-r"):
+                    ref = line[2:].strip()
+                    ref_path = root / ref
+                    if ref_path.exists():
+                        self._parse_file(ref_path, names, root)
+                continue
+            n = normalize_pkg_name(line)
+            if n:
+                names.add(n)
+
+
+class SetupCfgDepsParser(DependencyFileParser):
+    """Reads ``[options] install_requires`` from ``setup.cfg``."""
+
+    def can_parse(self, project_root: Path) -> bool:
+        return (project_root / "setup.cfg").exists()
+
+    def parse(self, project_root: Path) -> frozenset[str]:
+        path = project_root / "setup.cfg"
+        cfg = configparser.ConfigParser()
+        try:
+            cfg.read(path, encoding="utf-8")
+        except (configparser.Error, OSError):
+            return frozenset()
+
+        names: set[str] = set()
+        raw = cfg.get("options", "install_requires", fallback="")
+        for line in raw.splitlines():
+            n = normalize_pkg_name(line)
+            if n:
+                names.add(n)
+        # extras_require
+        for section in cfg.sections():
+            if section.startswith("options.extras_require"):
+                raw_extras = cfg.get(
+                    section, "install_requires", fallback=""
+                )
+                for line in raw_extras.splitlines():
+                    n = normalize_pkg_name(line)
+                    if n:
+                        names.add(n)
+        return frozenset(names)
+
+
+# ---------------------------------------------------------------------------
+# Default parser list for PythonAdapter
+# ---------------------------------------------------------------------------
+
+PYTHON_DEFAULT_DEP_PARSERS: list[DependencyFileParser] = [
+    PyprojectDepsParser(),
+    RequirementsTxtParser(),
+    SetupCfgDepsParser(),
+]
+
+
+# ---------------------------------------------------------------------------
+# Stdlib set (Python 3.10+)
+# ---------------------------------------------------------------------------
+
+def get_stdlib_names() -> frozenset[str]:
+    """Return stdlib top-level module names for the running Python."""
+    # sys.stdlib_module_names is available from Python 3.10
+    stdlib: set[str] = set(getattr(sys, "stdlib_module_names", set()))
+    # Add a minimal hardcoded set as fallback for older Pythons
+    stdlib.update({
+        "abc", "ast", "asyncio", "builtins", "collections", "contextlib",
+        "copy", "dataclasses", "datetime", "enum", "functools", "hashlib",
+        "importlib", "inspect", "io", "itertools", "json", "logging",
+        "math", "operator", "os", "pathlib", "pickle", "re", "shutil",
+        "signal", "socket", "string", "struct", "subprocess", "sys",
+        "tempfile", "threading", "time", "tomllib", "traceback", "typing",
+        "unittest", "urllib", "uuid", "warnings", "weakref",
+    })
+    return frozenset(stdlib)

graphlens_python/_module_resolver.py

@@ -0,0 +1,87 @@
+"""Module qualified name resolution and source root detection."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def find_source_roots(project_root: Path, files: list[Path]) -> list[Path]:
+    """
+    Detect Python source roots.
+
+    Checks for src/ layout first. Falls back to project root.
+    """
+    src = project_root / "src"
+    if (
+        src.is_dir()
+        and any(files)
+        and any(f.is_relative_to(src) for f in files)
+    ):
+        return [src]
+    return [project_root]
+
+
+def file_to_qualified_name(file_path: Path, source_root: Path) -> str:
+    """
+    Convert a file path to a dotted Python qualified module name.
+
+    Examples:
+      src/mypackage/__init__.py  ->  "mypackage"
+      src/mypackage/utils.py     ->  "mypackage.utils"
+      src/mypackage/sub/__init__.py -> "mypackage.sub"
+
+    """
+    relative = file_path.relative_to(source_root)
+    parts = list(relative.parts)
+
+    # Strip .py / .pyi extension from last part
+    stem = Path(parts[-1]).stem
+    parts[-1] = stem
+
+    # For __init__, the module is the package itself (drop __init__)
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+
+    if not parts:
+        # Top-level __init__.py with no parent — use the source root name
+        return source_root.name
+
+    return ".".join(parts)
+
+
+def is_package_init(file_path: Path) -> bool:
+    """Return True if the file is __init__.py or __init__.pyi."""
+    return file_path.name in ("__init__.py", "__init__.pyi")
+
+
+def resolve_relative_import(
+    current_module_qname: str,
+    level: int,
+    module: str | None,
+) -> str:
+    """
+    Resolve a relative import to an absolute qualified name.
+
+    Args:
+        current_module_qname: e.g. ``'mypackage.sub.mod'`` or
+            ``'mypackage'`` (for __init__)
+        level: number of leading dots (1 = current package,
+            2 = parent package, etc.)
+        module: the module part, e.g. ``'utils'`` in
+            ``'from ..utils import x'``. Can be None.
+
+    The current module's *package* is all parts except the last.
+    For level=1: base = current package (drop last part of
+    current_module_qname if it's not a package __init__).
+    For level=2: go one more level up, etc.
+
+    """
+    parts = current_module_qname.split(".")
+    # The package is everything except the module name itself.
+    # We go up `level` levels from the current module's package.
+    # parts[:-1] = current package. Then go up (level - 1) more.
+    base_parts = parts[: max(0, len(parts) - level)]
+
+    if module:
+        return ".".join([*base_parts, module]) if base_parts else module
+    return ".".join(base_parts) if base_parts else ""