calkit-python 0.47.3__tar.gz → 0.47.5__tar.gz

calkit_python-0.47.5/AGENTS.md

@@ -0,0 +1,79 @@
+# 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`
+- The Calkit Assistant desktop app lives in `assistant`
+- 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 unless asked to.
+
+Tests belong in the test module named after the module the exercised code
+lives in, e.g., tests for `calkit/cli/new.py` go in
+`calkit/tests/cli/test_new.py`. Don't create a new test module for a feature.
+
+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, if anything at all.
+
+Agents should typically not be writing prose for human consumption.
+If some is needed, notify
+the human developer and ask them to write in a given file at a specified
+line and make a commit.

calkit_python-0.47.5/CONTRIBUTING.md

@@ -0,0 +1,152 @@
+# 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. **Create the virtual environment:**
+   ```bash
+   uv sync --all-packages
+   ```
+   This repo is a uv workspace: the hub backend is a member, and both it
+   and the `calkit` package share a single `.venv` at the repo root.
+   Always pass `--all-packages`, since a bare `uv sync` installs only one
+   member and uninstalls the other's dependencies, leaving either the
+   `calkit` CLI or the hub backend unable to import its dependencies.
+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-builder 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`.
+
+## Releasing the assistant
+
+Publishing a GitHub release tagged `assistant/vX.Y.Z` builds the Windows
+executable with PyInstaller and attaches it to the release as
+`calkit-assistant-X.Y.Z-windows.exe`.
+As with the extensions, uncheck "set as the latest release" for these.
+Pull requests that touch `assistant/` run its offscreen smoke test on all
+three platforms and a Windows build, so a broken build is caught before a
+release is cut.
+`make assistant` runs the app locally and `make test-assistant` runs the
+same smoke test.
+
+## 💡 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.47.5/Makefile

@@ -0,0 +1,155 @@
+.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"
+	# --all-packages, since a bare `uv sync` would install only this
+	# package and uninstall the hub backend's dependencies from the
+	# workspace's single shared .venv
+	@uv sync --all-packages
+
+.PHONY: dev
+dev: ## Start up the hub containers for development.
+	@$(MAKE) -C hub dev
+
+.PHONY: dev-reset-user
+dev-reset-user: ## Reset the hub development user's data.
+	@$(MAKE) -C hub dev-reset-user
+
+.PHONY: frontend-client
+frontend-client: ## Regenerate the hub frontend's API client.
+	@$(MAKE) -C hub/frontend client
+
+.PHONY: format
+format: sync-docs sync-resources ## 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: schema
+schema: ## Generate the published JSON schema for calkit.yaml.
+	@echo "🚀 Generating calkit.yaml JSON schema"
+	@uv run calkit describe schema -o docs/schemas/calkit.json
+	@cp docs/schemas/calkit.json vscode-ext/schemas/calkit.json
+
+.PHONY: sync-docs
+sync-docs: schema ## 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: unreleased
+unreleased: ## List each product's commits since its last release.
+	@uv run python scripts/list-changes.py
+
+.PHONY: sync-resources
+sync-resources: ## Regenerate the dev container spec from the VS Code config.
+	@echo "🚀 Syncing project resources"
+	@uv run python scripts/sync-resources.py
+
+.PHONY: devcontainer-image
+devcontainer-image: ## Build the dev container image and smoke test it.
+	@echo "🚀 Building the dev container image"
+	@docker build -t calkit/devcontainer:dev calkit/resources/devcontainer
+	@echo "🚀 Smoke testing the dev container image"
+	@docker run --rm calkit/devcontainer:dev bash -c \
+		"calkit --version && uv --version && pixi --version && conda --version"
+
+.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
+
+.PHONY: assistant
+assistant: ## Run the desktop assistant locally for development.
+	@cd assistant && uv run main.py
+
+.PHONY: test-assistant
+test-assistant: ## Run the desktop assistant's offscreen smoke tests.
+	@cd assistant && QT_QPA_PLATFORM=offscreen uv run pytest