calkit-python 0.41.24__tar.gz → 0.42.0__tar.gz

calkit_python-0.42.0/.dockerignore

@@ -0,0 +1,29 @@
+# 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 is deliberately NOT excluded: hatch-vcs reads the release tags out of
+# it to version calkit-python and the hub backend at install time. It is
+# bind-mounted into the one RUN that needs it, so it never lands in a layer.
+.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.42.0/.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.42.0/.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.42.0/.prettierignore

@@ -0,0 +1,10 @@
+node_modules
+**/node_modules
+**/lib
+**/package.json
+calkit
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.venv
+browser-ext/dist

calkit_python-0.42.0/AGENTS.md

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

calkit_python-0.42.0/CONTRIBUTING.md

@@ -0,0 +1,131 @@
+# Contributing to Calkit
+
+Thank you for considering contributing to Calkit!
+We welcome contributions of all kinds, including code, documentation,
+bug reports, and feature suggestions.
+This guide will help you get started.
+
+## 🛠 How to contribute
+
+### 1. Find an issue to work on
+
+- Check the **[backlog](https://github.com/orgs/calkit/projects/1/views/1)**
+  for issues that are ready to be worked on.
+- Look for issues labeled `good first issue` if you're new.
+- If you have an idea, open a new issue and discuss it before coding.
+
+### 2. Set up your development environment
+
+1. [**Fork** the repository](https://github.com/calkit/calkit/fork).
+1. **Clone** your fork locally:
+   ```bash
+   git clone https://github.com/{your-username}/calkit.git
+   cd calkit
+   ```
+1. **Install system-level dependencies:**
+   - [Docker](https://docker.com)
+   - [Miniforge](https://conda-forge.org/download/)
+   - [uv](https://docs.astral.sh/uv/getting-started/installation/)
+   - [Pixi](https://pixi.sh/latest/)
+1. **Run tests** to ensure everything is working:
+   ```bash
+   uv run pytest
+   ```
+1. Install the Calkit CLI in dev mode:
+   ```sh
+   uv tool install -e .
+   ```
+1. Install the JupyterLab extension in development mode
+   (if working on the JupyterLab extension):
+   ```sh
+   uv run jupyter labextension develop . --overwrite
+   ```
+1. Start the JupyterLab extension TypeScript compiler in watch mode
+   (if working on the JupyterLab extension):
+   ```sh
+   make jlab-dev
+   ```
+1. Start JupyterLab:
+   ```sh
+   uv run jupyter lab
+   ```
+1. **Set up pre-commit hooks** to auto-enforce code style standards:
+   ```bash
+   uv tool install prek
+   prek install
+   ```
+   This will run automated checks before each commit.
+
+### 3. Make your changes
+
+- Create a new branch:
+  ```bash
+  git checkout -b your-feature-name
+  ```
+- Fix automatically-checked formatting issues:
+  ```bash
+  make format
+  ```
+- Follow style guidelines not automatically checked:
+  - No blank lines inside functions/methods
+  - Type hints required for all functions
+  - NumPy-style docstrings
+- Commit your changes
+  (use the imperative mood and capitalize the first letter,
+  but don't use punctuation):
+  ```bash
+  git add .
+  git commit -m "Short description of your change"
+  ```
+- Push your branch:
+  ```bash
+  git push origin your-feature-name -u
+  ```
+
+### 4. Submit a pull request (PR)
+
+- Open a **Pull request** on GitHub.
+- Link the PR to the issue it resolves by adding "resolves #{issue number}"
+  to the description.
+- Wait for a review and make necessary changes.
+
+## Releasing the browser extension
+
+Publishing a GitHub release tagged `browser-ext/vX.Y.Z` builds and tests the
+extension, stamps that version into `manifest.json` and `package.json`,
+strips source maps, and attaches a store-ready zip to the release.
+The version comes from the tag because the Chrome Web Store rejects an
+upload whose manifest version isn't higher than the last one, and a version
+kept in sync by hand eventually isn't.
+Uncheck "set as the latest release" for these, since they aren't
+calkit-python releases.
+
+The same workflow uploads to the Chrome Web Store once the
+`CHROME_EXTENSION_ID` repository variable is set, using the
+`CHROME_CLIENT_ID`, `CHROME_CLIENT_SECRET`, and `CHROME_REFRESH_TOKEN`
+secrets (an OAuth client for the Web Store API, authorized for the
+publishing account).
+Until that variable exists the upload step is skipped and the zip on the
+release is uploaded by hand.
+
+`make browser-ext` builds and packages the same zip locally.
+The packaged manifest drops the local development hub's host permission,
+which is why it is built from a staged copy rather than from `dist`, the
+directory loaded unpacked during development.
+The store listing's text lives in `browser-ext/store/listing.md`, and its
+screenshots are generated from `docs/img/browser-ext` by
+`browser-ext/scripts/store-screenshots.py`.
+
+## 💡 Other ways to contribute
+
+- **Report bugs**: Open an issue with detailed reproduction steps.
+- **Improve documentation**: Help us make Calkit's docs better.
+- **Suggest features**: Share your ideas for improvements.
+
+## 🎉 Join the community
+
+- Participate in **[GitHub Discussions](https://github.com/calkit/discussions)**.
+- Join our [**Discord**](https://discord.gg/m2MBC79HzD) for real-time collaboration.
+- Follow our updates on [**LinkedIn**](https://linkedin.com/company/calkit).
+
+We appreciate your help in making Calkit better! 🚀

calkit_python-0.42.0/Makefile

@@ -0,0 +1,117 @@
+.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
+
+.PHONY: browser-ext
+browser-ext: ## Build the browser extension and package it as a ZIP.
+	@echo "🚀 Building the browser extension"
+	@cd browser-ext && npm ci && npm run build
+	@echo "📦 Packaging the browser extension ZIP"
+	@mkdir -p browser-ext/zip
+# Packaged from a staged copy, never from dist: dist is what gets loaded
+# unpacked for development, and the published manifest drops the local
+# hub's host permission, which development needs.
+	@rm -rf browser-ext/zip/stage
+	@mkdir -p browser-ext/zip/stage
+	@cp -R browser-ext/dist/. browser-ext/zip/stage/
+	@cd browser-ext && node scripts/package-manifest.mjs zip/stage/manifest.json
+# Source maps are useful loading unpacked, but only bloat a store upload, so
+# they stay in dist and are excluded from the archive.
+# zip adds to an existing archive rather than replacing it, so a rebuild at
+# the same commit would otherwise keep files the build no longer produces.
+# $$ escapes the shell's expansion from Make's own.
+	@rm -f "browser-ext/zip/calkit-browser-ext.zip"
+	@cd browser-ext/zip/stage && zip -qr \
+		"../calkit-browser-ext.zip" . \
+		-x '.*' '*/.*' '*.map'
+	@rm -rf browser-ext/zip/stage
+
+.PHONY: browser-ext-dev
+browser-ext-dev: ## Rebuild the browser extension on every change.
+	@echo "🚀 Watching the browser extension"
+# Rebuilds on save. Chrome still needs the extension reloaded, since it
+# reads a content script from disk when a page loads. Vite doesn't type
+# check, so run 'cd browser-ext && npm run check' alongside this.
+	@cd browser-ext && npm ci && npm run dev
+
+.PHONY: browser-ext-clean-zips
+browser-ext-clean-zips: ## Delete all built browser extension ZIPs.
+	@rm -rf browser-ext/zip