initial commit

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  Lint:
+    runs-on: macos-14
+    if: github.repository == 'manzt/juv'
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "0.4.x"
+      - run: |
+          uv run ruff format --check
+          uv run ruff check
+
+  Test:
+    runs-on: macos-14
+    if: github.repository == 'manzt/juv'
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "0.4.x"
+      - run: uv run pytest

.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "0.4.x"
+
+      - run: uv build
+
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+          verbose: true
+
+      - run: deno run -A npm:[email protected]
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.gitignore

@@ -0,0 +1,2 @@
+.ipynb_checkpoints
+__pycache__

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Trevor Manz
+
+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.

README.md

@@ -0,0 +1,70 @@
+# juv
+
+A little wrapper around `uv` to launch ephemeral Jupyter notebooks.
+
+```sh
+uvx juv
+# juv [uvx flags] <command>[@version] <path>
+#
+# Commands:
+#   lab       Launch JupyterLab
+#   notebook  Launch Jupyter Notebook (classic)
+#
+# Arguments:
+#   path  Path to the Python script or notebook file
+#
+# Examples:
+#   uvx juv lab script.py
+#   uvx juv [email protected] script.ipynb
+#   uvx juv notebook existing_notebook.ipynb
+#   uvx juv --with pandas,matplotlib lab new_notebook.ipynb
+```
+
+`juv` has two main commands:
+
+- `juv lab` launches a Jupyter Lab session
+- `juv notebook` launches a classic notebook session
+
+Both commands accept a single argument: the path to the notebook or script to
+launch. A script will be converted to a notebook before launching.
+
+```sh
+uvx juv lab script.py # creates script.ipynb
+```
+
+Any flags that are passed prior to the command (e.g., `uvx juv --with=polars
+lab`) will be forwarded to `uvx` as-is. This allows you to specify additional
+dependencies, a different interpreter, etc.
+
+## what
+
+[PEP 723 (inline script metadata)](https://peps.python.org/pep-0723) allows
+specifying dependencies as comments within Python scripts, enabling
+self-contained, reproducible execution. This feature could significantly
+improve reproducibility in the data science ecosystem, since many analyses are
+shared as standalone code (not packages). However, _a lot_ of data science code
+lives in notebooks (`.ipynb` files), not Python scripts (`.py` files).
+
+`juv` bridges this gap by:
+
+- Extending PEP 723-style metadata support from `uv` to Jupyter notebooks
+- Launching Jupyter sessions with the specified dependencies
+
+It's a simple Python script that parses the notebook and starts a Jupyter
+session with the specified dependencies (piggybacking on `uv`'s existing
+functionality).
+
+## alternatives
+
+`juv` is opinionated and might not suit your preferences. That's ok! `uv` is
+super extensible, and I recommend reading [the
+documentation](https://docs.astral.sh/uv) to learn about its primitives.
+
+For example, you can achieve a similar workflow using the `--with-requirements`
+flag:
+
+```sh
+uvx --with-requirements=requirements.txt --from=jupyter-core --with=jupyterlab jupyter lab notebook.ipynb
+```
+
+While slightly more verbose, and breaking self-containment, this approach works well.

pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "juv"
+description = "A little wrapper around `uv` to launch ephemeral Jupyter notebooks."
+readme = "README.md"
+authors = [{ name = "Trevor Manz", email = "[email protected]" }]
+requires-python = ">=3.8"
+dependencies = [
+    "rich>=13.9.2",
+]
+dynamic = ["version"]
+
+[project.scripts]
+juv = "juv:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.uv]
+dev-dependencies = [
+    "inline-snapshot>=0.13.3",
+    "pytest>=8.3.3",
+    "ruff>=0.7.0",
+]