vscode-common-python-lsp 0.1.0__py3-none-any.whl

vscode_common_python_lsp/__init__.py

@@ -0,0 +1,137 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+"""Shared Python utilities for VS Code Python tool extensions."""
+
+from .code_actions import (
+    QuickFixRegistrationError,
+    QuickFixRegistry,
+    command_quick_fix,
+    create_workspace_edit,
+)
+from .context import change_cwd, redirect_io, substitute_attr
+from .debug import setup_debugpy
+from .diagnostics import (
+    ParsedRecord,
+    get_severity,
+    make_diagnostic,
+    parse_diagnostics_regex,
+    parse_to_records,
+    records_to_diagnostics,
+)
+from .formatting import (
+    NOTEBOOK_CELL_SCHEME,
+    is_notebook_cell,
+    match_line_endings,
+    strip_trailing_newline,
+)
+from .jsonrpc import (
+    JsonRpc,
+    RpcRunResult,
+    StreamClosedException,
+    get_or_start_json_rpc,
+    run_over_json_rpc,
+    shutdown_json_rpc,
+)
+from .linting import LintRequestTracker
+from .notebook import (
+    MAGIC_LINE_RE,
+    NOTEBOOK_SYNC_OPTIONS,
+    CellLike,
+    CellOffset,
+    SyntheticDocument,
+    build_notebook_source,
+    get_cell_for_line,
+    remap_diagnostics_to_cells,
+)
+from .paths import (
+    CWD_LOCK,
+    SERVER_CWD,
+    PythonFileKind,
+    as_list,
+    classify_python_file,
+    get_extensions_dir,
+    get_relative_path,
+    get_sys_config_paths,
+    is_current_interpreter,
+    is_match,
+    is_same_path,
+    normalize_path,
+)
+from .process_runner import run_message_loop, update_sys_path
+from .runner import CustomIO, RunResult, run_api, run_module, run_path
+from .server import ToolServer, ToolServerConfig
+from .version import VersionInfo, check_min_version, extract_version, version_to_tuple
+
+__all__ = [
+    # paths
+    "SERVER_CWD",
+    "CWD_LOCK",
+    "as_list",
+    "get_sys_config_paths",
+    "get_extensions_dir",
+    "get_relative_path",
+    "normalize_path",
+    "is_same_path",
+    "is_current_interpreter",
+    "classify_python_file",
+    "PythonFileKind",
+    "is_match",
+    # context
+    "substitute_attr",
+    "redirect_io",
+    "change_cwd",
+    # runner
+    "RunResult",
+    "CustomIO",
+    "run_module",
+    "run_path",
+    "run_api",
+    # jsonrpc
+    "StreamClosedException",
+    "JsonRpc",
+    "RpcRunResult",
+    "get_or_start_json_rpc",
+    "run_over_json_rpc",
+    "shutdown_json_rpc",
+    # process_runner
+    "update_sys_path",
+    "run_message_loop",
+    # debug
+    "setup_debugpy",
+    # server
+    "ToolServerConfig",
+    "ToolServer",
+    # code_actions
+    "QuickFixRegistrationError",
+    "QuickFixRegistry",
+    "command_quick_fix",
+    "create_workspace_edit",
+    # diagnostics
+    "ParsedRecord",
+    "get_severity",
+    "make_diagnostic",
+    "parse_diagnostics_regex",
+    "parse_to_records",
+    "records_to_diagnostics",
+    # formatting
+    "NOTEBOOK_CELL_SCHEME",
+    "match_line_endings",
+    "is_notebook_cell",
+    "strip_trailing_newline",
+    # linting
+    "LintRequestTracker",
+    # notebook
+    "CellLike",
+    "SyntheticDocument",
+    "CellOffset",
+    "MAGIC_LINE_RE",
+    "NOTEBOOK_SYNC_OPTIONS",
+    "build_notebook_source",
+    "get_cell_for_line",
+    "remap_diagnostics_to_cells",
+    # version
+    "VersionInfo",
+    "extract_version",
+    "check_min_version",
+    "version_to_tuple",
+]

vscode_common_python_lsp/code_actions.py

