Buckets:
| """Logic for checking project dependencies declared in ``calkit.yaml``. | |
| The ``app``, ``env-var``, and ``calkit-config`` kinds are handled directly | |
| by :func:`calkit.core.check_dep_exists`. This module adds support for the | |
| ``setup`` kind, which represents a per-machine precondition that isn't a | |
| file -- the canonical example is ``gh auth login``, which must be done | |
| once per clone and can be probed with ``gh auth status``. | |
| A ``setup`` dep declares: | |
| - ``check_command``: a shell command; exit 0 = satisfied. | |
| - ``setup_command``: optional. Printed as a fix-it command for non-TTY | |
| runs (CI); on an interactive TTY the user is asked before we exec it. | |
| - ``cache_ttl``: optional. Successful checks are cached in | |
| ``.calkit/local/dep-checks.sqlite`` for this long (default | |
| :data:`DEFAULT_SETUP_CACHE_TTL`) so repeated ``calkit run`` invocations | |
| don't re-probe network-bound commands. Cache entries also invalidate | |
| whenever the ``check_command`` itself changes, so editing | |
| ``calkit.yaml`` never silently relies on a stale result. Set | |
| ``cache_ttl: 0`` to disable caching for a specific dep. | |
| To run a command inside a project environment, the user prefixes it with | |
| ``calkit xenv -n <env> --`` explicitly -- there's no implicit wrap, | |
| because explicit is easier to reason about when commands fail. | |
| """ | |
| from __future__ import annotations | |
| import hashlib | |
| import os | |
| import re | |
| import subprocess | |
| import sys | |
| import time | |
| from typing import Any | |
| # Path constants are duplicated from ``calkit/dvc/zip.py`` rather than | |
| # imported to avoid pulling the DVC stack in for a simple dep check. | |
| LOCAL_DIR = ".calkit/local" | |
| DEP_CHECK_CACHE_PATH = LOCAL_DIR + "/dep-checks.sqlite" | |
| # How long to cache a successful setup-dep check by default. One day is | |
| # short enough that expiring credentials surface within a workday, and | |
| # long enough that repeated ``calkit run`` invocations during active | |
| # development don't re-probe network checks every time. Override per dep | |
| # with ``cache_ttl``, or disable for one dep with ``cache_ttl: 0``. | |
| DEFAULT_SETUP_CACHE_TTL = 24 * 60 * 60 | |
| _TTL_UNITS = { | |
| "s": 1, | |
| "m": 60, | |
| "h": 60 * 60, | |
| "d": 24 * 60 * 60, | |
| "w": 7 * 24 * 60 * 60, | |
| } | |
| _TTL_RE = re.compile(r"^\s*(\d+)\s*([smhdw]?)\s*$", re.IGNORECASE) | |
| def _format_uvx_from(spec: str) -> str: | |
| """Format a calkit version spec into a ``uvx --from`` argument. | |
| A bare version like ``0.38`` becomes ``calkit-python@0.38`` (uv's | |
| exact-pin shorthand); a PEP 440 specifier like ``>=0.38`` is | |
| appended directly, e.g. ``calkit-python>=0.38``. | |
| """ | |
| spec = spec.strip() | |
| if not spec: | |
| return "calkit-python" | |
| if spec[0].isdigit(): | |
| return f"calkit-python@{spec}" | |
| return f"calkit-python{spec}" | |
| def _suggest_version_from_spec(spec: str) -> str | None: | |
| """Pull the first version-looking token out of ``spec`` for a hint.""" | |
| m = re.search(r"\d[\w.+\-!]*", spec) | |
| return m.group(0) if m else None | |
| def check_calkit_version(spec: str) -> None: | |
| """Verify the running calkit satisfies ``spec`` (e.g. ``>=0.38``). | |
| Raises ``ValueError`` with a fix-it message pointing the user at | |
| ``calkit --use-version`` or ``calkit upgrade`` when the installed | |
| version is outside the requested specifier. A bare version like | |
| ``0.38`` is interpreted as ``==0.38`` so users can write | |
| ``- calkit==0.38`` or simply ``- calkit>=0.38`` in ``calkit.yaml``. | |
| """ | |
| from packaging.specifiers import SpecifierSet | |
| from packaging.version import InvalidVersion, Version | |
| import calkit | |
| raw = (spec or "").strip() | |
| if not raw: | |
| return | |
| spec_str = raw if raw[0] in "<>=!~" else f"=={raw}" | |
| try: | |
| spec_set = SpecifierSet(spec_str) | |
| except Exception as e: | |
| raise ValueError(f"Invalid calkit version spec '{spec}': {e}") | |
| try: | |
| current = Version(calkit.__version__) | |
| except InvalidVersion: | |
| # A dev/editable install with an unparseable version: don't block. | |
| return | |
| if current in spec_set: | |
| return | |
| # A development build of X sorts *before* X under PEP 440, so someone | |
| # running a dev build of the very version a project asks for would be | |
| # told to upgrade to what they are already running -- which is exactly | |
| # the position anyone working on Calkit itself is in. Judge it by the | |
| # release it is a development of. | |
| if current.is_devrelease or current.is_prerelease: | |
| try: | |
| if Version(current.base_version) in spec_set: | |
| return | |
| except InvalidVersion: | |
| pass | |
| suggested = _suggest_version_from_spec(spec_str) | |
| msg = ( | |
| f"calkit{spec_str} required, but installed version is " | |
| f"{calkit.__version__}." | |
| ) | |
| if suggested: | |
| msg += ( | |
| f" Re-run with 'calkit --use-version {suggested} ...' or " | |
| "upgrade with 'calkit upgrade'." | |
| ) | |
| else: | |
| msg += " Upgrade with 'calkit upgrade'." | |
| raise ValueError(msg) | |
| def parse_ttl(ttl: str | int | float) -> int: | |
| """Parse a TTL like ``30s``, ``5m``, ``2h``, ``7d``, ``1w`` into seconds. | |
| Bare numbers are seconds. ``0`` disables caching (caller's contract). | |
| Raises ``ValueError`` on garbage so misconfiguration surfaces at | |
| check time rather than silently disabling the cache. | |
| """ | |
| if isinstance(ttl, (int, float)): | |
| return int(ttl) | |
| m = _TTL_RE.match(str(ttl)) | |
| if m is None: | |
| raise ValueError( | |
| f"Invalid cache_ttl '{ttl}'; expected forms like '30s', '5m', " | |
| "'2h', '7d', '1w', or a bare integer number of seconds" | |
| ) | |
| n, unit = m.groups() | |
| return int(n) * _TTL_UNITS.get(unit.lower(), 1) | |
| def _hash_check_cmd(check: str | None) -> str: | |
| """Hash the check command so cache entries invalidate when it changes.""" | |
| return hashlib.sha256((check or "").encode("utf-8")).hexdigest() | |
| def _cache_path(wdir: str | None) -> str: | |
| return ( | |
| os.path.join(wdir, DEP_CHECK_CACHE_PATH) | |
| if wdir | |
| else DEP_CHECK_CACHE_PATH | |
| ) | |
| def _cache_open(wdir: str | None): | |
| """Open the SqliteDict cache, creating the local dir on demand.""" | |
| from sqlitedict import SqliteDict | |
| import calkit | |
| calkit.ensure_local_dir(wdir) | |
| return SqliteDict(_cache_path(wdir), autocommit=True) | |
| def cache_lookup( | |
| name: str, | |
| check: str | None, | |
| *, | |
| wdir: str | None = None, | |
| ) -> dict | None: | |
| """Return a fresh cache entry for ``name``, or None if missing/expired. | |
| Entries also invalidate when the ``check`` command hash changes, so | |
| editing ``calkit.yaml`` never silently relies on a stale result. | |
| """ | |
| if not os.path.isfile(_cache_path(wdir)): | |
| return None | |
| with _cache_open(wdir) as cache: | |
| entry = cache.get(name) | |
| if not entry: | |
| return None | |
| ttl_s = entry.get("ttl_seconds", 0) | |
| passed_at = entry.get("passed_at", 0) | |
| if ttl_s > 0 and (time.time() - passed_at) > ttl_s: | |
| return None | |
| if entry.get("check_hash") != _hash_check_cmd(check): | |
| return None | |
| return entry | |
| def cache_record( | |
| name: str, | |
| check: str | None, | |
| ttl_seconds: int, | |
| *, | |
| wdir: str | None = None, | |
| ) -> None: | |
| with _cache_open(wdir) as cache: | |
| cache[name] = { | |
| "passed_at": time.time(), | |
| "ttl_seconds": int(ttl_seconds), | |
| "check_hash": _hash_check_cmd(check), | |
| } | |
| def cache_clear(*, wdir: str | None = None) -> None: | |
| """Remove all cached dependency-check entries (used by ``--no-cache``).""" | |
| if not os.path.isfile(_cache_path(wdir)): | |
| return | |
| with _cache_open(wdir) as cache: | |
| cache.clear() | |
| def _run_shell( | |
| cmd: str, *, capture: bool = True | |
| ) -> subprocess.CompletedProcess: | |
| """Run ``cmd`` through the user's shell; mirrors how they would run it.""" | |
| return subprocess.run(cmd, shell=True, capture_output=capture, text=True) | |
| def _is_interactive() -> bool: | |
| """True only when both stdin and stdout are TTYs. | |
| Stdout matters because the prompt needs to render; stdin matters because | |
| we need to read the user's answer. CI environments fail at least one | |
| and fall through to the abort-with-fix-command path. | |
| """ | |
| try: | |
| return sys.stdin.isatty() and sys.stdout.isatty() | |
| except (AttributeError, ValueError): | |
| return False | |
| def _resolve_cache_ttl(dep: dict[str, Any]) -> int: | |
| """Resolve the effective cache TTL for a setup dep. | |
| Defaults to ``DEFAULT_SETUP_CACHE_TTL`` when ``cache_ttl`` is absent; | |
| ``cache_ttl: 0`` explicitly disables caching. | |
| """ | |
| raw = dep.get("cache_ttl") | |
| if raw is None: | |
| return DEFAULT_SETUP_CACHE_TTL | |
| return parse_ttl(raw) | |
| def check_setup_dep( | |
| dep: dict[str, Any], | |
| *, | |
| interactive: bool | None = None, | |
| use_cache: bool = True, | |
| wdir: str | None = None, | |
| ) -> bool: | |
| """Check a ``kind: setup`` dependency. | |
| Returns True if satisfied (or successfully made satisfied via the | |
| setup command), False otherwise. Successful checks are cached for | |
| ``cache_ttl`` (defaulting to one day) under ``.calkit/local`` so | |
| repeated runs skip re-probing. The caller can pass ``use_cache=False`` | |
| to bypass and force re-probing, which the CLI exposes as ``--no-cache``. | |
| """ | |
| name = dep.get("name") | |
| if not name: | |
| raise ValueError(f"setup dependency missing 'name': {dep}") | |
| check_command = dep.get("check_command") | |
| setup_command = dep.get("setup_command") | |
| if not check_command: | |
| raise ValueError( | |
| f"setup dependency '{name}' must declare 'check_command'" | |
| ) | |
| if interactive is None: | |
| interactive = _is_interactive() | |
| ttl_seconds = _resolve_cache_ttl(dep) | |
| # Cache hit short-circuits the probe entirely. | |
| if use_cache and ttl_seconds > 0: | |
| hit = cache_lookup(name, check_command, wdir=wdir) | |
| if hit is not None: | |
| return True | |
| result = _run_shell(check_command) | |
| if result.returncode == 0: | |
| if ttl_seconds > 0: | |
| cache_record(name, check_command, ttl_seconds, wdir=wdir) | |
| return True | |
| return _try_setup( | |
| name=name, | |
| check_command=check_command, | |
| setup_command=setup_command, | |
| interactive=interactive, | |
| ttl_seconds=ttl_seconds, | |
| wdir=wdir, | |
| failure_reason=(result.stderr or result.stdout or "").strip(), | |
| ) | |
| def prompt_and_store_env_var( | |
| name: str, | |
| *, | |
| default: str | None = None, | |
| dotenv_path: str = ".env", | |
| ) -> str | None: | |
| """Prompt the user for an env-var value, persist it to ``.env``, set it | |
| on ``os.environ``, and return the value. | |
| Returns ``None`` if the user aborted (EOF / no value and no default). | |
| The caller decides whether that is fatal. ``.env`` is appended to | |
| ``.gitignore`` if not already ignored, mirroring ``calkit check | |
| env-vars`` so secrets don't sneak into git. | |
| """ | |
| import dotenv | |
| prompt = f"Enter a value for {name}" | |
| if default is not None: | |
| prompt += f" [{default}]" | |
| try: | |
| raw = input(prompt + ": ") | |
| except EOFError: | |
| return None | |
| value = raw.strip() or default | |
| if value is None: | |
| return None | |
| dotenv.set_key( | |
| dotenv_path=dotenv_path, key_to_set=name, value_to_set=value | |
| ) | |
| os.environ[name] = value | |
| _ensure_env_gitignored(dotenv_path) | |
| return value | |
| def _env_var_dep_default(name: str, deps: list) -> str | None: | |
| """The default declared for an env-var dependency, if it has one.""" | |
| for dep in deps: | |
| if not isinstance(dep, dict): | |
| continue | |
| if dep.get("name") == name: | |
| return dep.get("default") | |
| if list(dep.keys()) == [name]: | |
| return (dep[name] or {}).get("default") | |
| return None | |
| def resolve_env_var_deps( | |
| ck_info: dict, | |
| interactive: bool | None = None, | |
| ) -> list[str]: | |
| """Set any declared env-var dependencies that aren't set yet. | |
| A project shares its ``calkit.yaml`` but not its ``.env``, so the | |
| variables it declares are the first thing missing for anyone but its | |
| author. Asking on a terminal turns that from an error someone has to | |
| decode into a question they can answer. | |
| Returns the names still unset, so a caller that reports rather than | |
| enforces -- ``calkit status``, say -- can mention them without failing. | |
| """ | |
| import calkit | |
| if interactive is None: | |
| interactive = _is_interactive() | |
| deps = calkit.get_requirements(ck_info) | |
| missing = [] | |
| for name in calkit.get_env_var_dep_names(ck_info): | |
| if os.environ.get(name): | |
| continue | |
| if not interactive: | |
| missing.append(name) | |
| continue | |
| print(f"Missing env var '{name}'") | |
| value = prompt_and_store_env_var( | |
| name, default=_env_var_dep_default(name, deps) | |
| ) | |
| if value is None: | |
| missing.append(name) | |
| return missing | |
| def _ensure_env_gitignored(dotenv_path: str) -> None: | |
| """Append ``dotenv_path`` to ``.gitignore`` if not already ignored. | |
| Falls back to a plain ``.gitignore`` append when the project isn't a | |
| git repo so this helper is safe to call from non-git contexts. | |
| """ | |
| try: | |
| import calkit.git | |
| repo = calkit.git.get_repo() | |
| if repo.ignored(dotenv_path): | |
| return | |
| except Exception: | |
| pass | |
| try: | |
| with open(".gitignore", "a") as f: | |
| f.write(f"\n{dotenv_path}\n") | |
| except OSError: | |
| pass | |
| def _try_setup( | |
| *, | |
| name: str, | |
| check_command: str, | |
| setup_command: str | None, | |
| interactive: bool, | |
| ttl_seconds: int, | |
| wdir: str | None, | |
| failure_reason: str, | |
| ) -> bool: | |
| """Common failure path: prompt-and-run on TTY, else print and abort. | |
| After setup runs we re-verify ``check_command`` so a setup that | |
| *claims* success but doesn't actually satisfy the dep is caught here | |
| instead of failing later inside the pipeline. A successful | |
| re-verification populates the cache so we don't immediately re-probe | |
| on the next ``calkit run``. | |
| """ | |
| print(f"Setup dependency '{name}' is not satisfied.") | |
| if failure_reason: | |
| print(f" Reason: {failure_reason}") | |
| if not setup_command: | |
| print( | |
| f" No 'setup_command' declared; satisfy '{name}' manually and " | |
| "re-run." | |
| ) | |
| return False | |
| if not interactive: | |
| print(f" To satisfy, run: {setup_command}") | |
| return False | |
| try: | |
| answer = ( | |
| input(f"Run setup now ({setup_command!r})? [Y/n] ").strip().lower() | |
| ) | |
| except EOFError: | |
| answer = "n" | |
| if answer not in ("", "y", "yes"): | |
| print(f" Skipped. To satisfy, run: {setup_command}") | |
| return False | |
| # capture=False so interactive setup tools (e.g., the browser-based | |
| # ``gh auth login`` flow) can talk to the terminal directly. | |
| result = _run_shell(setup_command, capture=False) | |
| if result.returncode != 0: | |
| print(f" Setup command exited {result.returncode}.") | |
| return False | |
| verify = _run_shell(check_command) | |
| if verify.returncode != 0: | |
| print( | |
| " Setup ran but check still fails; satisfy manually and re-run." | |
| ) | |
| return False | |
| if ttl_seconds > 0: | |
| cache_record(name, check_command, ttl_seconds, wdir=wdir) | |
| return True | |
Xet Storage Details
- Size:
- 15.4 kB
- Xet hash:
- f7c8b2b98a6ab0351568b2927e471ed29df6cc33e83eb14ad527527f776fa9fd
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.