threadcheck 0.0.1.1__py3-none-win_amd64.whl

threadcheck/__init__.py

@@ -0,0 +1,14 @@
+"""
+threadcheck — Data-race detector for multi-threaded Python.
+
+Supports both AST-based static analysis and runtime dynamic
+detection via bytecode instrumentation.
+
+Targets Python 3.14+ free-threading builds.
+"""
+
+from ._version import __version__
+
+from .static.analyzer import analyze_path, analyze_file
+from .static.models import RaceWarning, Severity, WarningCategory
+from .compat import check_compat, FTCompatResult, CompatStatus

threadcheck/__main__.py

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

threadcheck/_tid.py

@@ -0,0 +1,5 @@
+import threading
+
+
+def current_tid() -> int:
+    return threading.get_ident()

threadcheck/_version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1.1"

threadcheck/cli.py

@@ -0,0 +1,213 @@
+import argparse
+import json as _json
+import re
+import sys
+from pathlib import Path
+
+from ._version import __version__
+from .static.analyzer import analyze_path
+from .reporting.formatter import format_report, format_warnings_json
+from .reporting.sarif import format_sarif
+from .dynamic.__main__ import run_script
+from .compat import check_compat
+from .compat.models import CompatStatus
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="threadcheck",
+        description="Data Race Detector for Python",
+    )
+
+    parser.add_argument(
+        "--version", action="version", version=f"threadcheck {__version__}"
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    scan = sub.add_parser("scan", help="Static analysis for data races")
+    scan.add_argument("path", help="File or directory to scan")
+    fmt = scan.add_mutually_exclusive_group()
+    fmt.add_argument("--json", action="store_true", help="Output in JSON format")
+    fmt.add_argument("--sarif", action="store_true", help="Output in SARIF v2.1.0 format")
+    scan.add_argument("-o", "--output", help="Write output to file (default: stdout)")
+
+    run = sub.add_parser("run", help="Dynamic race detection")
+    run.add_argument("script", help="Python script to execute")
+    run_fmt = run.add_mutually_exclusive_group()
+    run_fmt.add_argument("--json", action="store_true", help="Output in JSON format")
+    run.add_argument("-o", "--output", help="Write output to file (default: stdout)")
+
+    compat = sub.add_parser("compat", help="Check free-threading compatibility")
+    compat.add_argument("path", nargs="?", default=".", help="Project path")
+    compat.add_argument("--json", action="store_true", help="Output in JSON format")
+
+    args = parser.parse_args()
+
+    if args.command == "scan":
+        _do_scan(args)
+    elif args.command == "run":
+        _do_run(args)
+    elif args.command == "compat":
+        _do_compat(args)
+
+
+def _detect_format(output_path: str | None) -> str:
+    if output_path:
+        ext = Path(output_path).suffix.lower()
+        if ext == ".json":
+            return "json"
+        if ext == ".sarif":
+            return "sarif"
+    return "text"
+
+
+def _do_scan(args):
+    path = Path(args.path).resolve()
+    if not path.exists():
+        print(f"Path does not exist: {path}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"threadcheck scan -- analysing {path}")
+    print()
+
+    warnings = analyze_path(str(path))
+
+    fmt = _detect_format(args.output)
+    if args.json:
+        fmt = "json"
+    elif args.sarif:
+        fmt = "sarif"
+
+    if fmt == "json":
+        output = format_warnings_json(warnings)
+        _write_output(args.output, output)
+    elif fmt == "sarif":
+        output = format_sarif(warnings)
+        _write_output(args.output, output)
+    else:
+        text = format_report(warnings)
+        _write_output(args.output, text)
+
+    total = len(warnings)
+    errors = sum(1 for w in warnings if w.severity.value == "error")
+    warns = sum(1 for w in warnings if w.severity.value == "warning")
+    infos = sum(1 for w in warnings if w.severity.value == "info")
+    print()
+    print(f"Total: {total} issue(s) ({errors} error(s), {warns} warning(s), {infos} info)")
+
+
+def _do_run(args):
+    fmt = "json" if args.json else _detect_format(args.output)
+    run_script(args.script, output_format=fmt)
+
+
+def _do_compat(args):
+    path = Path(args.path).resolve()
+    names: list[str] | None = None
+    toml = path / "pyproject.toml"
+    req = path / "requirements.txt"
+    if path.is_dir() and toml.is_file():
+        names = _read_deps_from_pyproject(toml)
+    elif path.is_file() and path.suffix == ".txt":
+        names = _read_deps_from_requirements(path)
+    elif path.is_file() and path.name == "pyproject.toml":
+        names = _read_deps_from_pyproject(path)
+
+    results = check_compat(names)
+
+    if args.json:
+        obj = [r.to_dict() for r in results]
+        print(_json.dumps(obj, indent=2, ensure_ascii=False))
+        return
+
+    print(f"threadcheck compat - Free-threading compatibility check")
+    print(f"Python {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")
+    print()
+
+    can_emoji = _can_print_emoji()
+    for r in results:
+        if r.status.value == "compatible":
+            icon = _icon("✅", "[OK]", can_emoji)
+        elif r.status.value == "needs_verification":
+            icon = _icon("⚠️", "[??]", can_emoji)
+        else:
+            icon = _icon("❌", "[--]", can_emoji)
+        print(f"  {icon}  {r.name:<20} {r.reason}")
+
+    print()
+    total = len(results)
+    compat_count = sum(1 for r in results if r.status == CompatStatus.COMPATIBLE)
+    needs_v = sum(1 for r in results if r.status == CompatStatus.NEEDS_VERIFICATION)
+    not_inst = sum(1 for r in results if r.status == CompatStatus.NOT_INSTALLED)
+    print(f"Total: {total} package(s) - {compat_count} compatible, {needs_v} need verification, {not_inst} not installed")
+
+
+def _read_deps_from_pyproject(path: Path) -> list[str]:
+    try:
+        import tomllib
+    except ImportError:
+        return []
+
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return []
+
+    deps: list[str] = []
+    for key in ("dependencies", "optional-dependencies"):
+        section = data.get("project", {}).get(key, {})
+        if isinstance(section, dict):
+            for group in section.values():
+                deps.extend(_extract_names(group))
+        elif isinstance(section, list):
+            deps.extend(_extract_names(section))
+    return sorted(set(deps))
+
+
+def _read_deps_from_requirements(path: Path) -> list[str]:
+    names: list[str] = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith(("#", "-", "git+", "http")):
+            continue
+        name = re.split(r"[<>=!~@;]", line, maxsplit=1)[0].strip()
+        if name:
+            names.append(name)
+    return sorted(set(names))
+
+
+def _extract_names(entries: list) -> list[str]:
+    import re as _re
+
+    names: list[str] = []
+    for entry in entries:
+        if not isinstance(entry, str):
+            continue
+        name = _re.split(r"[<>=!~@;]", entry, maxsplit=1)[0].strip()
+        if name:
+            names.append(name)
+    return names
+
+
+def _can_print_emoji() -> bool:
+    try:
+        "\u2705".encode(sys.stdout.encoding)
+        return True
+    except (UnicodeEncodeError, UnicodeDecodeError, AttributeError):
+        return False
+
+
+def _icon(emoji: str, fallback: str, can_emoji: bool) -> str:
+    return emoji if can_emoji else fallback
+
+
+def _write_output(path_arg: str | None, content: str):
+    if path_arg:
+        Path(path_arg).write_text(content, encoding="utf-8")
+    else:
+        print(content)
+
+
+if __name__ == "__main__":
+    main()

threadcheck/compat/__init__.py

@@ -0,0 +1,4 @@
+from .checker import check_compat
+from .models import FTCompatResult, CompatStatus, CExtInfo
+
+__all__ = ["check_compat", "FTCompatResult", "CompatStatus", "CExtInfo"]

threadcheck/compat/checker.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from .models import CExtInfo, CompatStatus, FTCompatResult
+
+_C_EXT_RE = re.compile(r"\.(pyd|so)$", re.IGNORECASE)
+_FT_TAG_RE = re.compile(r"\.(cp\d+t|cpython-\d+t)-")
+
+
+def _check_single(name: str) -> FTCompatResult:
+    try:
+        from importlib.metadata import PackageNotFoundError, distribution
+    except ImportError:
+        return FTCompatResult(
+            name=name,
+            status=CompatStatus.NOT_INSTALLED,
+            reason="importlib.metadata not available",
+        )
+
+    try:
+        dist = distribution(name)
+    except PackageNotFoundError:
+        return FTCompatResult(
+            name=name,
+            status=CompatStatus.NOT_INSTALLED,
+            reason="not installed",
+        )
+    except Exception as exc:
+        return FTCompatResult(
+            name=name,
+            status=CompatStatus.NOT_INSTALLED,
+            reason=str(exc),
+        )
+
+    c_exts: list[CExtInfo] = []
+    try:
+        files = dist.files or []
+    except Exception:
+        files = []
+
+    for f in files:
+        fname = str(f)
+        if not _C_EXT_RE.search(fname):
+            continue
+        c_exts.append(
+            CExtInfo(filename=fname, has_ft_tag=bool(_FT_TAG_RE.search(fname)))
+        )
+
+    if not c_exts:
+        return FTCompatResult(
+            name=name,
+            status=CompatStatus.COMPATIBLE,
+            reason="pure Python, no C extensions",
+        )
+
+    ft_missing = [e for e in c_exts if not e.has_ft_tag]
+    if ft_missing:
+        return FTCompatResult(
+            name=name,
+            status=CompatStatus.NEEDS_VERIFICATION,
+            c_exts=c_exts,
+            reason=f"{len(ft_missing)} C extension(s) not compiled for free-threading ABI",
+        )
+
+    return FTCompatResult(
+        name=name,
+        status=CompatStatus.COMPATIBLE,
+        c_exts=c_exts,
+        reason="all C extensions compiled for free-threading ABI",
+    )
+
+
+def check_compat(
+    names: Sequence[str] | None = None,
+) -> list[FTCompatResult]:
+    if names is not None:
+        return [_check_single(n) for n in names]
+
+    try:
+        from importlib.metadata import distributions
+    except ImportError:
+        return []
+
+    results: list[FTCompatResult] = []
+    for dist in distributions():
+        name = dist.metadata.get("Name", "")
+        if name:
+            results.append(_check_single(name))
+
+    results.sort(key=lambda r: r.name.lower())
+    return results

threadcheck/compat/models.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class CompatStatus(Enum):
+    COMPATIBLE = "compatible"
+    NEEDS_VERIFICATION = "needs_verification"
+    NOT_INSTALLED = "not_installed"
+
+
+@dataclass
+class CExtInfo:
+    filename: str
+    has_ft_tag: bool
+
+    @property
+    def tag(self) -> str:
+        match = re.search(r"\.(cpython-\d+t?|cp\d+t?)-", self.filename)
+        if match:
+            return match.group(1)
+        return ""
+
+
+@dataclass
+class FTCompatResult:
+    name: str
+    status: CompatStatus
+    c_exts: list[CExtInfo] = field(default_factory=list)
+    reason: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "status": self.status.value,
+            "c_exts": [{"filename": e.filename, "has_ft_tag": e.has_ft_tag} for e in self.c_exts],
+            "reason": self.reason,
+        }

threadcheck/dynamic/__main__.py

@@ -0,0 +1,47 @@
+import ast
+import sys
+from pathlib import Path
+
+from .tracker import ThreadCheckTracker
+from .transform import TrackInjector
+from ..reporting.formatter import format_dynamic_races, format_dynamic_json
+
+
+def run_script(script_path: str, output_format: str = "text"):
+    path = Path(script_path).resolve()
+    if not path.exists():
+        print(f"File not found: {path}", file=sys.stderr)
+        sys.exit(1)
+
+    source = path.read_text(encoding="utf-8")
+    filename = str(path)
+
+    try:
+        tree = ast.parse(source, filename=filename)
+    except SyntaxError as e:
+        print(f"Syntax error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    TrackInjector(filename=filename).transform(tree)
+    ast.fix_missing_locations(tree)
+
+    code = compile(tree, filename, "exec")
+
+    ThreadCheckTracker.start()
+    try:
+        exec(code, {"_threadcheck_tracker": ThreadCheckTracker, "__file__": filename})
+    except SystemExit:
+        pass
+    finally:
+        ThreadCheckTracker.stop()
+
+    races = ThreadCheckTracker.detect_races()
+    with ThreadCheckTracker._lock:
+        alog = dict(ThreadCheckTracker._access_log)
+
+    if output_format == "json":
+        print(format_dynamic_json(races))
+    else:
+        print(format_dynamic_races(races, alog))
+
+    ThreadCheckTracker.reset()

threadcheck/dynamic/clock.py

@@ -0,0 +1,31 @@
+from collections import defaultdict
+
+
+class VectorClock:
+    def __init__(self):
+        self._clock: dict[int, int] = defaultdict(int)
+
+    def tick(self, thread_id: int) -> int:
+        self._clock[thread_id] += 1
+        return self._clock[thread_id]
+
+    def merge(self, other: "VectorClock"):
+        for k, v in other._clock.items():
+            self._clock[k] = max(self._clock.get(k, 0), v)
+
+    def conflicts_with(self, other: "VectorClock") -> bool:
+        return not (self._leq(other) or other._leq(self))
+
+    def _leq(self, other: "VectorClock") -> bool:
+        for k, v in self._clock.items():
+            if v > other._clock.get(k, 0):
+                return False
+        return True
+
+    def copy(self) -> "VectorClock":
+        vc = VectorClock()
+        vc._clock = self._clock.copy()
+        return vc
+
+    def __repr__(self) -> str:
+        return f"VectorClock({dict(self._clock)})"

threadcheck/dynamic/hook.py

@@ -0,0 +1,97 @@
+import sys
+import ast
+import builtins
+import importlib.util
+import importlib.abc
+from pathlib import Path
+
+from .transform import TrackInjector
+from .tracker import ThreadCheckTracker
+
+
+class ThreadCheckLoader(importlib.abc.Loader):
+    def __init__(self, tracker=None):
+        self.tracker = tracker or ThreadCheckTracker
+
+    def create_module(self, spec):
+        return None
+
+    def exec_module(self, module):
+        spec = module.__spec__
+        source = self._get_source(spec, module)
+        if source is None:
+            raise ImportError(f"cannot load source for {spec.name}")
+
+        module.__file__ = spec.origin
+
+        tree = ast.parse(source, filename=spec.origin)
+        TrackInjector(filename=str(spec.origin)).transform(tree)
+        ast.fix_missing_locations(tree)
+
+        code = compile(tree, spec.origin, "exec")
+        globals_dict = module.__dict__
+        globals_dict["_threadcheck_tracker"] = self.tracker
+        builtins._threadcheck_tracker = self.tracker
+        exec(code, globals_dict)
+
+    @staticmethod
+    def _get_source(spec, module=None):
+        for candidate in (spec.origin, getattr(module, "__file__", None)):
+            if candidate and Path(candidate).suffix == ".py":
+                try:
+                    return Path(candidate).read_text(encoding="utf-8")
+                except Exception:
+                    pass
+        if hasattr(spec.loader, "get_source"):
+            try:
+                return spec.loader.get_source(spec.name)
+            except Exception:
+                pass
+        return None
+
+
+class ThreadCheckFinder(importlib.abc.MetaPathFinder):
+    def __init__(self, tracker=None, include_paths=None):
+        self.tracker = tracker or ThreadCheckTracker
+        self._include_paths = (
+            [Path(p).resolve() for p in include_paths] if include_paths else []
+        )
+
+    def _should_instrument(self, filepath: Path) -> bool:
+        if not self._include_paths:
+            return True
+        resolved = filepath.resolve()
+        return any(_is_under(resolved, inc) for inc in self._include_paths)
+
+    def find_spec(self, fullname, path, target=None):
+        for entry in (path or sys.path):
+            if entry == "":
+                entry = "."
+            base = Path(entry) / f"{fullname.replace('.', '/')}.py"
+            if base.exists() and self._should_instrument(base):
+                spec = importlib.util.spec_from_file_location(
+                    fullname,
+                    str(base),
+                    loader=ThreadCheckLoader(self.tracker),
+                )
+                return spec
+        return None
+
+
+def install_hook(tracker=None, include_paths=None):
+    hook = ThreadCheckFinder(tracker, include_paths)
+    sys.meta_path.insert(0, hook)
+    return hook
+
+
+def uninstall_hook(hook):
+    if hook in sys.meta_path:
+        sys.meta_path.remove(hook)
+
+
+def _is_under(child: Path, parent: Path) -> bool:
+    try:
+        child.relative_to(parent)
+        return True
+    except ValueError:
+        return False