calkit-python 0.45.3__tar.gz → 0.47.0__tar.gz

calkit_python-0.47.0/.pre-commit-config.yaml

@@ -0,0 +1,66 @@
+# Python linting/formatting runs the uv-managed ruff over the whole repo
+# with the root pyproject config, so the version and rules can't drift
+# between packages. The hub frontend is formatted by its own pinned Biome
+# to match hub/frontend/biome.json exactly.
+repos:
+  # renv generates renv/activate.R and rewrites it whenever it activates,
+  # trailing whitespace and all. Trimming it here would only make the
+  # committed copy differ from what renv writes, so it is left alone.
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v4.4.0"
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+        exclude: ^docs/overleaf\.md$
+      - id: check-toml
+      # The example projects' results files are stage outputs: a stage
+      # writes them, and a formatted copy is a changed output that makes
+      # the stage stale, so they are left exactly as written. Likewise
+      # .calkit/env-locks, which calkit writes and compares byte for byte.
+      - id: end-of-file-fixer
+        exclude: ^hub/frontend/src/client/|(^|/)renv/activate\.R$|^examples/.*/results/|(^|/)\.calkit/env-locks/
+      - id: trailing-whitespace
+        exclude: ^hub/frontend/src/client/|(^|/)renv/activate\.R$|^examples/.*/results/|(^|/)\.calkit/env-locks/
+      - id: check-yaml
+        args: ["--unsafe"]
+      - id: check-json
+        # The hub has JSONC files (tsconfig.json, .vscode/launch.json)
+        exclude: ^hub/
+
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        language: system
+        entry: bash -c 'uv run ruff check --fix --exit-non-zero-on-fix .'
+        pass_filenames: false
+        files: \.pyi?$
+      - id: ruff-format
+        name: ruff format
+        language: system
+        entry: bash -c 'uv run ruff format .'
+        pass_filenames: false
+        files: \.pyi?$
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: "v3.0.3"
+    hooks:
+      - id: prettier
+        # dvc.yaml and dvc.lock are generated---by calkit and DVC
+        # respectively---and are rewritten wholesale whenever the pipeline
+        # changes. Prettier and ruamel disagree about where a long 'desc:'
+        # value goes, so formatting them here just means the two take turns
+        # reformatting the same file.
+        # Likewise the example projects' results files, which are stage
+        # outputs and have to match what the stage wrote byte for byte.
+        exclude: calkit|^hub/|(^|/)dvc\.(yaml|lock)$|^examples/.*/results/
+
+  - repo: local
+    hooks:
+      - id: biome-format-hub-frontend
+        name: biome format (hub frontend)
+        language: system
+        entry: bash -c 'cd hub/frontend && npx biome format --write ./src'
+        pass_filenames: false
+        files: ^hub/frontend/src/.*\.(jsx?|tsx?|jsonc?|css)$

calkit_python-0.47.0/AGENTS.md

