pythonfaster 1.8.0__py3-none-any.whl

pythonfaster/__init__.py

@@ -0,0 +1,92 @@
+"""pythonfaster — zero-intrusion Python acceleration via Cython AOT compilation.
+
+Three things only:
+1. Import hook — transparently compiles .py → .so on import
+2. Type inference — int→longlong, float→double, range vars→longlong
+3. Object acceleration — cdef classes + cfunc methods + loop var typing
+
+Usage (global auto-activation — recommended)::
+
+    pip install pythonfaster
+    pythonfaster enable          # one-time, installs .pth, <1 second
+    # Done — all Python processes auto-accelerate projects with
+    # pyproject.toml / .git markers in the CWD tree.
+
+Usage (explicit, in code — per-project only)::
+
+    from pythonfaster import Config, install
+    install(Config(root="."))
+
+When using the explicit form, the .pth file is also auto-installed
+so that future Python processes benefit from global auto-activation
+without needing to run ``pythonfaster enable`` separately.
+"""
+__version__ = "1.8.0"
+
+__all__ = ["Config", "install"]
+
+_pth_installed = False
+
+
+def _maybe_autoinstall_pth() -> None:
+    """Best-effort: install .pth file on first explicit use of pythonfaster.
+
+    This runs once per process when the user accesses ``pythonfaster.Config``
+    or ``pythonfaster.install``.  If the .pth file is already present, this
+    is a single ``stat()`` call and returns immediately.
+    """
+    global _pth_installed
+    if _pth_installed:
+        return
+    _pth_installed = True
+    try:
+        import site
+        from pathlib import Path
+
+        content = "import pythonfaster._bootstrap\n"
+        # Check if already installed in any candidate directory.
+        candidate_dirs: list[Path] = []
+        if site.ENABLE_USER_SITE:
+            user_site = site.getusersitepackages()
+            if user_site:
+                candidate_dirs.append(Path(user_site))
+        for prefix in site.getsitepackages():
+            d = Path(prefix)
+            if d not in candidate_dirs:
+                candidate_dirs.append(d)
+
+        for d in candidate_dirs:
+            pth = d / "pythonfaster.pth"
+            if pth.exists():
+                return  # already installed somewhere
+
+        # Install to the first writable directory.
+        for d in candidate_dirs:
+            try:
+                d.mkdir(parents=True, exist_ok=True)
+                (d / "pythonfaster.pth").write_text(content, encoding="utf-8")
+                return
+            except (PermissionError, OSError):
+                continue
+    except Exception:
+        pass  # never break user's import
+
+
+def __getattr__(name):
+    """Lazy-load public API on first access.
+
+    Keeps ``import pythonfaster`` near-zero cost — essential because the
+    ``.pth`` bootstrap does ``import pythonfaster._bootstrap`` on every Python
+    startup.  Submodules (config, hook, cache, compiler) only load when
+    the user actually calls ``Config(...)`` or ``install(...)``.
+    Also auto-installs the .pth file on first explicit use.
+    """
+    if name == "Config":
+        _maybe_autoinstall_pth()
+        from .config import Config
+        return Config
+    if name == "install":
+        _maybe_autoinstall_pth()
+        from .hook import install
+        return install
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

pythonfaster/_bootstrap.py

