uv-kernel-manager 0.1.1a1__py3-none-any.whl

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/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())

uv_kernel/core.py

@@ -0,0 +1,171 @@
+"""Project discovery and safe Jupyter kernelspec operations."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from jupyter_client.kernelspec import KernelSpecManager
+
+from . import __version__
+
+OWNER_KEY = "uv-kernel"
+
+
+class UVKernelError(RuntimeError):
+    """A recoverable command error which should be shown to the user."""
+
+
+@dataclass(frozen=True)
+class Project:
+    root: Path
+    name: str
+    python: Path
+
+
+def find_project(start: Path | None = None) -> Project:
+    """Find the closest enclosing uv project and its project-local interpreter."""
+    directory = (start or Path.cwd()).resolve()
+    for candidate in (directory, *directory.parents):
+        manifest = candidate / "pyproject.toml"
+        if manifest.is_file():
+            try:
+                data = tomllib.loads(manifest.read_text(encoding="utf-8"))
+            except tomllib.TOMLDecodeError as exc:
+                raise UVKernelError(f"Cannot read {manifest}: {exc}") from exc
+            name = data.get("project", {}).get("name") or candidate.name
+            if not isinstance(name, str) or not name.strip():
+                name = candidate.name
+            python = candidate / ".venv" / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+            return Project(candidate, name, python)
+    raise UVKernelError("No pyproject.toml found in this directory or its parents.")
+
+
+def kernel_id(project: Project) -> str:
+    """A stable, collision-resistant Jupyter kernelspec identifier."""
+    slug = re.sub(r"[^a-z0-9]+", "-", project.name.lower()).strip("-") or "project"
+    digest = hashlib.sha256(str(project.root).encode()).hexdigest()[:10]
+    return f"uv-kernel-{slug}-{digest}"
+
+
+def python_version(python: Path) -> str:
+    try:
+        result = subprocess.run(
+            [str(python), "-c", "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')"],
+            capture_output=True, text=True, check=True,
+        )
+    except (OSError, subprocess.CalledProcessError) as exc:
+        raise UVKernelError(f"Could not run project Python at {python}: {exc}") from exc
+    return result.stdout.strip()
+
+
+def display_name(project: Project) -> str:
+    return f"Python {python_version(project.python)} ({project.name})"
+
+
+def ensure_ipykernel(project: Project) -> None:
+    """Ask uv to add ipykernel as a development dependency."""
+    try:
+        subprocess.run(["uv", "add", "--dev", "ipykernel"], cwd=project.root, check=True)
+    except FileNotFoundError as exc:
+        raise UVKernelError("uv was not found on PATH; install uv before registering.") from exc
+    except subprocess.CalledProcessError as exc:
+        raise UVKernelError("uv could not add the development dependency ipykernel.") from exc
+
+
+def spec_data(project: Project, kernel_display_name: str | None = None) -> dict[str, Any]:
+    return {
+        "argv": [str(project.python), "-m", "ipykernel_launcher", "-f", "{connection_file}"],
+        "display_name": kernel_display_name or display_name(project),
+        "language": "python",
+        "metadata": {OWNER_KEY: {
+            "version": __version__, "project_path": str(project.root),
+            "project_name": project.name,
+        }},
+    }
+
+
+def owned(spec: dict[str, Any]) -> bool:
+    return isinstance(spec.get("spec", {}).get("metadata", {}).get(OWNER_KEY), dict)
+
+
+def owned_kernels(manager: KernelSpecManager | None = None) -> list[dict[str, Any]]:
+    manager = manager or KernelSpecManager()
+    results = []
+    for name, data in manager.get_all_specs().items():
+        if owned(data):
+            meta = data["spec"]["metadata"][OWNER_KEY]
+            results.append({
+                "name": name, "display_name": data["spec"].get("display_name"),
+                "resource_dir": data.get("resource_dir"), "project_path": meta.get("project_path"),
+                "project_name": meta.get("project_name"), "version": meta.get("version"),
+            })
+    return sorted(results, key=lambda item: item["name"])
+
+
+def install(
+    project: Project,
+    manager: KernelSpecManager | None = None,
+    kernel_display_name: str | None = None,
+) -> dict[str, Any]:
+    if not project.python.is_file():
+        raise UVKernelError(f"No project interpreter found at {project.python}. Run `uv sync` first.")
+    manager = manager or KernelSpecManager()
+    name = kernel_id(project)
+    with tempfile.TemporaryDirectory(prefix="uv-kernel-") as temp:
+        Path(temp, "kernel.json").write_text(
+            json.dumps(spec_data(project, kernel_display_name), indent=2) + "\n",
+            encoding="utf-8",
+        )
+        manager.install_kernel_spec(temp, kernel_name=name, user=True, replace=True)
+    return {
+        "name": name,
+        "display_name": kernel_display_name or display_name(project),
+        "project_path": str(project.root),
+    }
+
+
+def matching(project: Project, manager: KernelSpecManager | None = None) -> list[dict[str, Any]]:
+    return [item for item in owned_kernels(manager) if item["project_path"] == str(project.root)]
+
+
+def remove(items: list[dict[str, Any]], manager: KernelSpecManager | None = None) -> list[str]:
+    manager = manager or KernelSpecManager()
+    removed: list[str] = []
+    for item in items:
+        manager.remove_kernel_spec(item["name"])
+        removed.append(item["name"])
+    return removed
+
+
+def stale(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [item for item in items if not item.get("project_path") or not Path(item["project_path"]).is_dir()
+            or not Path(item["project_path"], ".venv", "Scripts/python.exe" if os.name == "nt" else "bin/python").is_file()]
+
+
+def doctor(project: Project | None) -> dict[str, Any]:
+    details: dict[str, Any] = {
+        "uv": shutil.which("uv"), "jupyter_paths": KernelSpecManager().kernel_dirs,
+        "python": sys.executable,
+    }
+    if project:
+        details["project"] = {
+            "path": str(project.root), "name": project.name,
+            "interpreter": str(project.python), "interpreter_exists": project.python.is_file()
+        }
+        if project.python.is_file():
+            try:
+                details["project"]["python_version"] = python_version(project.python)
+            except UVKernelError as exc:
+                details["project"]["python_error"] = str(exc)
+    return details

uv_kernel_manager-0.1.1a1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+uv_kernel/__init__.py,sha256=ZPGIixPEw_hENy_O6J0QtQur9LKh2ciC2R2vCaIea8I,282
+uv_kernel/cli.py,sha256=jAKcDuJlY_ZtZtpECIYgm13W3kRSgWi2EipknVZu4E8,6284
+uv_kernel/core.py,sha256=xNzIrdyVCF8CAc9TZLrLIHGDJuG4sbGo2XWI00QvXw4,6495
+uv_kernel_manager-0.1.1a1.dist-info/METADATA,sha256=LerlZIZ_gp8vyEBZXNk2aqO8tfwXTiSYGe2mNBgkBMY,5380
+uv_kernel_manager-0.1.1a1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+uv_kernel_manager-0.1.1a1.dist-info/entry_points.txt,sha256=JW7hmvs49eP8cG-CMpQpaT5URK6971wZRCr6I0sJP0M,49
+uv_kernel_manager-0.1.1a1.dist-info/licenses/LICENSE,sha256=Gb9LjGPFKEOEdAlCgN0oFgVhKsfo93ASlM8NsftjFG4,1068
+uv_kernel_manager-0.1.1a1.dist-info/RECORD,,

uv_kernel_manager-0.1.1a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

uv_kernel_manager-0.1.1a1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+uv-kernel = uv_kernel.cli:main

uv_kernel_manager-0.1.1a1.dist-info/licenses/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.