@@ -0,0 +1,131 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+"""Code action helpers shared by Python tool extensions.
+
+Provides:
+* :class:`QuickFixRegistry` — decorator-based registry for quick-fix
+  code actions (shared by flake8 and pylint).
+* :func:`command_quick_fix` — build a command-based
+  :class:`lsprotocol.types.CodeAction`.
+* :func:`create_workspace_edit` — build a
+  :class:`lsprotocol.types.WorkspaceEdit` for a single document.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import lsprotocol.types as lsp
+
+# ---------------------------------------------------------------------------
+# QuickFix registry
+# ---------------------------------------------------------------------------
+
+
+class QuickFixRegistrationError(Exception):
+    """Raised when a quick-fix code is registered more than once."""
+
+    def __init__(self, code: str) -> None:
+        super().__init__(f"Quick fix already registered for code: {code!r}")
+        self.code = code
+
+
+class QuickFixRegistry:
+    """Manages quick fixes registered using the :meth:`quick_fix` decorator.
+
+    Usage::
+
+        QUICK_FIXES = QuickFixRegistry()
+
+        @QUICK_FIXES.quick_fix(codes=["E226", "E227"])
+        def fix_format(document, diagnostics):
+            return [command_quick_fix(...)]
+    """
+
+    def __init__(self) -> None:
+        self._solutions: dict[
+            str,
+            Callable[[Any, list[lsp.Diagnostic]], list[lsp.CodeAction]],
+        ] = {}
+
+    def quick_fix(
+        self,
+        codes: str | list[str],
+    ) -> Callable[..., Any]:
+        """Decorator for registering quick fixes for one or more codes."""
+
+        def decorator(
+            func: Callable[[Any, list[lsp.Diagnostic]], list[lsp.CodeAction]],
+        ) -> Callable[[Any, list[lsp.Diagnostic]], list[lsp.CodeAction]]:
+            if isinstance(codes, str):
+                if codes in self._solutions:
+                    raise QuickFixRegistrationError(codes)
+                self._solutions[codes] = func
+            else:
+                for code in codes:
+                    if code in self._solutions:
+                        raise QuickFixRegistrationError(code)
+                for code in codes:
+                    self._solutions[code] = func
+            return func
+
+        return decorator
+
+    def solutions(
+        self,
+        code: str | None,
+    ) -> Callable[[Any, list[lsp.Diagnostic]], list[lsp.CodeAction]] | None:
+        """Return the quick-fix handler for *code*, or *None*."""
+        if code is None:
+            return None
+        return self._solutions.get(code)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def command_quick_fix(
+    diagnostics: list[lsp.Diagnostic],
+    title: str,
+    command: str,
+    args: list[Any] | None = None,
+) -> lsp.CodeAction:
+    """Build a command-based :class:`CodeAction`."""
+    return lsp.CodeAction(
+        title=title,
+        kind=lsp.CodeActionKind.QuickFix,
+        diagnostics=diagnostics,
+        command=lsp.Command(title=title, command=command, arguments=args),
+    )
+
+
+def create_workspace_edit(
+    document_uri: str,
+    document_version: int | None,
+    text_edits: list[lsp.TextEdit],
+) -> lsp.WorkspaceEdit:
+    """Build a :class:`WorkspaceEdit` for a single document.
+
+    Parameters
+    ----------
+    document_uri:
+        The document's URI.
+    document_version:
+        The document's version (``None`` → 0 per LSP convention).
+    text_edits:
+        The edits to apply.
+    """
+    return lsp.WorkspaceEdit(
+        document_changes=[
+            lsp.TextDocumentEdit(
+                text_document=lsp.OptionalVersionedTextDocumentIdentifier(
+                    uri=document_uri,
+                    version=document_version if document_version is not None else 0,
+                ),
+                edits=text_edits,
+            )
+        ],
+    )

vscode_common_python_lsp/context.py

@@ -0,0 +1,61 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+"""Context managers for use with running tools over LSP."""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+import sys
+from collections.abc import Iterator
+from typing import Any
+
+from .paths import SERVER_CWD
+
+
+@contextlib.contextmanager
+def substitute_attr(obj: object, attribute: str, new_value: Any) -> Iterator[None]:
+    """Manage object attributes context when using runpy.run_module()."""
+    old_value = getattr(obj, attribute)
+    setattr(obj, attribute, new_value)
+    try:
+        yield
+    finally:
+        setattr(obj, attribute, old_value)
+
+
+@contextlib.contextmanager
+def redirect_io(stream: str, new_stream: Any) -> Iterator[None]:
+    """Redirect stdio streams to a custom stream."""
+    old_stream = getattr(sys, stream)
+    setattr(sys, stream, new_stream)
+    try:
+        yield
+    finally:
+        setattr(sys, stream, old_stream)
+
+
+@contextlib.contextmanager
+def change_cwd(new_cwd: str) -> Iterator[None]:
+    """Change working directory before running code.
+
+    Always restores to ``SERVER_CWD`` (the working directory at process
+    start), not the working directory active when the context manager was
+    entered.  This matches the behaviour of all upstream extension repos.
+    """
+    try:
+        os.chdir(new_cwd)
+    except OSError as e:
+        logging.warning(
+            "Failed to change directory to %r, running in %r instead: %s",
+            new_cwd,
+            SERVER_CWD,
+            e,
+        )
+        yield
+        return
+    try:
+        yield
+    finally:
+        os.chdir(SERVER_CWD)

vscode_common_python_lsp/debug.py

@@ -0,0 +1,49 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+"""Debugging support for LSP."""
+
+from __future__ import annotations
+
+import os
+import pathlib
+
+from .process_runner import update_sys_path
+
+
+def setup_debugpy(port: int = 5678, *, require_opt_in: bool = True) -> None:
+    """Conditionally attach debugpy if the environment is configured.
+
+    Checks the ``DEBUGPY_PATH`` environment variable and, when present,
+    loads debugpy from that path and connects to the given *port*.
+
+    Parameters
+    ----------
+    port:
+        The port to connect to for debugging.
+    require_opt_in:
+        When ``True`` (default), the ``USE_DEBUGPY`` environment variable
+        must also be set to a truthy value (``True``, ``TRUE``, ``1``, or
+        ``T``).  Set to ``False`` to skip this check — useful for
+        extensions that don't gate on ``USE_DEBUGPY`` (e.g. flake8, mypy).
+    """
+    if require_opt_in and os.getenv("USE_DEBUGPY", None) not in (
+        "True",
+        "TRUE",
+        "1",
+        "T",
+    ):
+        return
+
+    debugger_path = os.getenv("DEBUGPY_PATH", None)
+    if not debugger_path:
+        return
+
+    if pathlib.Path(debugger_path).name == "debugpy":
+        debugger_path = os.fspath(pathlib.Path(debugger_path).parent)
+
+    update_sys_path(debugger_path, "fromEnvironment")
+
+    import debugpy  # noqa: E402
+
+    debugpy.connect(port)
+    debugpy.breakpoint()

vscode_common_python_lsp/diagnostics.py

@@ -0,0 +1,275 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+"""Diagnostic construction and parsing helpers for LSP tool extensions.
+
+Provides:
+* Severity resolution shared by flake8, isort, mypy and pylint.
+* A generic regex-based diagnostic parser used by flake8 and mypy (with
+  a file-aware callback to support mypy's multi-file output).
+* A helper to build individual :class:`lsprotocol.types.Diagnostic` objects.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import re
+from collections.abc import Callable
+from typing import Any
+
+import lsprotocol.types as lsp
+
+# ---------------------------------------------------------------------------
+# Severity resolution
+# ---------------------------------------------------------------------------
+
+
+def get_severity(
+    code: str,
+    code_type: str,
+    severity_map: dict[str, str],
+    *,
+    default: str = "Error",
+    symbol: str | None = None,
+) -> lsp.DiagnosticSeverity:
+    """Resolve an LSP :class:`DiagnosticSeverity` from tool output.
+
+    Lookup order (matching pylint's most-expressive pattern):
+    ``symbol`` → ``code`` → ``code_type`` → *default*.
+
+    Parameters
+    ----------
+    code:
+        Machine-readable error code (e.g. ``"E501"``, ``"C0301"``).
+    code_type:
+        Category/type string (e.g. ``"Error"``, ``"convention"``).
+    severity_map:
+        User-configurable mapping of codes/types → severity names.
+    default:
+        Fallback severity name when nothing matches.
+    symbol:
+        Optional symbolic name (e.g. ``"line-too-long"``).  Only pylint
+        exposes this; other tools pass *None*.
+    """
+    value = (
+        (symbol and severity_map.get(symbol))
+        or severity_map.get(code, None)
+        or severity_map.get(code_type, None)
+        or default
+    )
+    try:
+        return lsp.DiagnosticSeverity[value]
+    except KeyError:
+        return lsp.DiagnosticSeverity.Error
+
+
+# ---------------------------------------------------------------------------
+# Diagnostic construction
+# ---------------------------------------------------------------------------
+
+
+def make_diagnostic(
+    *,
+    line: int,
+    column: int,
+    message: str,
+    severity: lsp.DiagnosticSeverity,
+    code: str = "",
+    source: str = "",
+    end_line: int | None = None,
+    end_column: int | None = None,
+    code_description: lsp.CodeDescription | None = None,
+    data: Any = None,
+) -> lsp.Diagnostic:
+    """Build an :class:`lsprotocol.types.Diagnostic`.
+
+    *line* and *column* are **0-based** (LSP convention).  If *end_line*
+    or *end_column* are *None* the range degenerates to a point.
+    """
+    start = lsp.Position(line=line, character=column)
+    end = lsp.Position(
+        line=end_line if end_line is not None else line,
+        character=end_column if end_column is not None else column,
+    )
+    return lsp.Diagnostic(
+        range=lsp.Range(start=start, end=end),
+        message=message,
+        severity=severity,
+        code=code or None,
+        code_description=code_description,
+        source=source or None,
+        data=data,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Regex-based diagnostic parsing
+# ---------------------------------------------------------------------------
+
+
+@dataclasses.dataclass(slots=True)
+class ParsedRecord:
+    """Intermediate representation of a single parsed diagnostic line.
+
+    Provides typed access to the regex-matched groups before they are
+    turned into :class:`lsprotocol.types.Diagnostic` objects.
+    """
+
+    file: str = ""
+    line: int = 0
+    column: int = 0
+    code: str = ""
+    code_type: str = ""
+    message: str = ""
+
+
+def parse_to_records(
+    content: str,
+    pattern: re.Pattern[str],
+    *,
+    line_at_1: bool = True,
+    col_at_1: bool = True,
+) -> list[ParsedRecord]:
+    """Parse tool output into :class:`ParsedRecord` instances.
+
+    This is the first stage of the two-stage parsing pipeline.  Use
+    :func:`records_to_diagnostics` to convert the records into LSP
+    diagnostics, or process them directly for custom handling (e.g. mypy
+    note-chaining).
+
+    The *pattern* uses ``re.match`` semantics (anchored at the start of
+    each line).  If your tool output may contain leading whitespace or
+    prefixes, account for that in the pattern.
+
+    Lines where the ``line`` named group is missing or not parseable as an
+    integer are skipped.
+    """
+    records: list[ParsedRecord] = []
+    line_offset = 1 if line_at_1 else 0
+    col_offset = 1 if col_at_1 else 0
+
+    for line in content.splitlines():
+        match = pattern.match(line)
+        if not match:
+            continue
+
+        data = match.groupdict()
+        line_value = data.get("line")
+        if not line_value:
+            continue
+
+        try:
+            parsed_line = int(line_value)
+        except ValueError:
+            continue
+
+        records.append(
+            ParsedRecord(
+                file=data.get("file") or "",
+                line=max(parsed_line - line_offset, 0),
+                column=max(int(data.get("column") or "1") - col_offset, 0),
+                code=data.get("code") or "",
+                code_type=data.get("type") or "",
+                message=data.get("message") or "",
+            )
+        )
+
+    return records
+
+
+def records_to_diagnostics(
+    records: list[ParsedRecord],
+    severity_map: dict[str, str],
+    source: str,
+    *,
+    default_severity: str = "Error",
+) -> list[lsp.Diagnostic]:
+    """Convert :class:`ParsedRecord` instances into LSP diagnostics.
+
+    This is the second stage of the two-stage parsing pipeline.
+    """
+    diagnostics: list[lsp.Diagnostic] = []
+    for record in records:
+        severity = get_severity(
+            record.code,
+            record.code_type,
+            severity_map,
+            default=default_severity,
+        )
+        diagnostics.append(
+            make_diagnostic(
+                line=record.line,
+                column=record.column,
+                message=record.message,
+                severity=severity,
+                code=record.code,
+                source=source,
+            )
+        )
+    return diagnostics
+
+
+def parse_diagnostics_regex(
+    content: str,
+    pattern: re.Pattern[str],
+    severity_map: dict[str, str],
+    source: str,
+    *,
+    line_at_1: bool = True,
+    col_at_1: bool = True,
+    default_severity: str = "Error",
+    record_callback: Callable[[ParsedRecord], lsp.Diagnostic | None] | None = None,
+) -> list[lsp.Diagnostic]:
+    """Parse tool output into diagnostics using a compiled regex.
+
+    The *pattern* must use **named groups** and ``re.match`` semantics
+    (anchored at the start of each line).  If your tool output may contain
+    leading whitespace or prefixes, account for that in the pattern.
+
+    Required named groups:
+
+    * ``line`` — 1-based line number (lines without a valid integer are
+      skipped)
+
+    Optional named groups:
+
+    * ``column`` — 1-based column number
+    * ``type`` — severity category (``Error``, ``Warning``, …)
+    * ``code`` — machine-readable code
+    * ``message`` — human-readable message
+    * ``file`` — file path (for multi-file output like mypy)
+
+    Parameters
+    ----------
+    content:
+        Raw tool stdout to parse.
+    pattern:
+        Compiled regex with named groups.
+    severity_map:
+        User severity overrides.
+    source:
+        Value for :attr:`Diagnostic.source` (e.g. ``"Flake8"``).
+    line_at_1:
+        Whether the tool's line numbers are 1-based (subtract 1 for LSP).
+    col_at_1:
+        Whether the tool's column numbers are 1-based.
+    default_severity:
+        Fallback severity when neither code nor type matches.
+    record_callback:
+        Optional callback that receives each :class:`ParsedRecord` and
+        returns a :class:`Diagnostic` (or *None* to skip).  When provided
+        the default diagnostic construction is bypassed — use this for
+        tools like mypy that need note-chaining or custom ranges.
+    """
+    records = parse_to_records(content, pattern, line_at_1=line_at_1, col_at_1=col_at_1)
+
+    if record_callback is not None:
+        diagnostics: list[lsp.Diagnostic] = []
+        for record in records:
+            diag = record_callback(record)
+            if diag is not None:
+                diagnostics.append(diag)
+        return diagnostics
+
+    return records_to_diagnostics(
+        records, severity_map, source, default_severity=default_severity
+    )

vscode_common_python_lsp/formatting.py

@@ -0,0 +1,48 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+"""Formatting helpers shared by Python tool extensions."""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+NOTEBOOK_CELL_SCHEME = "vscode-notebook-cell"
+
+
+def _get_line_endings(lines: list[str]) -> str | None:
+    """Detect the dominant line ending in *lines*.
+
+    Returns ``"\\r\\n"`` or ``"\\n"`` (or *None* when indeterminate).
+    """
+    crlf = sum(1 for line in lines if line.endswith("\r\n"))
+    lf = sum(1 for line in lines if line.endswith("\n") and not line.endswith("\r\n"))
+    if crlf == 0 and lf == 0:
+        return None
+    return "\r\n" if crlf > lf else "\n"
+
+
+def match_line_endings(document_source: str, edited_text: str) -> str:
+    """Ensure *edited_text* uses the same line endings as *document_source*.
+
+    This is identical across all 5 extension repos and prevents spurious
+    diffs when the tool normalises line endings differently from the editor.
+    """
+    expected = _get_line_endings(document_source.splitlines(keepends=True))
+    actual = _get_line_endings(edited_text.splitlines(keepends=True))
+    if actual == expected or actual is None or expected is None:
+        return edited_text
+    return edited_text.replace(actual, expected)
+
+
+def is_notebook_cell(uri: str) -> bool:
+    """Return *True* if *uri* refers to a notebook cell."""
+    return urlparse(uri).scheme == NOTEBOOK_CELL_SCHEME
+
+
+def strip_trailing_newline(text: str) -> str:
+    """Strip a single trailing newline (for notebook cell formatting)."""
+    if text.endswith("\r\n"):
+        return text[:-2]
+    if text.endswith("\n"):
+        return text[:-1]
+    return text