rgpycrumbs._aux

Attributes

logger
_DEPENDENCY_MAP
_CPU_OVERRIDES
_cuda_available

Classes

_LazyModule

Proxy that defers ensure_import until first attribute access.

Functions

warn_on_direct_script_import(→ None)	Warn when a PEP 723 script module is imported directly.
enable_library_auto_deps(→ None)	Default AUTO_DEPS for library plot APIs (match CLI dispatch).
_has_cuda(→ bool)	Return True when a usable NVIDIA GPU is present.
_get_dep_cache_dir(→ pathlib.Path)	Return the per-user dependency cache directory.
_resolve_pip_spec(→ str)	Return the pip install spec for module_name, respecting CUDA and SBOM pins.
_uv_install(→ None)	Install package_spec into target using uv (falling back to pip).
ensure_import(module_name)	Import module_name through a 5-step priority chain.
lazy_import(→ _LazyModule)	Return a lazy proxy for module_name.
getstrform(pathobj)	Return the absolute path as a string.
get_gitroot()	Return the root of the current git repository as a Path.
switchdir(path)	Context manager that temporarily changes the working directory.
_import_from_parent_env(module_name)	Import a module from parent interpreter's site-packages as a fallback.

Module Contents

rgpycrumbs._aux.logger

rgpycrumbs._aux._DEPENDENCY_MAP: dict[str, str]

rgpycrumbs._aux._CPU_OVERRIDES: dict[str, str]

rgpycrumbs._aux._cuda_available: bool | None = None

rgpycrumbs._aux.warn_on_direct_script_import(module_name: str, cli_hint: str, *, auto_env: str = 'RGPYCRUMBS_AUTO_DEPS', parent_env: str = 'RGPYCRUMBS_PARENT_SITE_PACKAGES', suppress_env: str = 'RGPYCRUMBS_SUPPRESS_SCRIPT_IMPORT_WARNING') → None

Warn when a PEP 723 script module is imported directly.

The warning is suppressed for normal script execution (__main__), when the dependency-resolution environment contract is already present, or when the caller opts out explicitly.

rgpycrumbs._aux.enable_library_auto_deps() → None

Default AUTO_DEPS for library plot APIs (match CLI dispatch).

CLI sets RGPYCRUMBS_AUTO_DEPS from config (default on) before running scripts. Direct from rgpycrumbs.eon import plot_neb never did, so ensure_import("jax") / adjustText failed unless the host pinned them. Call this at library plot entry before heavy imports.

rgpycrumbs._aux._has_cuda() → bool

Return True when a usable NVIDIA GPU is present.

Checks for nvidia-smi on PATH and verifies it exits cleanly. The result is cached for the lifetime of the process.

rgpycrumbs._aux._get_dep_cache_dir() → pathlib.Path

Return the per-user dependency cache directory.

Defaults to $XDG_CACHE_HOME/rgpycrumbs/deps/ (typically ~/.cache/rgpycrumbs/deps/).

rgpycrumbs._aux._resolve_pip_spec(module_name: str) → str

Return the pip install spec for module_name, respecting CUDA and SBOM pins.

If the host lacks a CUDA device and a CPU-only override exists, the override is returned instead of the default spec. When RGPYCRUMBS_LOCK_PINS / RGPYCRUMBS_SBOM_PINS is set (dispatch after uv.lock / pylock / CycloneDX), matching packages become name==version.

rgpycrumbs._aux._uv_install(package_spec: str, target: pathlib.Path) → None

Install package_spec into target using uv (falling back to pip).

Raises RuntimeError if both installers fail.

rgpycrumbs._aux.ensure_import(module_name: str)

Import module_name through a 5-step priority chain.

1. Current environment (importlib)

2. Parent environment (RGPYCRUMBS_PARENT_SITE_PACKAGES)

3. uv cache directory on sys.path

4. uv/pip install into cache (opt-in via RGPYCRUMBS_AUTO_DEPS=1)

5. Raise ImportError with an actionable message

Returns the imported module object.

Added in version 1.3.0.

class rgpycrumbs._aux._LazyModule(module_name: str)

Proxy that defers ensure_import until first attribute access.

After resolution the proxy replaces its own __dict__ with the real module’s attributes so subsequent access carries zero overhead.

Added in version 1.3.0.

_resolve()

__getattr__(attr)

__repr__()

rgpycrumbs._aux.lazy_import(module_name: str) → _LazyModule

Return a lazy proxy for module_name.

The actual import (via ensure_import()) is deferred until the first attribute access on the returned object.

Added in version 1.3.0.

rgpycrumbs._aux.getstrform(pathobj)

Return the absolute path as a string.

Added in version 0.0.1.

rgpycrumbs._aux.get_gitroot()

Return the root of the current git repository as a Path.

Added in version 0.0.1.

rgpycrumbs._aux.switchdir(path)

Context manager that temporarily changes the working directory.

Added in version 0.0.1.

rgpycrumbs._aux._import_from_parent_env(module_name: str)

Import a module from parent interpreter’s site-packages as a fallback. Uses importlib to correctly handle nested modules (e.g. ‘tblite.interface’).