@@ -0,0 +1,69 @@
+# Agent instructions for working on Calkit
+
+## Repo structure
+
+- The main Python package/CLI lives in `calkit`
+- The JupyterLab extension lives in `src`
+- The VS Code extension lives in `vscode-ext`
+- The Chrome extension lives in `browser-ext`
+- GitHub Actions live in `actions`, e.g., `calkit/calkit/actions/run`
+- Config Calkit installs into projects, e.g., the dev container, VS Code, and
+  GitHub Actions configs, lives in `calkit/resources`; see the README there
+  before editing, since some of those files are generated
+
+Be sure to read the `AGENTS.md` file in whatever subproject you're working on,
+if applicable.
+
+## Working
+
+See `CONTRIBUTING.md` for tool usage, style guidelines, etc.
+
+To run tests, use `uv run pytest`.
+
+To sync the docs and format all the code, run `make format`.
+
+Before finishing a change, type-check it. The CLI gate is mypy
+(`uv run mypy <changed files>`, or `make check` for the full suite), and the
+VS Code editor uses Pylance (Pyright). Keep new code clean under both, and do
+not introduce new type errors.
+
+Wrap prose at natural breakpoints in phrases or punctuation to keep max
+line length below 80 characters.
+
+In the docs, MkDocs Material admonitions (`!!! note`, `!!! tip`, etc.) must be
+preceded by a `<!-- prettier-ignore -->` comment. Otherwise Prettier reformats
+the block and strips the 4-space indentation of the admonition body, which
+breaks rendering.
+
+Agents should never make commits to Git.
+
+Prefer tests that include multiple scenarios to comprehensively test
+a feature in one function over many different test functions.
+
+Do not write docstrings in test functions.
+
+Do not put blank lines inside function bodies; separate logical sections with
+comments instead. This only applies to blank lines we write, not ones the
+formatter inserts, e.g., ruff-format adds one after an in-function import
+block. Don't hoist imports to module scope just to avoid those; imports are
+kept inside functions to keep CLI startup fast.
+
+For prose, only use one space after punctuation.
+
+Always put a comma after "i.e." and "e.g.".
+
+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.
+The only exception here is if splitting up a function makes it easier to
+write meaningful unit tests.
+If a function is only used inside one other function, nest it inside the
+caller at the top.
+
+No spaces on either side of en or em dashes used for ranges or pauses in prose,
+respectively.
+
+Never create `helpers` or `utils` modules or packages--tight coupling and
+low cohesion architecture.
+
+Don't be verbose in comments. One sentence is usually fine.

calkit_python-0.47.0/PKG-INFO

