Functions
Path\|None	_locate ()

Variables
str	REPAIR_PACKAGE = "oc_diagnostics"
str	REPAIR_FILENAME = "venv_sitecustomize.py"
Path	SOURCE = _locate()

Detailed Description

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.

Function Documentation

◆ _locate()

Path | None venv_sitecustomize._locate ( )

protected

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.

Definition at line 71 of file venv_sitecustomize.py.

Variable Documentation

◆ REPAIR_FILENAME

str venv_sitecustomize.REPAIR_FILENAME = "venv_sitecustomize.py"

Definition at line 68 of file venv_sitecustomize.py.

◆ REPAIR_PACKAGE

str venv_sitecustomize.REPAIR_PACKAGE = "oc_diagnostics"

Definition at line 65 of file venv_sitecustomize.py.

◆ SOURCE

Path venv_sitecustomize.SOURCE = _locate()

Definition at line 95 of file venv_sitecustomize.py.

Functions