@@ -0,0 +1,89 @@
+"""Auto-install hook on Python startup via .pth file.
+
+When a ``pythonfaster.pth`` file is present in a site-packages directory,
+the ``site`` module executes ``import pythonfaster._bootstrap`` during Python
+startup.  This module reads the global activation state and, if enabled,
+auto-detects the project root from the current working directory and
+installs the import hook — all before any user code runs.
+
+Safety guarantees:
+- Never raises — any failure silently aborts; Python starts normally.
+- Defaults to **enabled** when no state file exists (fresh install).
+- ``pythonfaster disable`` writes ``{"enabled": false}`` to explicitly turn off.
+- Respects ``PYTHONFASTER_DISABLE=1`` environment variable (fastest exit).
+- Does nothing when no project root is found (no pyproject.toml /
+  .git / pythonfaster.toml in the CWD or any parent directory).
+- The package ``__init__.py`` uses lazy ``__getattr__`` so importing
+  ``pythonfaster`` is near-zero cost — submodules load only on actual use.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+#: Re-export for convenience (used by _cli.py and tests).
+PTH_NAME = "pythonfaster.pth"
+PTH_CONTENT = "import pythonfaster._bootstrap\n"
+
+
+def _read_state_fast() -> dict:
+    """Read global state without importing pythonfaster.config.
+
+    Returns ``{"enabled": True, "mode": "all"}`` when no state file
+    exists (fresh install) — pythonfaster is on by default.  An explicit
+    ``{"enabled": false}`` written by ``pythonfaster disable`` turns it off.
+    """
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".config"
+    state_file = base / "pythonfaster" / "config.json"
+    try:
+        with open(state_file, "r", encoding="utf-8") as fh:
+            state = json.load(fh)
+        if isinstance(state, dict):
+            return state
+    except Exception:
+        pass
+    return {"enabled": True, "mode": "all"}
+
+
+def _bootstrap() -> None:
+    """Entry point called on every Python startup (via .pth import).
+
+    Designed to be as fast as possible when pythonfaster is disabled:
+    one env-var check + one file read, then return.
+    """
+    try:
+        # --- Fast exit #1: env var (no file I/O at all) ---
+        if os.environ.get("PYTHONFASTER_DISABLE") == "1":
+            return
+
+        # --- Fast exit #2: global state disabled (one file read) ---
+        state = _read_state_fast()
+        if not state.get("enabled"):
+            return
+
+        # --- Enabled: now we can afford the full import cost ---
+        from .config import find_project_root, load_config
+        from .hook import install
+
+        # Detect project root from current working directory.
+        root = find_project_root(Path.cwd())
+        if root is None:
+            return
+
+        # Load project-specific config (pythonfaster.toml / pyproject.toml).
+        config = load_config(root)
+        if not config.enabled:
+            return
+
+        # Install the import hook.
+        install(config)
+    except Exception:
+        # Never break Python startup.
+        pass
+
+
+# Execute on import (the .pth file does ``import pythonfaster._bootstrap``).
+_bootstrap()

pythonfaster/_cli.py

@@ -0,0 +1,232 @@
+"""pythonfaster CLI — global activation control.
+
+After ``pip install pythonfaster``, the state defaults to **enabled**.
+The only missing piece is the ``.pth`` file that triggers the
+bootstrap on every Python startup.  Run ``pythonfaster enable`` once
+to install it (takes <1 second) — then you're done forever.
+
+Usage::
+
+    pythonfaster enable       Install .pth file + ensure state is enabled (one-time setup).
+    pythonfaster disable      Disable auto-acceleration globally.
+    pythonfaster status        Show current activation state and .pth file location.
+    pythonfaster install-pth   (Re)install the .pth file into site-packages.
+    pythonfaster remove-pth    Remove the .pth file from all site-packages locations.
+
+After ``pythonfaster enable``, every Python process reads the state file on
+startup and auto-installs the import hook when a project root is detected.
+``pythonfaster disable`` flips the state to ``enabled: false`` (the .pth file
+stays installed so re-enabling is instant — just ``pythonfaster enable`` again).
+"""
+from __future__ import annotations
+
+import json
+import os
+import site
+import sys
+from pathlib import Path
+
+from .config import load_state, save_state, state_path
+
+#: Name of the .pth file to install.
+PTH_NAME = "pythonfaster.pth"
+
+#: Content of the .pth file — a single import line executed by ``site``.
+PTH_CONTENT = "import pythonfaster._bootstrap\n"
+
+
+# ---------------------------------------------------------------------------
+# .pth file management
+# ---------------------------------------------------------------------------
+
+def _pth_candidate_dirs() -> list[Path]:
+    """Return candidate directories for .pth installation, best first.
+
+    Preference order:
+    1. User site-packages (survives venv recreation, no sudo needed).
+    2. Global site-packages (fallback).
+    """
+    dirs: list[Path] = []
+    # User site — shared across venvs (preferred)
+    if site.ENABLE_USER_SITE:
+        user_site = site.getusersitepackages()
+        if user_site:
+            dirs.append(Path(user_site))
+    # Global site-packages
+    for prefix in site.getsitepackages():
+        d = Path(prefix)
+        if d not in dirs:
+            dirs.append(d)
+    return dirs
+
+
+def _find_pth() -> Path | None:
+    """Find the currently installed .pth file, if any."""
+    for d in _pth_candidate_dirs():
+        p = d / PTH_NAME
+        if p.exists():
+            return p
+    return None
+
+
+def _install_pth() -> Path | None:
+    """Install the .pth file into the first writable candidate directory."""
+    for d in _pth_candidate_dirs():
+        try:
+            d.mkdir(parents=True, exist_ok=True)
+            p = d / PTH_NAME
+            p.write_text(PTH_CONTENT, encoding="utf-8")
+            return p
+        except (PermissionError, OSError):
+            continue
+    return None
+
+
+def _remove_pth() -> bool:
+    """Remove the .pth file from all candidate locations."""
+    removed = False
+    for d in _pth_candidate_dirs():
+        p = d / PTH_NAME
+        if p.exists():
+            try:
+                p.unlink()
+                removed = True
+            except OSError:
+                pass
+    return removed
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+def cmd_enable() -> int:
+    """Enable pythonfaster globally: ensure state is on + install .pth file.
+
+    After ``pip install pythonfaster``, the state is already enabled by default.
+    This command mainly installs the ``.pth`` file that triggers the
+    bootstrap on every Python startup.
+    """
+    save_state({"enabled": True, "mode": "all"})
+    pth = _install_pth()
+    if pth is None:
+        print(
+            "error: could not write .pth file to any site-packages directory.\n"
+            "Try:  pip install --user pythonfaster   (then re-run pythonfaster enable)",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"pythonfaster enabled")
+    print(f"  state:   {state_path()}  (enabled=true)")
+    print(f"  .pth:    {pth}")
+    print()
+    print("All Python processes will now auto-accelerate projects with")
+    print("pyproject.toml / pythonfaster.toml / .git markers in the CWD tree.")
+    print("Set PYTHONFASTER_DISABLE=1 to temporarily disable for a single process.")
+    return 0
+
+
+def cmd_disable() -> int:
+    """Disable pythonfaster globally: flip state to enabled=false."""
+    prev = load_state()
+    save_state({"enabled": False, "mode": prev.get("mode", "all")})
+    # Keep the .pth file installed so re-enable is just a state flip.
+    pth = _find_pth()
+    print(f"pythonfaster disabled")
+    print(f"  state:   {state_path()}  (enabled=false)")
+    if pth:
+        print(f"  .pth:    {pth}  (kept installed for fast re-enable)")
+    print("Run 'pythonfaster enable' to re-activate.  No restart needed.")
+    return 0
+
+
+def cmd_status() -> int:
+    """Print current activation state and .pth file location."""
+    from .config import state_path
+    state = load_state()
+    pth = _find_pth()
+    state_exists = state_path().exists()
+
+    print(f"State file:    {state_path()}")
+    if state_exists:
+        print(f"Enabled:       {state.get('enabled', True)}  (explicitly set)")
+    else:
+        print(f"Enabled:       {state.get('enabled', True)}  (default — no state file)")
+    print(f"Mode:          {state.get('mode', 'all')}")
+    if pth:
+        print(f".pth file:     {pth}")
+        content = pth.read_text(encoding="utf-8").strip()
+        print(f".pth content:  {content!r}")
+    else:
+        print(f".pth file:     not installed  (run 'pythonfaster enable' to install)")
+
+    # Show whether the hook is active in the current process.
+    active = any(
+        type(f).__name__ == "PythonFasterFinder" for f in sys.meta_path
+    )
+    print(f"Hook active:   {active}")
+    return 0
+
+
+def cmd_install_pth() -> int:
+    """Force (re)install the .pth file."""
+    pth = _install_pth()
+    if pth is None:
+        print("error: could not write .pth file", file=sys.stderr)
+        return 1
+    print(f".pth installed at {pth}")
+    return 0
+
+
+def cmd_remove_pth() -> int:
+    """Force remove the .pth file from all locations."""
+    if _remove_pth():
+        print(".pth file removed")
+    else:
+        print(".pth file was not found")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+USAGE = """\
+pythonfaster — zero-intrusion Python acceleration
+
+State defaults to enabled after pip install.  Run 'pythonfaster enable' once
+to install the .pth file for global auto-activation.
+
+Commands:
+  enable        One-time setup: install .pth file + ensure state is enabled
+  disable       Disable auto-acceleration globally
+  status        Show current state and .pth file location
+  install-pth   (Re)install the .pth file into site-packages
+  remove-pth    Remove the .pth file from all site-packages locations
+"""
+
+
+def main() -> int:
+    args = sys.argv[1:]
+    if not args or args[0] in ("-h", "--help", "help"):
+        print(USAGE)
+        return 0
+
+    cmd = args[0]
+    handlers = {
+        "enable":       cmd_enable,
+        "disable":      cmd_disable,
+        "status":       cmd_status,
+        "install-pth":  cmd_install_pth,
+        "remove-pth":   cmd_remove_pth,
+    }
+    handler = handlers.get(cmd)
+    if handler is None:
+        print(f"error: unknown command '{cmd}'", file=sys.stderr)
+        print(USAGE)
+        return 1
+    return handler()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pythonfaster/cache.py

@@ -0,0 +1,285 @@
+"""Cache layout, key computation, skip list and compile locking.
+
+Layout (all outside the user project)::
+
+    $PYTHONFASTER_CACHE_DIR  or  ~/.cache/pythonfaster/
+    ├── cpython-312/
+    │   ├── build/<key>/     # transient build area (removed after success)
+    │   └── lib/<key>/       # final artifacts: <mod>.cpython-312-*.so
+    └── index.json           # skip list + compile stats
+
+The cache key covers every factor that influences the artifact:
+source bytes, module name, Python version/ABI, Cython version,
+optimization level, compiler flags and the strategy-set version.
+"""
+from __future__ import annotations
+
+import hashlib
+import importlib.machinery
+import json
+import os
+import platform
+import sys
+import time
+from pathlib import Path
+
+#: Bump whenever the transform/strategy set changes semantics of artifacts.
+STRATEGY_SET_VERSION = "pythonfaster-1.8"  # Passes 9-10: recursive lowering and sum-LICM folding
+
+#: Compile flags baked into artifacts (and therefore into the key).
+#: ``-march=native`` is NOT used by default: it can produce artifacts that
+#: crash (SIGILL) when the cache is shared across machines with different
+#: CPU micro-architectures (e.g. AVX2 vs AVX-512).  Enable explicitly via
+#: ``PYTHONFASTER_MARCH_NATIVE=1`` for single-machine, profiled use.
+if os.name == "nt":  # pragma: no cover - Windows support lands in M2+
+    COMPILE_FLAGS = ("/O2",)
+else:
+    if os.environ.get("PYTHONFASTER_MARCH_NATIVE") == "1":
+        COMPILE_FLAGS = ("-O3", "-march=native")
+    else:
+        COMPILE_FLAGS = ("-O3",)
+
+_LOCK_STALE_SECONDS = 600.0
+
+
+# ---------------------------------------------------------------------------
+# paths & keying
+# ---------------------------------------------------------------------------
+
+def cache_root() -> Path:
+    env = os.environ.get("PYTHONFASTER_CACHE_DIR")
+    if env:
+        return Path(env)
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".cache"
+    return base / "pythonfaster"
+
+
+def interp_tag() -> str:
+    impl = platform.python_implementation().lower()
+    return f"{impl}-{sys.version_info.major}{sys.version_info.minor}"
+
+
+def versioned_root() -> Path:
+    return cache_root() / interp_tag()
+
+
+def ext_suffix() -> str:
+    return importlib.machinery.EXTENSION_SUFFIXES[0]
+
+
+def _cpu_feature_tag() -> str:
+    """A coarse CPU-feature tag for cache key isolation.
+
+    When ``-march=native`` is active, artifacts may use CPU-specific
+    instructions.  We include a tag derived from the platform machine and,
+    when available, a more specific CPU brand string so artifacts from
+    different micro-architectures don't collide.
+    """
+    parts = [platform.machine()]
+    if "-march=native" in COMPILE_FLAGS:
+        try:
+            brand = platform.processor() or ""
+            if brand:
+                parts.append(brand)
+        except Exception:
+            pass
+    return "|".join(parts)
+
+
+def cache_key(*, source: bytes, module: str, level: int) -> str:
+    """Compute the artifact key. Every influencing factor must appear here."""
+    from Cython import __version__ as cython_version  # lazy: keep bootstrap fast
+
+    h = hashlib.sha256()
+    h.update(b"pythonfaster-v1\0")
+    h.update(source)
+    h.update(b"\0")
+    h.update(module.encode())
+    h.update(b"\0")
+    h.update(interp_tag().encode())
+    h.update(b"\0")
+    h.update(_cpu_feature_tag().encode())
+    h.update(b"\0")
+    h.update(cython_version.encode())
+    h.update(b"\0")
+    h.update(str(level).encode())
+    h.update(b"\0")
+    h.update(" ".join(COMPILE_FLAGS).encode())
+    h.update(b"\0")
+    h.update(STRATEGY_SET_VERSION.encode())
+    return h.hexdigest()[:32]
+
+
+def so_rel_path(module: str) -> Path:
+    """Path of the artifact relative to its lib dir (dotted -> nested)."""
+    parts = module.split(".")
+    return Path(*parts[:-1], parts[-1] + ext_suffix()) if len(parts) > 1 \
+        else Path(parts[0] + ext_suffix())
+
+
+def so_lookup(key: str, module: str) -> Path | None:
+    """Return the cached .so path if present, else None."""
+    candidate = versioned_root() / "lib" / key / so_rel_path(module)
+    return candidate if candidate.exists() else None
+
+
+def pyx_rel_path(module: str) -> Path:
+    """Path of the stored compiled-source copy relative to its lib dir."""
+    rel = so_rel_path(module)
+    return rel.parent / rel.name.replace(ext_suffix(), ".pyx")
+
+
+def pyx_lookup(key: str, module: str) -> Path | None:
+    """Return the stored compiled source (.pyx actually compiled) if kept."""
+    candidate = versioned_root() / "lib" / key / pyx_rel_path(module)
+    return candidate if candidate.exists() else None
+
+
+def lib_dir(key: str) -> Path:
+    return versioned_root() / "lib" / key
+
+
+def build_dir(key: str) -> Path:
+    return versioned_root() / "build" / key
+
+
+# ---------------------------------------------------------------------------
+# index: skip list + stats
+# ---------------------------------------------------------------------------
+
+class CacheIndex:
+    """Persistent index.json with skip list and compile statistics.
+
+    Writes are atomic (tmp + rename). Last-writer-wins across processes;
+    losing an occasional stat update is acceptable, the skip list is
+    best-effort protection against repeated failed compiles.
+    """
+
+    def __init__(self) -> None:
+        self.path = cache_root() / "index.json"
+        self._data = self._read()
+
+    def _read(self) -> dict:
+        try:
+            with open(self.path, "r", encoding="utf-8") as fh:
+                data = json.load(fh)
+            if isinstance(data, dict):
+                data.setdefault("skipped", {})
+                data.setdefault("compiled", {})
+                return data
+        except Exception:
+            pass
+        return {"version": 1, "skipped": {}, "compiled": {}}
+
+    def _write(self) -> None:
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            # Use a unique temp file per process to avoid clobbering
+            # concurrent writes from other processes.
+            tmp = self.path.with_suffix(f".json.{os.getpid()}.tmp")
+            with open(tmp, "w", encoding="utf-8") as fh:
+                json.dump(self._data, fh, indent=1)
+            os.replace(tmp, self.path)
+        except Exception as exc:
+            # The index is advisory, so never break imports over it.  Make
+            # persistent cache/index failures diagnosable when requested.
+            if os.environ.get("PYTHONFASTER_VERBOSE") == "1":
+                print(
+                    f"[pythonfaster] warning: failed to write cache index: {exc}",
+                    file=sys.stderr,
+                )
+
+    def refresh(self) -> None:
+        self._data = self._read()
+
+    def is_skipped(self, key: str) -> bool:
+        return key in self._data["skipped"]
+
+    def record_skip(self, key: str, module: str, reason: str) -> None:
+        self.refresh()
+        self._data["skipped"][key] = {
+            "module": module,
+            "reason": reason[:500],
+            "time": time.time(),
+        }
+        self._write()
+
+    def record_success(self, key: str, module: str, seconds: float,
+                       strategies: list[str] | None = None) -> None:
+        self.refresh()
+        self._data["compiled"][key] = {
+            "module": module,
+            "seconds": round(seconds, 3),
+            "time": time.time(),
+            "strategies": strategies or [],
+        }
+        self._data["skipped"].pop(key, None)
+        self._write()
+
+    def stats(self) -> dict:
+        self.refresh()
+        return {
+            "compiled": len(self._data["compiled"]),
+            "skipped": len(self._data["skipped"]),
+            "skipped_detail": dict(self._data["skipped"]),
+        }
+
+
+def cache_size_bytes() -> int:
+    total = 0
+    root = cache_root()
+    if root.exists():
+        for dirpath, _dirnames, filenames in os.walk(root):
+            for name in filenames:
+                try:
+                    total += os.path.getsize(os.path.join(dirpath, name))
+                except OSError:
+                    pass
+    return total
+
+
+# ---------------------------------------------------------------------------
+# compile lock (cross-process, lockfile based)
+# ---------------------------------------------------------------------------
+
+class FileLock:
+    """Advisory cross-process lock via O_EXCL lockfile.
+
+    Stale locks (holder died) are broken after ``_LOCK_STALE_SECONDS``.
+    """
+
+    def __init__(self, path: Path, timeout: float = 300.0) -> None:
+        self.path = Path(str(path) + ".lock")
+        self.timeout = timeout
+
+    def __enter__(self) -> "FileLock":
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        deadline = time.monotonic() + self.timeout
+        stale_broken = False
+        while True:
+            try:
+                fd = os.open(self.path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+                os.close(fd)
+                return self
+            except FileExistsError:
+                if time.monotonic() > deadline:
+                    raise TimeoutError(f"compile lock timeout: {self.path}")
+                try:
+                    age = time.time() - self.path.stat().st_mtime
+                except OSError:
+                    continue  # lock vanished between checks; retry immediately
+                if age > _LOCK_STALE_SECONDS and not stale_broken:
+                    stale_broken = True
+                    try:
+                        self.path.unlink()
+                    except OSError:
+                        pass
+                    continue
+                time.sleep(0.05)
+
+    def __exit__(self, *exc: object) -> None:
+        try:
+            self.path.unlink()
+        except OSError:
+            pass