@@ -0,0 +1,413 @@
+Metadata-Version: 2.5
+Name: calkit-python
+Version: 0.47.0
+Summary: Reproducibility simplified.
+Project-URL: Homepage, https://calkit.org
+Project-URL: Issues, https://github.com/calkit/calkit/issues
+Project-URL: Repository, https://github.com/calkit/calkit
+Author-email: Pete Bachant <petebachant@gmail.com>
+License-File: LICENSE
+Classifier: Framework :: Jupyter
+Classifier: Framework :: Jupyter :: JupyterLab
+Classifier: Framework :: Jupyter :: JupyterLab :: 4
+Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
+Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: arithmeval
+Requires-Dist: bibtexparser
+Requires-Dist: checksumdir
+Requires-Dist: docx2pdf
+Requires-Dist: dvc[all]==3.67.1
+Requires-Dist: fastapi
+Requires-Dist: fsspec>=2026.4.0
+Requires-Dist: gitpython
+Requires-Dist: json2latex>=0.0.3
+Requires-Dist: jupyterlab>=4.4.5
+Requires-Dist: keyring
+Requires-Dist: nbconvert
+Requires-Dist: papermill>=2.6.0
+Requires-Dist: pathspec<1.0.0
+Requires-Dist: pillow
+Requires-Dist: psutil>=7.0.0
+Requires-Dist: pydantic-settings
+Requires-Dist: pydantic[email]
+Requires-Dist: pygtrie<2.6.0
+Requires-Dist: pyjwt
+Requires-Dist: python-dotenv>=1
+Requires-Dist: pywin32; platform_system == 'Windows'
+Requires-Dist: requests
+Requires-Dist: rich
+Requires-Dist: sqlitedict>=2.1.0
+Requires-Dist: texsoup>=0.3.3
+Requires-Dist: toml>=0.10.2
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: typer==0.27.2
+Requires-Dist: uvicorn
+Provides-Extra: data
+Requires-Dist: pandas>=2.2.3; extra == 'data'
+Requires-Dist: polars>=1.18.0; extra == 'data'
+Provides-Extra: xet
+Requires-Dist: xet>=0.0.1; extra == 'xet'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://calkit.org" target="_blank">
+    <img width="40%" src="docs/img/calkit-no-bg.png" alt="Calkit">
+  </a>
+</p>
+<p align="center">
+  <a href="https://docs.calkit.org" target="_blank">
+    Documentation
+  </a>
+  |
+  <a href="https://docs.calkit.org/tutorials" target="_blank">
+    Tutorials
+  </a>
+  |
+  <a href="https://github.com/orgs/calkit/discussions" target="_blank">
+    Discussions
+  </a>
+</p>
+
+<!-- INCLUDE: docs/index.md -->
+
+Typical research workflows are horizontally-siloed, i.e.,
+various stages--data collection, analysis, writing--are performed in
+disconnected systems,
+turning research into a slow, error-prone, and tedious
+[waterfall](https://en.wikipedia.org/wiki/Waterfall_model) process.
+
+Calkit helps you integrate code, data, figures, results, publications,
+and more into a cohesive, traceable, and portable _knowledge creation system_,
+so every output can be traced back to its source (provenance)
+and reproduced with a single command.
+
+With industry standard tools combined into a unified and simplified experience
+tailored for research,
+you can reap the rewards of reproducibility and automation
+without the cognitive overhead.
+
+<!-- https://docs.google.com/drawings/d/1XMGnbgYYNFAVUBDyUaCyLfRB7efvJdrnrKmFlNmT19o/edit -->
+
+![pipeline](https://docs.calkit.org/img/pipeline.png)
+
+## Features
+
+- A simplified [version control](https://docs.calkit.org/version-control)
+  interface that unifies Git and DVC (Data Version Control),
+  so everything can be kept in the same project repository.
+  This way, code doesn't need to be siloed away from other
+  important artifacts like datasets, models, figures, or article PDFs,
+  allowing you to work on all parts of a project without hopping around to
+  different tools.
+- [Computational environment management](https://docs.calkit.org/environments) with support for many
+  languages and environment managers: Conda, Docker, uv, Julia, Renv, and more.
+  No need to create and update environments on your own. Calkit will handle
+  them as needed.
+- An environment-aware build system or [pipeline](https://docs.calkit.org/pipeline) with
+  a simple declarative syntax and
+  output caching so you don't need to think about which steps or stages
+  need to be rerun after changing any part of the project.
+  Simply call `calkit run`.
+  Compose your pipeline from many different kinds of stages,
+  including simple scripts, commands, Jupyter Notebooks, LaTeX, and more.
+- A complementary self-hostable and GitHub-integrated
+  [hub](https://github.com/calkit/calkit/tree/main/hub)
+  to facilitate backup, collaboration,
+  and sharing throughout the entire research lifecycle.
+- [Overleaf integration](https://docs.calkit.org/overleaf/), so
+  analysis, visualization, and writing can all stay in sync
+  (no more manual uploads!)
+- Support for running on [high performance computing (HPC)](https://docs.calkit.org/hpc) systems
+  that use PBS or SLURM schedulers.
+- Support for automated running with
+  [GitHub Actions](https://docs.calkit.org/tutorials/github-actions).
+- Extensions for doing all of the above graphically in
+  [JupyterLab](https://docs.calkit.org/jupyterlab) and
+  [VS Code](https://marketplace.visualstudio.com/items?itemName=Calkit.calkit-vscode).
+- A [browser extension](https://docs.calkit.org/browser-ext) for collecting references
+  directly to BibTeX (optionally synced with Zotero),
+  viewing DVC-stored files on GitHub,
+  and syncing figures and results with Overleaf directly in Chrome,
+  Microsoft Edge, and more.
+
+<!-- END INCLUDE -->
+
+## Installation
+
+<!-- INCLUDE: docs/installation.md +1 -->
+
+On Linux, macOS, or Windows Git Bash,
+install Calkit and [uv](https://docs.astral.sh/uv/)
+(if not already installed) with:
+
+```sh
+curl -LsSf install.calkit.org | sh
+```
+
+Or with Windows Command Prompt or PowerShell:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm install-ps1.calkit.org | iex"
+```
+
+If you already have uv installed, install Calkit with:
+
+```sh
+uv tool install calkit-python
+```
+
+You can also install with your system Python:
+
+```sh
+pip install calkit-python
+```
+
+To effectively use Calkit, you'll want to ensure [Git](https://git-scm.com)
+is installed and properly configured.
+You may also want to install [Docker](https://docker.com),
+since that is the default method by which LaTeX environments are created.
+If you want to use a [Calkit hub](https://docs.calkit.org/hub)
+for collaboration and backup as a DVC remote,
+you can [connect to the hub](https://docs.calkit.org/hub) with:
+
+```sh
+calkit hub login
+```
+
+If you use AI agents like Claude, Copilot, or Codex,
+see [AI tools](https://docs.calkit.org/ai-tools)
+to learn how to install agent skills for working with Calkit.
+
+### Use without installing
+
+If you want to use Calkit without installing it,
+you can use uv's `uvx` command to run it directly:
+
+```sh
+uvx ck9 --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/requirements.md#pinning-the-calkit-cli-version).
+
+### Calkit Assistant
+
+For Windows users, the
+[Calkit Assistant](https://github.com/calkit/calkit-assistant)
+app is the easiest way to get everything set up and ready to work in
+VS Code, which can then be used as the primary app for working on
+all scientific or analytical computing projects.
+
+![Calkit Assistant](https://github.com/calkit/calkit-assistant/blob/main/resources/screenshot.png?raw=true)
+
+<!-- END INCLUDE -->
+
+## Quickstart
+
+<!-- INCLUDE: docs/quickstart.md +1 -->
+
+<!-- prettier-ignore -->
+!!! note
+    `ck` is an abbreviated alias for the `calkit` executable.
+    All `calkit` commands can be run as `ck` instead, e.g., `ck save -am "..."`.
+
+### From an existing project
+
+If you want to use Calkit with an existing project,
+navigate into its working directory and use the `xr` command to start
+executing and recording your scripts, notebooks, LaTeX files, etc.,
+as reproducible pipeline stages.
+For example:
+
+```sh
+calkit xr scripts/analyze.py
+
+calkit xr notebooks/plot.ipynb
+
+calkit xr paper/main.tex
+```
+
+Calkit will attempt to detect environments, inputs, and outputs and
+save them in `calkit.yaml`.
+If successful,
+you'll be able to run the full pipeline with:
+
+```sh
+calkit run
+```
+
+Next, make a change to e.g., a script and look at the output of
+`calkit status`.
+You'll see that the pipeline has a stage that is out-of-date:
+
+```sh
+---------------------------- Pipeline ----------------------------
+analyze:
+        changed deps:
+                modified:           scripts/analyze.py
+```
+
+This can be fixed with another call to `calkit run`.
+
+You can save (add and commit) all changes with:
+
+```sh
+calkit save -am "Add to pipeline"
+```
+
+### Fresh from a Calkit project template
+
+Create a new project from the
+[`calkit/example-basic`](https://github.com/calkit/example-basic)
+template with:
+
+```sh
+calkit new project my-research \
+    --title "My research" \
+    --template calkit/example-basic \
+    --hub
+```
+
+Note the `--hub` flag requires [a hub connection](https://docs.calkit.org/hub)
+to be set up, but can be omitted if the project doesn't need to be backed up to
+the hub or shared with collaborators.
+Hub integration can also be set up later.
+
+Next, move into the project folder and run the pipeline,
+which consists of several stages defined in `calkit.yaml`:
+
+<!-- TODO: This takes a long time to pull the image -->
+
+```sh
+cd my-research
+calkit run
+```
+
+Next, make some edits to a script or LaTeX file and run `calkit status` to
+see what stages are out-of-date.
+For example:
+
+```sh
+---------------------------- Pipeline ----------------------------
+build-paper:
+        changed deps:
+                modified:           paper/paper.tex
+```
+
+Execute `calkit run` again to bring everything up-to-date.
+
+To back up or save the project, call:
+
+```sh
+calkit save -am "Run pipeline"
+```
+
+### With an AI coding agent
+
+Simply tell the [AI agent](https://docs.calkit.org/ai-tools):
+
+> Turn this folder into a Calkit project
+
+or
+
+> Create me a new Calkit project for investigating...
+
+<!-- END INCLUDE -->
+
+## Get involved
+
+We welcome all kinds of contributions!
+See [CONTRIBUTING.md](CONTRIBUTING.md) to learn how to get involved.
+
+## Acknowledgements
+
+<!-- INCLUDE: docs/acknowledgements.md +1 -->
+
+Calkit is supported by the
+[Caltech Schmidt Academy of Software Engineering](https://sase.caltech.edu).
+
+<p align="center">
+  <a href="https://sase.caltech.edu" target="_blank">
+    <img width="40%" src="docs/img/caltech.png" alt="Caltech SASE">
+  </a>
+<a href="https://schmidtsciences.org/" target="_blank">
+    <img width="40%" src="docs/img/schmidt-sciences.png" alt="Schmidt Sciences">
+  </a>
+</p>
+
+<!-- END INCLUDE -->

calkit_python-0.47.0/actions/run/README.md

@@ -0,0 +1,119 @@
+# Calkit run GitHub Action
+
+A GitHub Action to run a Calkit project's pipeline and optionally save results
+(commit and push) to Git and DVC.
+
+The action lives in the Calkit repo because it's a thin wrapper around a
+sequence of CLI commands, and it reads `calkit list environments` output to
+decide what tooling to install.
+Keeping it here means a change to either is tested against the other before
+release.
+
+## Usage
+
+Reference the action by a Calkit release tag:
+
+```yaml
+- uses: calkit/calkit/actions/run@v0.43.0
+```
+
+The easiest way to add it to a project is:
+
+```sh
+calkit update github-actions
+```
+
+which writes the workflow below to `.github/workflows/run-calkit.yml`,
+pinned to the version of Calkit that wrote it.
+Rerun it after upgrading Calkit to move the pin.
+
+<!-- Do not edit the snippet below since it is automatically populated -->
+<!-- snippet:example.yml:start -->
+
+```yaml
+name: Run pipeline
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+  # Lets Docker environments configured with a registry push the images they
+  # build to the GitHub Container Registry, so later runs pull instead of
+  # rebuilding
+  packages: write
+
+# Make sure we only ever run one per branch so we don't have issues pushing
+# after running the pipeline
+concurrency:
+  group: calkit-run-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  main:
+    name: Run
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # For PRs, checkout the head ref to avoid detached HEAD
+          ref: ${{ github.head_ref || github.ref_name }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Configure Git credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      # This action automatically runs necessary setup steps based on environments
+      - name: Run Calkit
+        uses: calkit/calkit/actions/run@main
+```
+
+<!-- snippet:example.yml:end -->
+
+Note the permissions, concurrency, and checkout options.
+The action detects required environment kinds from `calkit.yaml` and sets up
+needed tooling (for example Calkit via `uv`, Julia, Pixi, Conda, R, MATLAB,
+and Docker Buildx) before running.
+
+## Configuration
+
+If simply running the pipeline is desired, the `save` option can be set to
+`false`.
+Additionally, caching DVC data can be disabled with `cache_dvc: false`.
+When caching is enabled, the action saves DVC cache entries using the current
+branch name plus the current commit SHA.
+The restore step first looks for the
+most recent cache for the current branch and then falls back to the default
+branch cache if the current branch cache doesn't exist yet.
+
+## System dependencies
+
+System dependencies like `uv`, `pixi`, `conda`, `juliaup` will be installed
+automatically if missing, and if the project has an environment with the
+corresponding kind.
+If you'd like control over which versions are used, you can add setup steps
+before the Calkit Action, and Calkit will detect and skip installation.
+
+## Development
+
+`example.yml` is the source for both the snippet above and the copy bundled
+into the Python package at `calkit/resources/github-actions`.
+After editing it, run `make sync-resources`.
+
+CI runs the action against real example projects on every pull request that
+touches this directory, with Calkit installed from the working tree first, so
+the action exercises the CLI being changed rather than the last release.
+
+## Previous home
+
+This action was previously published from
+[`calkit/run-action`](https://github.com/calkit/run-action), which is no
+longer maintained.
+Workflows referencing `calkit/run-action@v2` still work, but should be
+updated to `calkit/calkit/actions/run@<version>`, which
+`calkit update github-actions` will do in place.