calkit-python 0.45.0__tar.gz → 0.45.2__tar.gz

calkit_python-0.45.2/AGENTS.md

@@ -0,0 +1,67 @@
+# 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.

calkit_python-0.45.2/PKG-INFO

@@ -0,0 +1,411 @@
+Metadata-Version: 2.5
+Name: calkit-python
+Version: 0.45.2
+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](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 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/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.45.2/calkit/__init__.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from importlib.metadata import version as _version
+from typing import TYPE_CHECKING
+
+__version__ = _version("calkit-python")
+
+from .core import *  # noqa: F403, I001
+
+if TYPE_CHECKING:
+    from calkit import (  # noqa: F401
+        calc,
+        conda,
+        config,
+        datasets,
+        dependencies,
+        detect,
+        docker,
+        dvc,
+        environments,
+        fs,
+        git,
+        github,
+        gui,
+        hub,
+        install,
+        invenio,
+        julia,
+        jupyter,
+        licenses,
+        magics,
+        matlab,
+        models,
+        notebooks,
+        office,
+        ops,
+        overleaf,
+        pipeline,
+        procedures,
+        provenance,
+        releases,
+        reproducibility,
+        resources,
+        schema,
+        server,
+        templates,
+    )
+
+    from .notebooks import declare_notebook  # noqa: F401
+
+# Lazy-load submodules to speed up imports
+_SUBMODULES = {
+    "git",
+    "dvc",
+    "hub",
+    "fs",
+    "jupyter",
+    "config",
+    "models",
+    "office",
+    "templates",
+    "conda",
+    "calc",
+    "procedures",
+    "provenance",
+    "reproducibility",
+    "github",
+    "invenio",
+    "releases",
+    "resources",
+    "licenses",
+    "overleaf",
+    "julia",
+    "notebooks",
+    "environments",
+    "pipeline",
+    "matlab",
+    "datasets",
+    "dependencies",
+    "detect",
+    "docker",
+    "gui",
+    "install",
+    "magics",
+    "ops",
+    "schema",
+    "server",
+}
+
+
+def __getattr__(name: str):
+    if name in _SUBMODULES:
+        import importlib
+
+        mod = importlib.import_module(f"calkit.{name}")
+        globals()[name] = mod
+        return mod
+    if name == "declare_notebook":
+        from .notebooks import declare_notebook
+
+        globals()["declare_notebook"] = declare_notebook
+        return declare_notebook
+    raise AttributeError(f"module 'calkit' has no attribute {name!r}")
+
+
+def _jupyter_labextension_paths():
+    return [{"src": "labextension", "dest": "calkit"}]
+
+
+def _jupyter_server_extension_points():
+    return [{"module": "calkit"}]
+
+
+def _load_jupyter_server_extension(server_app):
+    """Registers the API handler to receive HTTP requests from the frontend
+    extension.
+
+    Parameters
+    ----------
+    server_app: jupyterlab.labapp.LabApp
+        JupyterLab application instance
+    """
+    import os
+
+    from .jupyterlab.routes import setup_route_handlers
+
+    # Change to root_dir so all handlers work in the correct directory context
+    root_dir = server_app.root_dir
+    os.chdir(root_dir)
+    server_app.log.info(f"Changed working directory to {root_dir}")
+    setup_route_handlers(server_app.web_app)
+    name = "calkit"
+    server_app.log.info(f"Registered {name} server extension")