uv-kernel-manager 0.1.1a1__tar.gz

uv_kernel_manager-0.1.1a1/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test-and-build:
+    name: Test and Build Validation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Set up the project environment
+        run: uv sync --locked --group dev
+      - name: Run tests
+        run: uv run --group dev pytest
+      - name: Build distributions
+        run: uv build --no-sources --clear
+      - name: Validate distribution metadata
+        run: uv run --group dev twine check dist/*
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

uv_kernel_manager-0.1.1a1/.github/workflows/release.yaml

@@ -0,0 +1,69 @@
+name: Release to PyPI
+
+on:
+  release:
+    types: [published]
+
+# Trusted Publishing exchanges this short-lived GitHub OIDC identity for a
+# PyPI upload credential. No repository secret or write-capable token is used.
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: pypi-publish
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Validate, build, and publish
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/uv-kernel-manager
+    steps:
+      - name: Check out the released tag
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name }}
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Validate the release tag and package version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+          if [[ ! "$RELEASE_TAG" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)((a|b|rc)(0|[1-9][0-9]*))?$ ]]; then
+            echo "Release tag must be vMAJOR.MINOR.PATCH or a PyPI pre-release such as v0.1.0rc1; got: $RELEASE_TAG" >&2
+            exit 1
+          fi
+          package_version="$(python - <<'PY'
+          import tomllib
+          from pathlib import Path
+
+          manifest = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
+          print(manifest["project"]["version"])
+          PY
+          )"
+          if [[ "v$package_version" != "$RELEASE_TAG" ]]; then
+            echo "Release tag $RELEASE_TAG does not match pyproject.toml version $package_version" >&2
+            exit 1
+          fi
+
+      - name: Install locked development dependencies
+        run: uv sync --locked --group dev
+
+      - name: Run tests
+        run: uv run --group dev pytest
+
+      - name: Build distributions
+        run: uv build --no-sources --clear
+
+      - name: Validate distribution metadata
+        run: uv run --group dev twine check dist/*
+
+      - name: Publish to PyPI with Trusted Publishing
+        run: uv publish --trusted-publishing always dist/*

uv_kernel_manager-0.1.1a1/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+.DS_Store
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+dist/
+build/
+*.egg-info/
+outputs/
+.idea/

uv_kernel_manager-0.1.1a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nOtFoRgEeKs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

uv_kernel_manager-0.1.1a1/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.5
+Name: uv-kernel-manager
+Version: 0.1.1a1
+Summary: A lightweight CLI to seamlessly register and manage uv-managed Python environments as Jupyter kernels.
+Project-URL: Homepage, https://github.com/nOtFoRgEeKs/uv-kernel-manager
+Author: nOtFoRgEeKs
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Requires-Dist: jupyter-client>=8.0
+Description-Content-Type: text/markdown
+
+# uv-kernel-manager
+
+`uv-kernel-manager` registers the Python environments created by
+[`uv`](https://docs.astral.sh/uv/) projects as Jupyter kernels. It is designed
+for a single JupyterLab installation shared across many projects, each with
+its own project-local `.venv`.
+
+The PyPI distribution is `uv-kernel-manager`; the command is `uv-kernel`; the
+Python package is `uv_kernel`.
+
+## How it works
+
+```
+JupyterLab installation
+        │
+        ├── Python 3.12 (analytics) ──> analytics/.venv/bin/python
+        └── Python 3.13 (forecasting) ─> forecasting/.venv/bin/python
+```
+
+Run `uv-kernel register` from a uv project to create a standard, user-level
+Jupyter kernelspec pointing at that project's interpreter. The command suggests
+a label in the form `Python <major.minor> (<project-name>)`, such as
+`Python 3.13 (forecasting)`, and lets you accept it or provide a label that is
+more meaningful to you.
+
+The tool manages kernelspecs only. It does not install, start, configure, or
+upgrade JupyterLab; it also does not create or otherwise manage your uv
+projects or their virtual environments.
+
+## Prerequisites
+
+- [uv](https://docs.astral.sh/uv/) on your `PATH`
+- A uv project with a `pyproject.toml` and a synchronized `.venv` (`uv sync`)
+- JupyterLab or another Jupyter frontend installed wherever you normally run it
+
+`register` adds `ipykernel` to the current project's development dependencies
+by default. Use `--no-add-ipykernel` only when it is already installed or you
+do not want the command to change project dependencies.
+
+## Installation
+
+Install the tool permanently with uv:
+
+```bash
+uv tool install uv-kernel-manager
+```
+
+Then run the `uv-kernel` command from a project directory:
+
+```bash
+cd path/to/forecasting
+uv sync
+uv-kernel register
+jupyter lab
+```
+
+During registration, the tool shows the suggested Jupyter label:
+
+```text
+Register kernel as: Python 3.13 (forecasting)
+Press Enter to continue, or enter a custom name:
+```
+
+Press Enter to use it, or type a custom label. For scripts and other
+non-interactive usage, accept the suggestion with `--yes` or set it explicitly
+with `--name`:
+
+```bash
+uv-kernel register --yes
+uv-kernel register --name "Forecasting — production"
+```
+
+To run without installing it, use `uvx`:
+
+```bash
+uvx uv-kernel-manager register
+uvx uv-kernel-manager status
+```
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `uv-kernel register` | Prompt for a label and add the current project's `.venv` as a Jupyter kernel. |
+| `uv-kernel register --yes` | Register with the suggested label without prompting. |
+| `uv-kernel register --name "NAME"` | Register with an explicit Jupyter label. |
+| `uv-kernel status` | Show whether the current project is registered. |
+| `uv-kernel refresh` | Recreate the current project's kernel with its current interpreter and settings. |
+| `uv-kernel unregister` | Remove the current project's managed kernel. |
+| `uv-kernel list` | List every kernel managed by this tool. |
+| `uv-kernel clean` | Report managed kernels whose project or interpreter no longer exists. |
+| `uv-kernel clean --yes` | Remove the stale managed kernels reported by `clean`. |
+| `uv-kernel doctor` | Show diagnostic information about uv, the project, and Jupyter kernel locations. |
+
+Use `--json` with reporting commands when scripting, for example:
+
+```bash
+uv-kernel --json list
+uv-kernel --json status
+```
+
+For a non-interactive JSON registration, include either `--yes` or `--name`:
+
+```bash
+uv-kernel --json register --yes
+uv-kernel --json register --name "Forecasting — production"
+```
+
+## Safety and ownership
+
+Every kernel created by this tool includes a structured `metadata.uv-kernel`
+ownership record. `unregister`, `refresh`, and `clean` act only on kernels
+with that record; manually installed kernels and kernels managed by other
+tools are left untouched. Kernel directory names also begin with `uv-kernel-`,
+but the metadata marker—not the directory name—is the ownership check.
+
+`clean` is intentionally non-destructive unless you explicitly pass `--yes`.
+
+## Build from source
+
+To build the package locally, clone the repository and install its development
+dependencies:
+
+```bash
+uv sync --dev
+uv build
+```
+
+The wheel and source distribution are written to `dist/`. To install the local
+checkout as a tool, run:
+
+```bash
+uv tool install .
+```
+
+## Development
+
+Run the test suite and validate built package metadata before contributing:
+
+```bash
+uv run pytest
+uv run twine check dist/*
+```
+
+You can also run the command directly from the checkout:
+
+```bash
+uv run uv-kernel --help
+```
+
+## Contributing
+
+Contributions are welcome. Please open an issue or pull request with a focused
+change, include tests when behavior changes, and run the checks above before
+submitting.

uv_kernel_manager-0.1.1a1/README.md

@@ -0,0 +1,155 @@
+# uv-kernel-manager
+
+`uv-kernel-manager` registers the Python environments created by
+[`uv`](https://docs.astral.sh/uv/) projects as Jupyter kernels. It is designed
+for a single JupyterLab installation shared across many projects, each with
+its own project-local `.venv`.
+
+The PyPI distribution is `uv-kernel-manager`; the command is `uv-kernel`; the
+Python package is `uv_kernel`.
+
+## How it works
+
+```
+JupyterLab installation
+        │
+        ├── Python 3.12 (analytics) ──> analytics/.venv/bin/python
+        └── Python 3.13 (forecasting) ─> forecasting/.venv/bin/python
+```
+
+Run `uv-kernel register` from a uv project to create a standard, user-level
+Jupyter kernelspec pointing at that project's interpreter. The command suggests
+a label in the form `Python <major.minor> (<project-name>)`, such as
+`Python 3.13 (forecasting)`, and lets you accept it or provide a label that is
+more meaningful to you.
+
+The tool manages kernelspecs only. It does not install, start, configure, or
+upgrade JupyterLab; it also does not create or otherwise manage your uv
+projects or their virtual environments.
+
+## Prerequisites
+
+- [uv](https://docs.astral.sh/uv/) on your `PATH`
+- A uv project with a `pyproject.toml` and a synchronized `.venv` (`uv sync`)
+- JupyterLab or another Jupyter frontend installed wherever you normally run it
+
+`register` adds `ipykernel` to the current project's development dependencies
+by default. Use `--no-add-ipykernel` only when it is already installed or you
+do not want the command to change project dependencies.
+
+## Installation
+
+Install the tool permanently with uv:
+
+```bash
+uv tool install uv-kernel-manager
+```
+
+Then run the `uv-kernel` command from a project directory:
+
+```bash
+cd path/to/forecasting
+uv sync
+uv-kernel register
+jupyter lab
+```
+
+During registration, the tool shows the suggested Jupyter label:
+
+```text
+Register kernel as: Python 3.13 (forecasting)
+Press Enter to continue, or enter a custom name:
+```
+
+Press Enter to use it, or type a custom label. For scripts and other
+non-interactive usage, accept the suggestion with `--yes` or set it explicitly
+with `--name`:
+
+```bash
+uv-kernel register --yes
+uv-kernel register --name "Forecasting — production"
+```
+
+To run without installing it, use `uvx`:
+
+```bash
+uvx uv-kernel-manager register
+uvx uv-kernel-manager status
+```
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `uv-kernel register` | Prompt for a label and add the current project's `.venv` as a Jupyter kernel. |
+| `uv-kernel register --yes` | Register with the suggested label without prompting. |
+| `uv-kernel register --name "NAME"` | Register with an explicit Jupyter label. |
+| `uv-kernel status` | Show whether the current project is registered. |
+| `uv-kernel refresh` | Recreate the current project's kernel with its current interpreter and settings. |
+| `uv-kernel unregister` | Remove the current project's managed kernel. |
+| `uv-kernel list` | List every kernel managed by this tool. |
+| `uv-kernel clean` | Report managed kernels whose project or interpreter no longer exists. |
+| `uv-kernel clean --yes` | Remove the stale managed kernels reported by `clean`. |
+| `uv-kernel doctor` | Show diagnostic information about uv, the project, and Jupyter kernel locations. |
+
+Use `--json` with reporting commands when scripting, for example:
+
+```bash
+uv-kernel --json list
+uv-kernel --json status
+```
+
+For a non-interactive JSON registration, include either `--yes` or `--name`:
+
+```bash
+uv-kernel --json register --yes
+uv-kernel --json register --name "Forecasting — production"
+```
+
+## Safety and ownership
+
+Every kernel created by this tool includes a structured `metadata.uv-kernel`
+ownership record. `unregister`, `refresh`, and `clean` act only on kernels
+with that record; manually installed kernels and kernels managed by other
+tools are left untouched. Kernel directory names also begin with `uv-kernel-`,
+but the metadata marker—not the directory name—is the ownership check.
+
+`clean` is intentionally non-destructive unless you explicitly pass `--yes`.
+
+## Build from source
+
+To build the package locally, clone the repository and install its development
+dependencies:
+
+```bash
+uv sync --dev
+uv build
+```
+
+The wheel and source distribution are written to `dist/`. To install the local
+checkout as a tool, run:
+
+```bash
+uv tool install .
+```
+
+## Development
+
+Run the test suite and validate built package metadata before contributing:
+
+```bash
+uv run pytest
+uv run twine check dist/*
+```
+
+You can also run the command directly from the checkout:
+
+```bash
+uv run uv-kernel --help
+```
+
+## Contributing
+
+Contributions are welcome. Please open an issue or pull request with a focused
+change, include tests when behavior changes, and run the checks above before
+submitting.

uv_kernel_manager-0.1.1a1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "uv-kernel-manager"
+version = "0.1.1a1"
+
+description = "A lightweight CLI to seamlessly register and manage uv-managed Python environments as Jupyter kernels."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "nOtFoRgEeKs" }]
+classifiers = [
+  "Environment :: Console",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Build Tools",
+]
+dependencies = ["jupyter_client>=8.0"]
+
+[project.scripts]
+uv-kernel = "uv_kernel.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/nOtFoRgEeKs/uv-kernel-manager"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/uv_kernel"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[dependency-groups]
+dev = ["pytest>=8", "twine>=6"]

uv_kernel_manager-0.1.1a1/src/uv_kernel/__init__.py

@@ -0,0 +1,7 @@
+"""Manage Jupyter kernels for uv-managed projects."""
+
+from importlib.metadata import version
+
+# The installed distribution metadata is generated from [project].version in
+# pyproject.toml, keeping that file as the only version authority.
+__version__ = version("uv-kernel-manager")

uv_kernel_manager-0.1.1a1/src/uv_kernel/cli.py

@@ -0,0 +1,146 @@
+"""Command line interface for uv-kernel."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .core import (UVKernelError, display_name, doctor, ensure_ipykernel,
+                   find_project, install, matching, owned_kernels, remove, stale)
+
+DESCRIPTION = """
+Manage Jupyter kernels for uv-managed Python environments.
+
+Register a project's uv `.venv` with the Jupyter installation you already use.
+Only kernels carrying uv-kernel's ownership metadata are ever changed or removed.
+"""
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="uv-kernel", description=DESCRIPTION,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="Examples:\n  uv-kernel register\n  uv-kernel --json list\n  uv-kernel clean --yes")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    p.add_argument("--json", action="store_true", dest="json_output", help="Output machine-readable JSON.")
+    sub = p.add_subparsers(dest="command", required=True, metavar="COMMAND")
+    register = sub.add_parser("register", help="Register the current uv project as a Jupyter kernel.",
+        description="Adds ipykernel as a development dependency by default and writes a standard user kernelspec.")
+    register.add_argument("--no-add-ipykernel", action="store_true", help="Do not run `uv add --dev ipykernel` first.")
+    naming = register.add_mutually_exclusive_group()
+    naming.add_argument("--name", metavar="NAME", help="Use NAME as the kernel label instead of the suggested label.")
+    naming.add_argument("--yes", action="store_true", help="Accept the suggested kernel label without prompting.")
+    sub.add_parser("unregister", help="Remove this project's uv-kernel-owned kernel.",
+        description="Removes only kernels marked as owned by uv-kernel for the current project.")
+    sub.add_parser("list", help="List every kernel owned by uv-kernel.")
+    sub.add_parser("status", help="Show this project's uv-kernel registration status.")
+    sub.add_parser("refresh", help="Recreate this project's owned kernel with current settings.",
+        description="Updates the spec for the current .venv; it never touches other kernels.")
+    clean = sub.add_parser("clean", help="Find stale uv-kernel-owned kernels safely.",
+        description="Reports kernels whose project or .venv interpreter is gone. Nothing is deleted without --yes.")
+    clean.add_argument("--yes", action="store_true", help="Remove the stale kernels reported by clean.")
+    sub.add_parser("doctor", help="Diagnose uv, the current project, and Jupyter kernel paths.")
+    return p
+
+
+def emit(value: Any, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(value, indent=2, sort_keys=True))
+        return
+    if isinstance(value, list):
+        if not value:
+            print("No uv-kernel-owned kernels found.")
+        for item in value:
+            print(f"{item['name']}: {item.get('display_name', '')} — {item.get('project_path', '')}")
+    elif isinstance(value, dict):
+        for key, item in value.items(): print(f"{key}: {item}")
+    else: print(value)
+
+
+def choose_kernel_name(default: str) -> str:
+    """Prompt for a kernel label, accepting the suggested label on Enter."""
+    try:
+        response = input(
+            f"Register kernel as: {default}\n"
+            "Press Enter to continue, or enter a custom name: "
+        ).strip()
+    except EOFError as exc:
+        raise UVKernelError("No kernel name was provided. Use --yes or --name for non-interactive use.") from exc
+    return response or default
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        if args.command == "list":
+            emit(owned_kernels(), args.json_output)
+            return 0
+        
+        if args.command == "clean":
+            items = stale(owned_kernels())
+            if args.yes:
+                removed = remove(items)
+                emit({"removed": removed, "count": len(removed)}, args.json_output)
+            else:
+                emit(items, args.json_output)
+                if not args.json_output and items: 
+                    print("Run `uv-kernel clean --yes` to remove these kernels.")
+            return 0
+        
+        if args.command == "doctor":
+            try: 
+                project = find_project()
+            except UVKernelError: 
+                project = None
+            emit(doctor(project), args.json_output)
+            return 0
+        
+        project = find_project()
+        if args.command == "register":
+            suggested_name = display_name(project)
+            if args.name:
+                kernel_display_name = args.name
+            elif args.yes:
+                kernel_display_name = suggested_name
+            elif args.json_output:
+                raise UVKernelError("Use --yes or --name with --json register.")
+            else:
+                kernel_display_name = choose_kernel_name(suggested_name)
+            if not args.no_add_ipykernel:
+                ensure_ipykernel(project)
+            result = install(project, kernel_display_name=kernel_display_name)
+            emit({"registered": result}, args.json_output)
+            return 0
+        
+        if args.command == "unregister":
+            removed = remove(matching(project))
+            emit({"removed": removed, "count": len(removed)}, args.json_output)
+            return 0
+        
+        if args.command == "status":
+            items = matching(project)
+            result = {"project": str(project.root), "registered": bool(items), "kernels": items}
+            emit(result, args.json_output)
+            return 0 if items else 1
+        
+        if args.command == "refresh":
+            remove(matching(project))
+            result = install(project)
+            emit({"refreshed": result}, args.json_output)
+            return 0
+        
+    except UVKernelError as exc:
+        if args.json_output: 
+            print(json.dumps({"error": str(exc)}))
+        else: 
+            print(f"uv-kernel: error: {exc}", file=sys.stderr)
+        return 2
+    
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())