rgpycrumbs.api

Stable public suite API for config, pins/locks, and on-demand imports.

This is the documented surface for consumers (chemparseplot, pychum, wailord, cookbooks). Prefer these names over importing private modules.

Example:

from rgpycrumbs.api import load_config, load_pypi_pins, ensure_import

cfg = load_config()
pins = cfg.merged_package_pins_normalized()
# optional lock file
# pins = load_pypi_pins("uv.lock")

jax = ensure_import("jax")  # needs RGPKGS_AUTO_DEPS=1 or host install

See docs/orgmode/explanation/public_api.org and suite architecture docs.

Added in version 1.9.18.

Attributes

CONFIG_PATH_ENV
LOCK_PATH_ENV

Functions

ensure_import(module_name)	Import module_name through a 5-step priority chain.
lazy_import(→ _LazyModule)	Return a lazy proxy for module_name.
load_config(→ RgpycrumbsConfig)	Load and merge global + project + optional explicit config files.
resolve_auto_deps_default(→ str)	Return '1' or '0' for default AUTO_DEPS when env unset.
resolve_force_uv(→ bool)	Whether to force uv isolation (False if --dev / DEV env).
resolve_lock_path_layered(→ pathlib.Path | None)	CLI → env (RGPKGS_* / RGPYCRUMBS_*) → config file lock path.
user_config_path(→ pathlib.Path)	Preferred global config: ~/.config/rgpkgs/config.toml.
apply_pin_to_spec(→ str)	If pip_spec's package is in pins, return name==version.
load_pypi_pins(→ dict[str, str])	Load any supported lock/SBOM path and return a PyPI pin map.
normalize_pypi_name(→ str)	PEP 503-ish name normalization for pin lookups.
pins_from_env(→ dict[str, str])	Read pin map from RGPKGS_LOCK_PINS / legacy pin envs.
pins_to_constraint_lines(→ list[str])	Render pin map as pip/uv constraint lines (name==version).
suite_pins(→ dict[str, str])	Merged package pins: RGPKGS_LOCK_PINS / env pins or layered config.

Module Contents

rgpycrumbs.api.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 RGPKGS_AUTO_DEPS=1 or legacy RGPYCRUMBS_AUTO_DEPS=1)

5. Raise ImportError with an actionable message

Returns the imported module object.

Added in version 1.3.0.

Changed in version 1.10.5: Auto-deps respects RGPKGS_AUTO_DEPS (ecosystem) as well as the legacy RGPYCRUMBS_AUTO_DEPS name, matching AUTO_DEPS_ENVS.

rgpycrumbs.api.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.api.CONFIG_PATH_ENV = 'RGPKGS_CONFIG'

rgpycrumbs.api.load_config(*, cwd: pathlib.Path | None = None, explicit_config: pathlib.Path | str | None = None) → RgpycrumbsConfig

Load and merge global + project + optional explicit config files.

rgpycrumbs.api.resolve_auto_deps_default(*, config: RgpycrumbsConfig | None = None, cwd: pathlib.Path | None = None) → str

Return '1' or '0' for default AUTO_DEPS when env unset.

rgpycrumbs.api.resolve_force_uv(*, is_dev: bool, config: RgpycrumbsConfig | None = None, cwd: pathlib.Path | None = None) → bool

Whether to force uv isolation (False if –dev / DEV env).

rgpycrumbs.api.resolve_lock_path_layered(*, cli_lock: str | None = None, cli_sbom: str | None = None, config: RgpycrumbsConfig | None = None, cwd: pathlib.Path | None = None) → pathlib.Path | None

CLI → env (RGPKGS_* / RGPYCRUMBS_*) → config file lock path.

rgpycrumbs.api.user_config_path() → pathlib.Path

Preferred global config: ~/.config/rgpkgs/config.toml.

rgpycrumbs.api.LOCK_PATH_ENV = 'RGPKGS_LOCK'

rgpycrumbs.api.apply_pin_to_spec(pip_spec: str, pins: dict[str, str]) → str

If pip_spec’s package is in pins, return name==version.

rgpycrumbs.api.load_pypi_pins(path: str | pathlib.Path) → dict[str, str]

Load any supported lock/SBOM path and return a PyPI pin map.

Raises:

FileNotFoundError: path missing ValueError: unreadable / unsupported / empty-of-python when required

rgpycrumbs.api.normalize_pypi_name(name: str) → str

PEP 503-ish name normalization for pin lookups.

rgpycrumbs.api.pins_from_env(env: dict[str, str] | None = None) → dict[str, str]

Read pin map from RGPKGS_LOCK_PINS / legacy pin envs.

rgpycrumbs.api.pins_to_constraint_lines(pins: dict[str, str]) → list[str]

Render pin map as pip/uv constraint lines (name==version).

rgpycrumbs.api.suite_pins() → dict[str, str]

Merged package pins: RGPKGS_LOCK_PINS / env pins or layered config.

Single implementation for the suite. Consumers (chemparseplot, wailord) should re-export or call this rather than reimplementing the merge.

Soft-fails to env-only pins if config load errors (never raises for missing config files). Does not install packages and does not require uv.