venv_sitecustomize.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/tools/venv_sitecustomize.py
 
"""
Purpose
-------
Pointer stub. Plan 270 P1 moved the real venv repair file to
`oc_diagnostics/oc_diagnostics/venv_sitecustomize.py` - the package it
repairs - so the dispatcher layer needs no toolchain to build a usable
venv. This module keeps oct's historical path alive by naming where the
file now lives; it is NEVER the file that gets copied.
 
The repair itself is unchanged: `python -m <anything>` run from the
monorepo root fails with `cannot import name '_dbg' from
'oc_diagnostics'`, because Python finds the bare subproject FOLDER
(`oc_diagnostics\\`, `oct\\`, `oc_chat\\`) on the working directory before
the editable-installed package. The moved finder makes the installed
package win over a bare folder, while a real checkout (a worktree's
package WITH `__init__.py`) still wins over the install.
 
Install: copy :data:`SOURCE` - not this file - to
`.venv\\Lib\\site-packages\\sitecustomize.py`. Re-copy after any venv
rebuild. It is COPIED out, never imported as part of the oct package,
and it must stay stdlib-pure: any package import here would pre-load
that package into EVERY interpreter, which breaks fresh-import leaf
guards (the oc_pricing t1 guard caught exactly that). That is why the
location is resolved through `importlib.util.find_spec`, which reads
the spec without importing anything (operator ruling 2026-09-15).
 
Responsibilities
----------------
- :data:`SOURCE` - the real repair file inside the resolvable
  `oc_diagnostics`, or `None` when no such copy exists.
 
Diagnostics
-----------
Domain: OCT-CORE
Levels:
    L2 - reserved (path resolution only; this module must emit nothing)
    L3 - reserved
    L4 - reserved
 
Contracts
---------
- stdlib-only, and it never imports `oc_diagnostics`: a spec lookup is
  all a path resolution needs, and importing the package here would put
  it in every interpreter that touches this module.
- Resolves a path and nothing else: no finder is installed, no
  `sys.meta_path` entry is added, nothing is read and nothing is
  written.
- Never raises. `SOURCE` is `None` when `oc_diagnostics` cannot be
  located or predates the move; callers check before copying.
"""
 
# OCT-LINT: disable-file=dbg_import reason="Plan 263: stdlib-only by contract - any package import here pre-loads that package into EVERY interpreter using the venv, which breaks fresh-import leaf guards"
# OCT-LINT: disable-file=dbg_usage reason="Plan 263: this runs inside the import machinery and is copied out to site-packages, so it can emit nothing"
 
from __future__ import annotations
 
import importlib.util
from pathlib import Path
 
#: The package whose copy of the repair file this stub points at.
REPAIR_PACKAGE = "oc_diagnostics"
 
#: The file's name inside that package.
REPAIR_FILENAME = "venv_sitecustomize.py"
 
 
def _locate() -> Path | None:
    """Find the repair file without importing the package that ships it.
 
    ``find_spec`` reads the spec a finder would produce and stops there,
    so nothing is executed and nothing lands in ``sys.modules``.
    ``submodule_search_locations`` is the package's own directory list,
    which answers for a regular package and for a namespace package
    alike - and the namespace case is exactly the broken venv this file
    exists to repair, so it must not be the case that crashes.
    """
    try:
        spec = importlib.util.find_spec(REPAIR_PACKAGE)
    except (ImportError, ValueError):  # pragma: no cover - defensive
        return None
    if spec is None:
        return None
    for location in list(spec.submodule_search_locations or ()):
        candidate = Path(location) / REPAIR_FILENAME
        if candidate.is_file():
            return candidate
    return None
 
 
#: The real repair file, inside the package it repairs (plan 270 P1).
SOURCE: Path | None = _locate()
 
__all__ = ["REPAIR_FILENAME", "REPAIR_PACKAGE", "SOURCE"]