calkit-python 0.41.23__tar.gz → 0.41.25__tar.gz

calkit_python-0.41.25/.dockerignore

@@ -0,0 +1,26 @@
+# The hub backend image builds with this directory as its context so it can
+# install the calkit-python workspace member; keep everything it doesn't need
+# out of the context
+.git
+.venv
+.env
+**/__pycache__
+*.pyc
+**/.mypy_cache
+**/.pytest_cache
+**/node_modules
+**/.venv
+.coverage
+coverage.xml
+htmlcov
+dist
+site
+docs
+examples
+test
+calk9
+jupyterlab-ext
+vscode-ext
+hub/frontend
+hub/texmf-proxy
+hub/node_modules

calkit_python-0.41.25/.gitignore

@@ -0,0 +1,27 @@
+dev.ipynb
+*.pyc
+.DS_Store
+.vscode/settings.json
+site
+.env
+.venv
+.coverage*
+coverage.xml
+import.log
+tsconfig.tsbuildinfo
+jupyterlab-ext/lib
+node_modules
+.yarn
+*.eslintcache
+*.stylelintcache
+calkit/labextension
+coverage
+junit.xml
+calk9
+dist
+*.vsix
+vscode-ext/out
+.claude
+TODO.md
+**/__pycache__/
+CLAUDE.md

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

@@ -0,0 +1,52 @@
+# 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:
+  - 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
+      - id: end-of-file-fixer
+        exclude: ^hub/frontend/src/client/
+      - id: trailing-whitespace
+        exclude: ^hub/frontend/src/client/
+      - 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
+        exclude: calkit|^hub/
+
+  - 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.41.25/Makefile

@@ -0,0 +1,81 @@
+.PHONY: help
+help: ## Show this help.
+	@uv run python -c "import re; \
+	[[print(f'\033[36m{m[0]:<20}\033[0m {m[1]}') for m in re.findall(r'^([a-zA-Z_-]+):.*?## (.*)$$', open(makefile).read(), re.M)] for makefile in ('$(MAKEFILE_LIST)').strip().split()]"
+
+.PHONY: install
+install: ## Create the project's virtual environment.
+	@echo "🚀 Creating virtual environment"
+	@uv sync
+
+.PHONY: dev
+dev: ## Start up the hub containers for development.
+	@$(MAKE) -C hub dev
+
+.PHONY: frontend-client
+frontend-client: ## Regenerate the hub frontend's API client.
+	@$(MAKE) -C hub/frontend client
+
+.PHONY: format
+format: sync-docs ## Automatically format files.
+	@echo "🚀 Linting code with pre-commit"
+	@uv run pre-commit run -a
+
+.PHONY: check
+check: format ## Run code quality tools.
+	@echo "🚀 Checking lock file consistency with 'pyproject.toml'"
+	@uv lock --locked
+	@echo "🚀 Static type checking with mypy"
+	@uv run --all-packages mypy
+	@echo "🚀 Checking for obsolete dependencies with deptry"
+	@uv run deptry .
+
+.PHONY: test
+test: ## Test the code with pytest.
+	@echo "🚀 Testing code with pytest"
+	@uv run pytest
+
+.PHONY: test-cov
+test-cov: ## Test the code coverage with pytest.
+	@echo "🚀 Testing code coverage with pytest"
+	@uv run pytest --cov --cov-config=pyproject.toml
+
+.PHONY: test-docs
+test-docs: sync-docs ## Test if documentation can be built without warnings or errors.
+	@uv run mkdocs build -s
+
+.PHONY: sync-docs
+sync-docs: ## Sync documentation content from docs/*.md into README.md.
+	@echo "🚀 Generating docs references"
+	@uv run python scripts/generate-docs-references.py
+	@echo "🚀 Syncing documentation"
+	@uv run python scripts/sync-docs.py
+
+.PHONY: docs
+docs: sync-docs ## Build and serve the documentation.
+	@uv run mkdocs serve --livereload
+
+.PHONY: import-profile
+import-profile: ## Profile the import time of the CLI.
+	uv run python -X importtime -m calkit --help 2> import.log && uvx tuna import.log
+
+.PHONY: jlab-dev
+jlab-dev: ## Develop the JupyterLab extension.
+	cd jupyterlab-ext && uv run jlpm run watch
+
+.PHONY: jlab
+jlab: ## Build the JupyterLab extension.
+	cd jupyterlab-ext && uv run jlpm run build:prod
+
+.PHONY: test-jlab
+test-jlab: ## Run JupyterLab extension unit tests with Jest.
+	@echo "🚀 Running JupyterLab extension unit tests"
+	@cd jupyterlab-ext && uv run jlpm test
+
+.PHONY: test-jlab-ui
+test-jlab-ui: ## Run the JupyterLab UI integration tests.
+	@echo "🚀 Running JupyterLab UI tests with Playwright"
+	@cd jupyterlab-ext && uv run jlpm run build:prod
+	@uv run --directory=jupyterlab-ext/ui-tests jlpm install
+	@uv run --directory=jupyterlab-ext/ui-tests jlpm playwright install
+	@uv run --directory=jupyterlab-ext/ui-tests jlpm playwright test -u --reporter=list

calkit_python-0.41.25/PKG-INFO

@@ -0,0 +1,406 @@
+Metadata-Version: 2.4
+Name: calkit-python
+Version: 0.41.25
+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: pyjwt
+Requires-Dist: python-dotenv>=1
+Requires-Dist: pywin32; platform_system == 'Windows'
+Requires-Dist: requests
+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.25.1
+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](docs/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).
+
+<!-- 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 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 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 -->