calkit-python 0.40.1__tar.gz → 0.41.0__tar.gz

{calkit_python-0.40.1 → calkit_python-0.41.0}/AGENTS.md

@@ -25,3 +25,7 @@ a feature in one function over many different test functions.
 Do not write docstrings in test functions.
 
 For prose, only use one space after punctuation.
+
+Don't overzealously split up functions just because they're long.
+Functions should usually be used ~3 times before abstracting.
+Otherwise, split up long ones into logical sections with comments.

{calkit_python-0.40.1 → calkit_python-0.41.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: calkit-python
-Version: 0.40.1
+Version: 0.41.0
 Summary: Reproducibility simplified.
 Project-URL: Homepage, https://calkit.org
 Project-URL: Issues, https://github.com/calkit/calkit/issues
@@ -193,6 +193,74 @@ you can use uv's `uvx` command to run it directly:
 uvx calk9 --help
 ```
 
+### Nix
+
+Calkit ships a [flake](https://nixos.wiki/wiki/Flakes) at the root of
+its repo, so [Nix](https://nixos.org/) users can pull the CLI into their
+environments alongside their other tools.
+
+Run it ad hoc without installing:
+
+```sh
+nix run github:calkit/calkit -- --help
+```
+
+Drop into a shell that has `calkit`, `git`, and `uv` on `PATH`:
+
+```sh
+nix shell github:calkit/calkit
+```
+
+Add it to your own `flake.nix` as an input:
+
+```nix
+{
+  inputs.calkit.url = "github:calkit/calkit";
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+  outputs = { self, nixpkgs, calkit }: {
+    devShells.x86_64-linux.default =
+      nixpkgs.legacyPackages.x86_64-linux.mkShell {
+        packages = [ calkit.packages.x86_64-linux.default ];
+      };
+  };
+}
+```
+
+Then `nix develop` will give you a shell with the Calkit CLI ready to
+use. To pin a specific Calkit release inside the shell, set the
+`CALKIT_VERSION` environment variable (e.g. `CALKIT_VERSION=0.41.0`)
+before invoking `calkit`.
+
+The flake is currently a thin wrapper around `uvx --from calkit-python
+calkit`. It depends on `uv` from `nixpkgs` and fetches the published
+wheel from PyPI on first use. This trades a fully Nix-native build for
+zero version-drift maintenance, and avoids the macOS `docx2pdf` /
+`appscript` and JupyterLab labextension build issues that block a pure
+nixpkgs derivation today. If you want a fully nixpkgs-native build,
+see the community [`calkit-nix`](https://github.com/dwinkler1/calkit-nix)
+flake.
+
+Nix isn't supported natively on Windows; run Calkit inside
+[WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and use
+the flake there.
+
+### Running against a specific version
+
+If a project requires a Calkit version other than the one you have
+installed, use the top-level `--use-version` flag to re-invoke the CLI
+under that release without changing your installation:
+
+```sh
+calkit --use-version 0.38 run
+```
+
+This re-execs the CLI via `uvx --from calkit-python@<version> calkit`,
+so it requires [uv](https://docs.astral.sh/uv/) on `PATH`.
+You can also declare a minimum version in `calkit.yaml`;
+see
+[Pinning the Calkit CLI version](https://docs.calkit.org/dependencies.md#pinning-the-calkit-cli-version).
+
 ### Calkit Assistant
 
 For Windows users, the

{calkit_python-0.40.1 → calkit_python-0.41.0}/README.md

@@ -134,6 +134,74 @@ you can use uv's `uvx` command to run it directly:
 uvx calk9 --help
 ```
 
+### Nix
+
+Calkit ships a [flake](https://nixos.wiki/wiki/Flakes) at the root of
+its repo, so [Nix](https://nixos.org/) users can pull the CLI into their
+environments alongside their other tools.
+
+Run it ad hoc without installing:
+
+```sh
+nix run github:calkit/calkit -- --help
+```
+
+Drop into a shell that has `calkit`, `git`, and `uv` on `PATH`:
+
+```sh
+nix shell github:calkit/calkit
+```
+
+Add it to your own `flake.nix` as an input:
+
+```nix
+{
+  inputs.calkit.url = "github:calkit/calkit";
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+  outputs = { self, nixpkgs, calkit }: {
+    devShells.x86_64-linux.default =
+      nixpkgs.legacyPackages.x86_64-linux.mkShell {
+        packages = [ calkit.packages.x86_64-linux.default ];
+      };
+  };
+}
+```
+
+Then `nix develop` will give you a shell with the Calkit CLI ready to
+use. To pin a specific Calkit release inside the shell, set the
+`CALKIT_VERSION` environment variable (e.g. `CALKIT_VERSION=0.41.0`)
+before invoking `calkit`.
+
+The flake is currently a thin wrapper around `uvx --from calkit-python
+calkit`. It depends on `uv` from `nixpkgs` and fetches the published
+wheel from PyPI on first use. This trades a fully Nix-native build for
+zero version-drift maintenance, and avoids the macOS `docx2pdf` /
+`appscript` and JupyterLab labextension build issues that block a pure
+nixpkgs derivation today. If you want a fully nixpkgs-native build,
+see the community [`calkit-nix`](https://github.com/dwinkler1/calkit-nix)
+flake.
+
+Nix isn't supported natively on Windows; run Calkit inside
+[WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and use
+the flake there.
+
+### Running against a specific version
+
+If a project requires a Calkit version other than the one you have
+installed, use the top-level `--use-version` flag to re-invoke the CLI
+under that release without changing your installation:
+
+```sh
+calkit --use-version 0.38 run
+```
+
+This re-execs the CLI via `uvx --from calkit-python@<version> calkit`,
+so it requires [uv](https://docs.astral.sh/uv/) on `PATH`.
+You can also declare a minimum version in `calkit.yaml`;
+see
+[Pinning the Calkit CLI version](https://docs.calkit.org/dependencies.md#pinning-the-calkit-cli-version).
+
 ### Calkit Assistant
 
 For Windows users, the

{calkit_python-0.40.1 → calkit_python-0.41.0}/calkit/__init__.py

@@ -15,6 +15,7 @@ if TYPE_CHECKING:
         conda,
         config,
         datasets,
+        dependencies,
         detect,
         docker,
         dvc,
@@ -23,6 +24,7 @@ if TYPE_CHECKING:
         git,
         github,
         gui,
+        install,
         invenio,
         julia,
         jupyter,
@@ -67,9 +69,11 @@ _SUBMODULES = {
     "pipeline",
     "matlab",
     "datasets",
+    "dependencies",
     "detect",
     "docker",
     "gui",
+    "install",
     "magics",
     "ops",
     "server",

calkit_python-0.41.0/calkit/cli/__init__.py

@@ -0,0 +1,53 @@
+from .core import *  # noqa: F403
+
+
+def run() -> None:
+    # Intercept ``--use-version`` before Typer/Click parses argv: Click
+    # processes eager options like ``--help`` and ``--version`` (and the
+    # group's ``no_args_is_help``) ahead of the callback body, so an
+    # invocation like ``calkit --use-version 0.1.1 -- --help`` would
+    # otherwise print the *current* CLI's help instead of re-execing
+    # under the requested version.
+    _maybe_exec_with_version()
+    from .main import app
+
+    app()
+
+
+def _maybe_exec_with_version() -> None:
+    import sys
+
+    # Only scan the group's option region -- the tokens before the first
+    # subcommand (or the ``--`` end-of-options marker). A ``--use-version``
+    # buried in a forwarded arg (e.g. ``calkit xenv -- some-tool
+    # --use-version 1.0``) must not trigger a re-exec.
+    argv = sys.argv[1:]
+    version_spec: str | None = None
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a == "--":
+            break
+        if not a.startswith("-"):
+            # First non-option token is the subcommand name; stop here.
+            break
+        if a == "--use-version" and i + 1 < len(argv):
+            version_spec = argv[i + 1]
+            break
+        if a.startswith("--use-version="):
+            version_spec = a.split("=", 1)[1]
+            break
+        # Skip past an option's value when it takes one (heuristic: a
+        # following token that doesn't itself look like a flag). Worst
+        # case we treat a flag-with-no-value as one with one, which only
+        # affects where the loop terminates -- the outer ``break``s above
+        # still fire first if --use-version is present.
+        if i + 1 < len(argv) and not argv[i + 1].startswith("-"):
+            i += 2
+        else:
+            i += 1
+    if not version_spec:
+        return
+    from .main.core import _exec_with_version
+
+    _exec_with_version(version_spec)

{calkit_python-0.40.1 → calkit_python-0.41.0}/calkit/cli/check.py

@@ -14,10 +14,10 @@ import dotenv
 import typer
 
 import calkit
-from calkit.cli import raise_error, warn
+from calkit.cli import AliasGroup, raise_error, warn
 from calkit.core import get_md5
 
-check_app = typer.Typer(no_args_is_help=True)
+check_app = typer.Typer(cls=AliasGroup, no_args_is_help=True)
 
 
 def _juliaup_version_installed(julia_version: str) -> bool:
@@ -231,6 +231,61 @@ def _check_julia_env(
     return lock_fpath or os.path.join(env_dir, "Manifest.toml")
 
 
+def _require_nix_available() -> None:
+    """Ensure the ``nix`` CLI is on PATH, with a friendly error otherwise.
+
+    On Windows we steer users to WSL2 rather than attempting native Nix,
+    which isn't officially supported.
+    """
+    if shutil.which("nix") is not None:
+        return
+    if _platform.system() == "Windows":
+        raise_error(
+            "Nix is not available natively on Windows. Run Calkit inside "
+            "WSL2 (https://learn.microsoft.com/en-us/windows/wsl/install) "
+            "and install Nix there."
+        )
+    raise_error(
+        "The 'nix' command was not found. Install it with "
+        "'calkit install nix' or from https://nixos.org/download."
+    )
+
+
+def check_nix_env(env: dict, verbose: bool = False) -> str:
+    """Materialize / refresh ``flake.lock`` next to the flake.
+
+    Running ``nix flake lock`` writes ``flake.lock`` if missing and is a
+    no-op when the lock is already up-to-date. The lock file is what we
+    track as a DVC dep, so an out-of-date lock invalidates dependent
+    stages on the next ``calkit run``.
+    """
+    env_path = env.get("path")
+    if env_path is None:
+        raise_error("Nix environments require a path pointing to flake.nix")
+    assert isinstance(env_path, str)
+    if os.path.basename(env_path) != "flake.nix":
+        raise_error("Nix environments require a path pointing to flake.nix")
+    if not os.path.isfile(env_path):
+        raise_error(f"Nix flake not found: {env_path}")
+    _require_nix_available()
+    env_dir = os.path.dirname(os.path.abspath(env_path)) or "."
+    cmd = [
+        "nix",
+        "--extra-experimental-features",
+        "nix-command flakes",
+        "flake",
+        "lock",
+    ]
+    if verbose:
+        typer.echo(f"Running command: {cmd} (cwd={env_dir})")
+    try:
+        subprocess.check_call(cmd, cwd=env_dir)
+    except subprocess.CalledProcessError:
+        raise_error("Failed to lock Nix flake")
+    lock_fpath = os.path.join(os.path.dirname(env_path), "flake.lock")
+    return lock_fpath
+
+
 @check_app.command(name="repro")
 def check_repro(
     wdir: Annotated[
@@ -412,6 +467,8 @@ def check_environment(
         # env config so DVC stages that depend on the env get invalidated
         # when the config changes.
         write_scheduler_env_lock(env_name=env_name, env=env)
+    elif env["kind"] == "nix":
+        check_nix_env(env=env, verbose=verbose)
     else:
         raise_error(f"Environment kind '{env['kind']}' not supported")
     return get_env_lock_fpath(env=env, env_name=env_name, as_posix=False)
@@ -1243,20 +1300,31 @@ def check_matlab_env(
     )
 
 
-@check_app.command(name="dependencies")
-@check_app.command(name="deps")
+@check_app.command(name="deps|dependencies")
 def check_dependencies(
     verbose: Annotated[
         bool, typer.Option("--verbose", "-v", help="Print verbose output")
     ] = False,
+    no_cache: Annotated[
+        bool,
+        typer.Option(
+            "--no-cache",
+            help=(
+                "Re-probe every setup dependency, ignoring (and clearing) "
+                "the cache at .calkit/local/dep-checks.sqlite."
+            ),
+        ),
+    ] = False,
 ) -> None:
     """Check that a project's system-level dependencies are set up
     correctly.
     """
     typer.echo("Checking project dependencies")
     dotenv.load_dotenv(dotenv_path=".env", verbose=verbose)
+    if no_cache:
+        calkit.dependencies.cache_clear()
     try:
-        calkit.check_system_deps()
+        calkit.check_system_deps(use_cache=not no_cache)
     except Exception as e:
         raise_error(str(e))
     message = "✅ All set!"
@@ -1278,32 +1346,22 @@ def check_env_vars(
     for name in env_var_dep_names:
         if verbose:
             typer.echo(f"Checking for environmental variable '{name}'")
-        attrs = {}
+        # Pull the dep's attrs to honor any per-var default.
+        attrs: dict = {}
         for dep in deps:
-            if isinstance(dep, dict) and "name" in dep:
+            if isinstance(dep, dict) and dep.get("name") == name:
                 attrs = dep
                 break
-            elif isinstance(dep, dict) and list(dep.keys()) == [name]:
-                attrs = dep[name]
+            if isinstance(dep, dict) and list(dep.keys()) == [name]:
+                attrs = dep[name] or {}
                 break
         if name not in os.environ:
             typer.echo(f"Missing env var '{name}'")
-            if "default" in attrs:
-                default = attrs["default"]
-            else:
-                default = None
-            value = typer.prompt(
-                f"Enter a value for {name}", default=default, type=str
-            )
-            dotenv.set_key(
-                dotenv_path=".env", key_to_set=name, value_to_set=value
+            value = calkit.dependencies.prompt_and_store_env_var(
+                name, default=attrs.get("default")
             )
-    # Ensure that .env is ignored by git
-    repo = calkit.git.get_repo()
-    if not repo.ignored(".env"):
-        typer.echo("Adding .env to .gitignore")
-        with open(".gitignore", "a") as f:
-            f.write("\n.env\n")
+            if value is None:
+                raise_error(f"No value provided for '{name}'")
     message = "✅ All set!"
     calkit.echo(message)
 

{calkit_python-0.40.1 → calkit_python-0.41.0}/calkit/cli/list.py

@@ -98,6 +98,34 @@ def list_templates():
             typer.echo(f"{kind}/{name}")
 
 
+@list_app.command(name="installers")
+def list_installers():
+    """List apps with a registered native installer.
+
+    These can be declared as ``kind: app`` dependencies in ``calkit.yaml``
+    and Calkit will offer to install them via ``calkit install <name>`` or
+    automatically during ``calkit run`` on an interactive TTY.
+    """
+    # Group entries that share the same underlying installer (e.g.,
+    # ``cargo``/``rustup``, ``julia``/``juliaup``) so the listing reflects
+    # the alias relationship rather than implying separate scripts.
+    groups: dict[int, list[str]] = {}
+    for name, entry in calkit.install.INSTALLERS.items():
+        groups.setdefault(id(entry), []).append(name)
+    for names in groups.values():
+        names.sort()
+        canonical = names[0]
+        entry = calkit.install.INSTALLERS[canonical]
+        aliases = ", ".join(names[1:])
+        header = canonical + (f"  (aliases: {aliases})" if aliases else "")
+        typer.echo(header)
+        for platform in ("unix", "windows"):
+            ins = entry.get(platform)  # type: ignore[arg-type]
+            if ins is None:
+                continue
+            typer.echo(f"  {platform}: {ins['script']}")
+
+
 @list_app.command(name="procedures")
 def list_procedures():
     """List procedures in the current project."""

{calkit_python-0.40.1 → calkit_python-0.41.0}/calkit/cli/main/core.py

@@ -111,10 +111,63 @@ def main(
         bool,
         typer.Option("--version", help="Show version and exit."),
     ] = False,
+    use_version: Annotated[
+        Optional[str],
+        typer.Option(
+            "--use-version",
+            help=(
+                "Re-invoke the CLI under a specific calkit-python version "
+                "via 'uvx --from'."
+            ),
+        ),
+    ] = None,
 ):
     if version:
         typer.echo(f"Calkit {calkit.__version__}")
         raise typer.Exit()
+    if use_version:
+        _exec_with_version(use_version)
+
+
+def _exec_with_version(version_spec: str) -> None:
+    """Replace this process with ``uvx --from calkit-python<spec> calkit ...``.
+
+    Strips ``--use-version`` from ``sys.argv`` before re-invoking so the
+    child process doesn't loop. Requires ``uv`` to be available on PATH.
+    """
+    from calkit.dependencies import _format_uvx_from
+
+    if shutil.which("uvx") is None:
+        raise_error(
+            "'--use-version' requires 'uvx' (install uv: "
+            "https://docs.astral.sh/uv/)."
+        )
+    cleaned: list[str] = []
+    argv = sys.argv[1:]
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a == "--use-version":
+            i += 2
+            continue
+        if a.startswith("--use-version="):
+            i += 1
+            continue
+        cleaned.append(a)
+        i += 1
+    # A leading ``--`` was only needed to escape *our* option parser
+    # (e.g. ``ck --use-version 0.3 -- --version``). Forwarding it would
+    # leave the child CLI to interpret it as a positional, so older
+    # versions error with "No such command '--version'".
+    if cleaned and cleaned[0] == "--":
+        cleaned = cleaned[1:]
+    cmd = [
+        "uvx",
+        "--from",
+        _format_uvx_from(version_spec),
+        "calkit",
+    ] + cleaned
+    os.execvp(cmd[0], cmd)
 
 
 @app.command(name="init")
@@ -346,6 +399,17 @@ def get_status(
             calkit.git.get_repo()
         except InvalidGitRepositoryError:
             git.Repo.init()
+        # Likewise, if this isn't a DVC repo, initialize one so the pipeline
+        # can be compiled and its status reported. DVC init requires a Git
+        # repo, which the block above ensures exists.
+        if not os.path.isfile(os.path.join(".dvc", "config")):
+            typer.echo("Initializing DVC repository")
+            try:
+                result = calkit.dvc.run_dvc_command(["init", "-q"])
+                if result != 0:
+                    raise subprocess.CalledProcessError(result, "dvc init")
+            except subprocess.CalledProcessError as e:
+                raise_error(f"Failed to initialize DVC repository: {e}")
     valid_categories = ["project", "git", "dvc", "pipeline"]
     if categories is not None:
         for category in categories:
@@ -2332,6 +2396,44 @@ def run_in_env(
             subprocess.check_call(cmd, cwd=env_dir, env=env_vars)
         except subprocess.CalledProcessError:
             raise_error("Failed to run in renv")
+    elif env["kind"] == "nix":
+        from calkit.cli.check import check_nix_env
+
+        env_path = env.get("path")
+        if env_path is None:
+            raise_error(
+                "Nix environments require a path pointing to flake.nix"
+            )
+        assert isinstance(env_path, str)
+        if os.path.basename(env_path) != "flake.nix":
+            raise_error(
+                "Nix environments require a path pointing to flake.nix"
+            )
+        if not no_check:
+            check_nix_env(env=env, verbose=verbose)
+        env_dir = os.path.dirname(os.path.abspath(env_path)) or "."
+        flake_ref = f"path:{env_dir}"
+        shell_name = env.get("shell")
+        if shell_name:
+            flake_ref = f"{flake_ref}#{shell_name}"
+        shell_cmd = _to_shell_cmd(cmd)
+        nix_cmd = [
+            "nix",
+            "--extra-experimental-features",
+            "nix-command flakes",
+            "develop",
+            flake_ref,
+            "--command",
+            "sh",
+            "-c",
+            shell_cmd,
+        ]
+        if verbose:
+            typer.echo(f"Running command: {nix_cmd}")
+        try:
+            subprocess.check_call(nix_cmd, cwd=wdir)
+        except subprocess.CalledProcessError:
+            raise_error("Failed to run in Nix environment")
     elif env["kind"] == "matlab":
         if not no_check:
             check_matlab_env(
@@ -2379,6 +2481,55 @@ def run_in_env(
         raise_error("Environment kind not supported")
 
 
+@app.command(
+    name="install",
+    help=(
+        "Install a registered native dependency (e.g., pixi, uv) via its "
+        "upstream installer for the current platform."
+    ),
+)
+def install_app(
+    name: Annotated[
+        str,
+        typer.Argument(
+            help="The app to install (e.g., 'pixi', 'uv').",
+        ),
+    ],
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "--yes",
+            "-y",
+            help="Skip the confirmation prompt and install immediately.",
+        ),
+    ] = False,
+) -> None:
+    from calkit import install as _install
+
+    # Surface a platform-specific "use X instead" message before the
+    # generic "no installer" error -- e.g., Nix on Windows needs WSL2.
+    unsupported = _install.get_unsupported_message(name)
+    if unsupported:
+        raise_error(unsupported)
+    entry = _install.get_installer(name)
+    if entry is None:
+        raise_error(
+            f"No registered installer for '{name}'. Known apps: "
+            + ", ".join(sorted(_install.INSTALLERS))
+        )
+    # ``--yes`` makes this scriptable (CI, provisioning) without losing
+    # the safety prompt for plain interactive use.
+    if yes:
+        ok = _install.install(name)
+    else:
+        from calkit.dependencies import _is_interactive
+
+        ok = _install.prompt_and_install(name, interactive=_is_interactive())
+    if not ok:
+        raise_error(f"Failed to install '{name}'")
+    typer.echo(f"✅ Installed '{name}'")
+
+
 @app.command(name="xproc|runproc", help="Execute a procedure.")
 def run_procedure(
     name: Annotated[str, typer.Argument(help="The name of the procedure.")],