juplit 0.0.1__tar.gz

juplit-0.0.1/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.3
+Name: juplit
+Version: 0.0.1
+Summary: Jupytext percent-format notebook workflow manager
+Requires-Dist: jupytext>=1.16.0
+Requires-Dist: cyclopts>=2.0.0
+Requires-Python: >=3.12

juplit-0.0.1/juplit/SKILL.md

@@ -0,0 +1,181 @@
+# Juplit: Literate Programming Workflow for Python Projects
+
+## What juplit is for
+
+juplit lets you do **literate programming** — writing code alongside explanations, examples, and tests in Jupyter notebook cells — while keeping your repository clean and AI-agent-friendly.
+
+The problem it solves:
+- Jupyter `.ipynb` files are JSON blobs: hard to diff in git, noisy in PRs, and token-heavy when AI agents need to read them
+- But interactive notebook development is genuinely useful: you can run cells incrementally, see outputs inline, and mix prose with code
+
+**juplit's solution**: `.py` files in jupytext percent format are the source of truth. `.ipynb` files are generated on demand for interactive use and are gitignored. AI agents and humans read `.py` files; Jupyter reads `.ipynb` files.
+
+## File format
+
+Every paired notebook `.py` file starts with a jupytext header:
+
+```python
+# ---
+# jupyter:
+#   jupytext:
+#     formats: ipynb,py:percent
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.16.0
+#   kernelspec:
+#     display_name: Python 3
+#     language: python
+#     name: python3
+# ---
+```
+
+The key line is `formats: ipynb,py:percent` — this is what marks a file as a paired notebook.
+
+### Cell delimiters
+
+| Syntax | Meaning |
+|---|---|
+| `# %%` | Code cell |
+| `# %% [markdown]` | Markdown cell (content is `#`-prefixed comments) |
+
+### Markdown cells
+
+```python
+# %% [markdown]
+# # Module Title
+#
+# Description of what this module does.
+```
+
+## Separating logic from tests with `test()`
+
+Import `test` from juplit to gate test code so it runs interactively and under pytest, but **never on import**:
+
+```python
+from juplit import test
+
+# %%
+def add(a: int, b: int) -> int:
+    return a + b
+
+# %%
+if test():
+    assert add(1, 2) == 3
+    assert add(-1, 1) == 0
+```
+
+`test()` returns `True` when:
+- The module is run as `__main__` (interactive Jupyter cell execution)
+- `pytest` is active
+
+It returns `False` on normal import, so test code never runs in production.
+
+## Poe commands
+
+| Command | What it does |
+|---|---|
+| `poe sync` | Sync `.py` ↔ `.ipynb` — run after cloning and after editing `.py` files |
+| `poe clean` | Sync then delete all `.ipynb` files — use before AI agent sessions |
+| `poe init` | Install git pre-commit hooks |
+| `poe test` | Run pytest across all `.py` files |
+| `poe docs` | Sync notebooks then serve docs locally for preview |
+| `poe docs-deploy` | Sync notebooks then deploy docs to GitHub Pages |
+
+## Workflow
+
+### First-time setup after cloning
+
+```bash
+uv sync        # install dependencies
+poe init       # install git hooks (includes juplit sync on commit)
+poe sync       # generate .ipynb notebooks from .py files
+```
+
+### Editing code (as an AI agent or in an editor)
+
+1. Edit the `.py` file directly
+2. Run `poe sync` to propagate changes to `.ipynb`
+3. Commit the `.py` file — `.ipynb` is gitignored
+
+### Before handing off to an AI agent
+
+```bash
+poe clean      # removes all .ipynb files so agents only see .py files
+```
+
+## Creating a new paired notebook file
+
+1. Create a `.py` file with the jupytext header (copy from an existing file)
+2. Add cells using `# %%` and `# %% [markdown]` delimiters
+3. Run `poe sync` to generate the paired `.ipynb`
+
+Minimal template:
+
+```python
+# ---
+# jupyter:
+#   jupytext:
+#     formats: ipynb,py:percent
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.16.0
+# ---
+
+# %% [markdown]
+# # Module Name
+#
+# Brief description.
+
+# %%
+from juplit import test
+
+# %%
+def my_function(x):
+    return x
+
+# %%
+if test():
+    assert my_function(1) == 1
+```
+
+## Configuration in pyproject.toml
+
+```toml
+[project]
+dependencies = ["juplit>=0.1.0"]
+
+[dependency-groups]
+dev = ["poethepoet>=0.25.0", "pytest>=8.0.0", "ipykernel>=6.0.0", "pre-commit>=3.0.0"]
+
+[tool.poe.tasks]
+init         = {cmd = "pre-commit install"}
+sync         = {cmd = "juplit sync"}
+clean        = {cmd = "juplit clean"}
+test         = {cmd = "pytest"}
+docs         = {sequence = [{ref = "sync"}, {cmd = "mkdocs serve"}]}
+docs-deploy  = {sequence = [{ref = "sync"}, {cmd = "mkdocs gh-deploy --force"}]}
+
+[tool.juplit]
+notebook_src_dirs = ["your_module_name", "docs"]  # dirs scanned for paired .py files
+
+[tool.jupytext]
+formats = "ipynb,py:percent"
+
+[tool.pytest.ini_options]
+python_files = ["*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+```
+
+## Key conventions
+
+- **Edit `.py` files only** — `.ipynb` is generated, never manually edited
+- **One logical idea per cell** — keep cells small and focused
+- **Gate all test code with `if test():`** — never let test side effects run on import
+- **Markdown goes in `# %% [markdown]` cells** using `#`-prefixed comment lines
+- **`_tasks.py` itself** uses `formats: py:percent` (no `ipynb` pairing) since it is a pure utility, not a notebook
+

juplit-0.0.1/juplit/SKILL_migrate_from_nbdev.md

@@ -0,0 +1,141 @@
+# Migrating from nbdev to juplit
+
+This guide describes how to migrate a project that uses nbdev (Jupyter-based literate programming with `#|export` directives) to juplit's percent-format workflow.
+
+## Overview
+
+nbdev notebooks use special directives inside cells to control what gets exported:
+- `#|export` — cell is exported to the Python module
+- `#|hide` — cell is hidden in docs (usually tests/setup)
+- No directive — cell is shown in docs but not exported (usually examples/tests)
+
+In juplit, **all cells are regular Python** and everything in the file is importable. Test/example code is gated with `if test():` instead of being in non-exported cells.
+
+## Migration steps
+
+### 1. Initialize a new juplit project with cookiecutter
+
+```bash
+pip install cookiecutter juplit
+cookiecutter gh:DeanLight/juplit_template
+cd <new_project_slug>
+uv sync
+poe init
+```
+
+### 2. For each nbdev notebook, create a paired .py file
+
+For each `.ipynb` in the nbdev `nbs/` directory, create a corresponding `.py` file in the new module directory. Use this conversion rule for each cell:
+
+**Markdown cells** → `# %% [markdown]` cell (keep content as `#`-prefixed comments):
+
+```python
+# %% [markdown]
+# # Module Title
+#
+# Cell content here.
+```
+
+**Code cells with `#|export`** → regular `# %%` code cell (strip the directive):
+
+```python
+# nbdev:           →   # juplit:
+# #|export             # %%
+# def my_func(x):      def my_func(x):
+#     return x              return x
+```
+
+**Code cells without `#|export`** (examples, tests, `#|hide` cells) → `# %%` cell wrapped in `if test():`
+
+```python
+# nbdev (no #|export):   →   # juplit:
+# assert my_func(1) == 1     # %%
+#                             if test():
+#                                 assert my_func(1) == 1
+```
+
+### 3. File header
+
+Every converted file needs the jupytext header at the top, followed by the `test` import:
+
+```python
+# ---
+# jupyter:
+#   jupytext:
+#     formats: ipynb,py:percent
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.16.0
+#   kernelspec:
+#     display_name: Python 3
+#     language: python
+#     name: python3
+# ---
+
+# %%
+from juplit import test
+# (other imports your module needs)
+```
+
+### 4. Generate notebooks and verify
+
+```bash
+poe sync       # generates .ipynb from .py files
+poe test       # run tests to verify nothing broke
+```
+
+### 5. Update imports in the rest of the project
+
+nbdev exports from a generated module path. After migration, the module is the `.py` files directly. Update any `from nbs.xx_module import ...` to `from your_module import ...`.
+
+## Example conversion
+
+**Before (nbdev `nbs/00_core.ipynb`):**
+
+```python
+# Cell 1 — markdown
+# # Core module
+
+# Cell 2 — #|export
+# #|export
+# def add(a, b):
+#     return a + b
+
+# Cell 3 — no directive (test shown in docs)
+# assert add(1, 2) == 3
+
+# Cell 4 — #|hide (hidden test)
+# #|hide
+# assert add(-1, 1) == 0
+```
+
+**After (juplit `your_module/core.py`):**
+
+```python
+# ---
+# jupyter:
+#   jupytext:
+#     formats: ipynb,py:percent
+# ...
+# ---
+
+# %% [markdown]
+# # Core module
+
+# %%
+from juplit import test
+
+# %%
+def add(a, b):
+    return a + b
+
+# %%
+if test():
+    assert add(1, 2) == 3
+
+# %%
+if test():
+    assert add(-1, 1) == 0
+```

juplit-0.0.1/juplit/__init__.py

@@ -0,0 +1,4 @@
+from juplit.tasks import clean_notebooks, generate_notebooks, sync_notebooks
+from juplit.testing import test
+
+__all__ = ["sync_notebooks", "generate_notebooks", "clean_notebooks", "test"]

juplit-0.0.1/juplit/_dev.py

@@ -0,0 +1,15 @@
+"""Internal dev utilities for the juplit package itself."""
+
+import os
+import sys
+
+
+def check_env(env_name: str) -> None:
+    """Assert that an environment variable is set; exit with an error if not.
+
+    Used as a poe task guard before publishing to PyPI.
+    """
+    if not os.environ.get(env_name):
+        print(f"Error: environment variable {env_name!r} is not set.", file=sys.stderr)
+        print(f"  Set it with: export {env_name}=<your-token>", file=sys.stderr)
+        raise SystemExit(1)

juplit-0.0.1/juplit/cli.py

@@ -0,0 +1,56 @@
+"""juplit CLI — notebook workflow commands."""
+
+from importlib.resources import files
+
+import cyclopts
+
+from juplit.tasks import clean_notebooks, generate_notebooks, sync_notebooks
+
+app = cyclopts.App(
+    name="juplit",
+    help="Jupytext percent-format notebook workflow manager.",
+)
+
+
+@app.command
+def sync() -> None:
+    """Sync .py <-> .ipynb for all paired percent-format notebooks."""
+    sync_notebooks()
+
+
+@app.command
+def nb() -> None:
+    """Generate .ipynb files from .py percent-format files (run after cloning)."""
+    generate_notebooks()
+
+
+@app.command
+def clean() -> None:
+    """Sync notebooks then delete all .ipynb files (keeps workspace clean for AI agents)."""
+    clean_notebooks()
+
+
+@app.command
+def skill() -> None:
+    """Print the juplit skill file for use with Claude Code.
+
+    Pipe the output into your project's .claude/skills/ directory:
+
+        juplit skill > .claude/skills/juplit-programming.md
+    """
+    print(files("juplit").joinpath("SKILL.md").read_text(), end="")
+
+
+@app.command
+def skill_migrate() -> None:
+    """Print the nbdev-to-juplit migration skill file for use with Claude Code.
+
+    Pipe the output into your project's .claude/skills/ directory:
+
+        juplit skill-migrate > .claude/skills/juplit-migrate.md
+    """
+    print(files("juplit").joinpath("SKILL_migrate_from_nbdev.md").read_text(), end="")
+
+
+def main() -> None:
+    app()

juplit-0.0.1/juplit/tasks.py

@@ -0,0 +1,239 @@
+"""Core notebook workflow tasks for juplit.
+
+These functions back both the `poe` task targets and the `juplit` CLI commands.
+They can also be imported and called directly from Python.
+"""
+
+import hashlib
+import json
+import subprocess
+import tomllib
+from pathlib import Path
+
+
+def _find_pyproject_toml() -> Path | None:
+    """Walk up from cwd to find the nearest pyproject.toml."""
+    current = Path.cwd()
+    for parent in [current, *current.parents]:
+        candidate = parent / "pyproject.toml"
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _get_src_dirs() -> list[Path]:
+    """Read notebook_src_dirs (or legacy notebook_src_dir) from [tool.juplit]."""
+    toml_path = _find_pyproject_toml()
+    root = toml_path.parent if toml_path is not None else Path.cwd()
+    if toml_path is not None:
+        try:
+            with open(toml_path, "rb") as f:
+                config = tomllib.load(f)
+            juplit_cfg = config.get("tool", {}).get("juplit", {})
+            dirs = juplit_cfg.get("notebook_src_dirs") or juplit_cfg.get("notebook_src_dir")
+            if dirs:
+                if isinstance(dirs, str):
+                    dirs = [dirs]
+                return [root / d for d in dirs]
+        except OSError:
+            pass
+    return [root / "src"]
+
+
+def _is_paired_notebook(path: Path) -> bool:
+    """Return True if the file is a percent-format notebook paired with an ipynb.
+
+    Checks the jupytext header for both 'ipynb' and 'py:percent' in the formats
+    line, so plain py files and non-paired notebooks are excluded.
+    """
+    try:
+        content = path.read_text()
+    except OSError:
+        return False
+    for line in content.splitlines():
+        if not line.startswith("#"):
+            break
+        stripped = line.lstrip("# ").strip()
+        if stripped.startswith("formats:"):
+            formats = stripped[len("formats:"):].strip()
+            return "ipynb" in formats and "py:percent" in formats
+    return False
+
+
+def _find_py_files() -> list[Path]:
+    result = []
+    for src_dir in _get_src_dirs():
+        if src_dir.exists():
+            result.extend(src_dir.rglob("*.py"))
+    return sorted(result)
+
+
+def _find_percent_notebook_py_files() -> list[Path]:
+    return [f for f in _find_py_files() if _is_paired_notebook(f)]
+
+
+def _fmt(label: str, names: list[str]) -> str:
+    return f"{len(names)} {label}: {', '.join(names)}"
+
+
+# ── Hash-based change tracking ────────────────────────────────────────────────
+
+def _hash_file(path: Path) -> str:
+    try:
+        return hashlib.md5(path.read_bytes()).hexdigest()
+    except OSError:
+        return ""
+
+
+def _state_path() -> Path:
+    toml_path = _find_pyproject_toml()
+    root = toml_path.parent if toml_path is not None else Path.cwd()
+    return root / ".sync_hashes.json"
+
+
+def _load_hashes() -> dict[str, str]:
+    p = _state_path()
+    if p.exists():
+        try:
+            return json.loads(p.read_text())
+        except Exception:
+            return {}
+    return {}
+
+
+def _save_hashes(files: list[Path]) -> None:
+    state = {f.name: _hash_file(f) for f in files if f.exists()}
+    _state_path().write_text(json.dumps(state, indent=2, sort_keys=True) + "\n")
+
+
+# ── Jupytext runner ───────────────────────────────────────────────────────────
+
+def _run_jupytext(args: list[str], files: list[Path]) -> tuple[dict[str, list[str]], list[str]]:
+    """Run jupytext and classify files by comparing hashes against the last sync.
+
+    Returns (groups, errors) where groups has keys: updated, unchanged, skipped.
+    """
+    prev_hashes = _load_hashes()
+
+    result = subprocess.run(
+        ["jupytext"] + args + [str(f) for f in files],
+        capture_output=True,
+        text=True,
+    )
+
+    skipped_names: set[str] = set()
+    errors: list[str] = []
+
+    for line in result.stderr.splitlines():
+        low = line.lower()
+        if "warning" in low and "not a paired" in low:
+            words = line.split()
+            try:
+                idx = next(i for i, w in enumerate(words) if w == "Warning:")
+                skipped_names.add(Path(words[idx + 1]).name)
+            except (StopIteration, IndexError):
+                pass
+        elif "error" in low:
+            errors.append(line)
+
+    if result.returncode != 0 and not errors:
+        errors.append(result.stderr.strip() or f"jupytext exited with code {result.returncode}")
+
+    updated: list[str] = []
+    unchanged: list[str] = []
+    skipped: list[str] = []
+
+    for f in files:
+        if f.name in skipped_names:
+            skipped.append(f.name)
+        elif _hash_file(f) != prev_hashes.get(f.name, ""):
+            updated.append(f.name)
+        else:
+            unchanged.append(f.name)
+
+    _save_hashes(files)
+    return {"updated": updated, "unchanged": unchanged, "skipped": skipped}, errors
+
+
+# ── Public tasks ─────────────────────────────────────────────────────────────
+
+def sync_notebooks() -> None:
+    """Sync `.py` and `.ipynb` files for all paired percent-format notebooks.
+
+    Walks the configured `notebook_src_dirs` (from `[tool.juplit]` in
+    `pyproject.toml`) and calls `jupytext --sync` on every `.py` file that has
+    a jupytext percent-format header pairing it with an `.ipynb`.
+
+    Prints a summary of updated, unchanged, and skipped files.
+    Raises `SystemExit(1)` if jupytext reports any errors.
+    """
+    files = _find_percent_notebook_py_files()
+    if not files:
+        print("No percent notebook .py files found.")
+        return
+
+    groups, errors = _run_jupytext(["--sync"], files)
+    if groups["updated"]:
+        print(_fmt("sync updated", groups["updated"]))
+    if groups["unchanged"]:
+        print(_fmt("sync unchanged", groups["unchanged"]))
+    if groups["skipped"]:
+        print(_fmt("sync skipped (not paired)", groups["skipped"]))
+    if not any(groups.values()):
+        print("Sync: nothing to do")
+    for err in errors:
+        print(f"sync error: {err}")
+    if errors:
+        raise SystemExit(1)
+
+
+def generate_notebooks() -> None:
+    """Generate `.ipynb` files from `.py` percent-format files.
+
+    Calls `jupytext --to notebook` on every paired `.py` file found in the
+    configured `notebook_src_dirs`. Use this after cloning a repo where only
+    the `.py` sources are committed.
+
+    Prints a summary of created/updated, unchanged, and skipped files.
+    Raises `SystemExit(1)` if jupytext reports any errors.
+    """
+    files = _find_percent_notebook_py_files()
+    if not files:
+        print("No percent notebook .py files found.")
+        return
+
+    groups, errors = _run_jupytext(["--to", "notebook"], files)
+    if groups["updated"]:
+        print(_fmt("nb created/updated", groups["updated"]))
+    if groups["unchanged"]:
+        print(_fmt("nb unchanged", groups["unchanged"]))
+    if groups["skipped"]:
+        print(_fmt("nb skipped", groups["skipped"]))
+    if not any(groups.values()):
+        print("Notebooks: nothing to do")
+    for err in errors:
+        print(f"nb error: {err}")
+    if errors:
+        raise SystemExit(1)
+
+
+def clean_notebooks() -> None:
+    """Sync then delete all `.ipynb` files from the source directories.
+
+    First calls `sync_notebooks()` to flush any unsaved changes from the
+    `.ipynb` files back into their paired `.py` sources, then removes every
+    `.ipynb` found under `notebook_src_dirs`. Keeps the working directory
+    clean for AI agents and CI environments that only need the `.py` sources.
+
+    Prints a summary of removed files.
+    """
+    sync_notebooks()
+    removed = []
+    for src_dir in _get_src_dirs():
+        for f in src_dir.rglob("*.ipynb"):
+            removed.append(f.name)
+            f.unlink()
+    if removed:
+        print(_fmt("clean removed", sorted(removed)))
+    else:
+        print("clean: nothing to remove")

juplit-0.0.1/juplit/testing.py

@@ -0,0 +1,27 @@
+"""test() helper — separates exportable logic from inline tests."""
+
+import sys
+
+
+def test() -> bool:
+    """Return True when the calling module is run directly or under pytest.
+
+    Use this to gate test code in percent-format notebook files so that tests
+    run interactively (in Jupyter) and under pytest, but never on import.
+
+    Example::
+
+        # %%
+        from juplit import test
+
+        # %%
+        def add(a, b):
+            return a + b
+
+        # %%
+        if test():
+            assert add(1, 2) == 3
+    """
+    frame = sys._getframe(1)
+    caller_name = frame.f_globals.get("__name__", "")
+    return caller_name == "__main__" or "pytest" in sys.modules

juplit-0.0.1/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "juplit"
+version = "0.0.1"
+description = "Jupytext percent-format notebook workflow manager"
+requires-python = ">=3.12"
+dependencies = [
+    "jupytext>=1.16.0",
+    "cyclopts>=2.0.0",
+]
+
+[project.scripts]
+juplit = "juplit.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.21,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+
+[tool.uv.build-backend.wheel]
+include = ["juplit/SKILL.md", "juplit/SKILL_migrate_from_nbdev.md"]
+
+[dependency-groups]
+dev = [
+    "poethepoet>=0.25.0",
+    "pytest>=8.0.0",
+    "ipykernel>=6.0.0",
+    "pre-commit>=3.0.0",
+    "mkdocs>=1.5.0",
+    "mkdocs-material>=9.0.0",
+    "mkdocs-jupyter>=0.24.0",
+    "mkdocstrings[python]>=0.24.0",
+]
+
+[tool.poe.tasks]
+init         = {cmd = "pre-commit install", help = "Install git hooks"}
+sync         = {script = "juplit.tasks:sync_notebooks", help = "Sync .py<->ipynb for all paired notebooks"}
+nb           = {script = "juplit.tasks:generate_notebooks", help = "Generate .ipynb from .py files (run after cloning)"}
+clean        = {script = "juplit.tasks:clean_notebooks", help = "Sync then delete all .ipynb files"}
+test         = {cmd = "pytest", help = "Run tests"}
+docs         = {sequence = [{ref = "sync"}, {cmd = "mkdocs serve"}], help = "Sync notebooks then serve docs locally for preview"}
+docs-build   = {sequence = [{ref = "sync"}, {cmd = "mkdocs build"}], help = "Sync notebooks then build docs site"}
+docs-deploy  = {sequence = [{ref = "sync"}, {cmd = "mkdocs gh-deploy --force"}], help = "Sync notebooks then deploy docs to GitHub Pages"}
+
+[tool.poe.tasks.pypi]
+help = "Build the package and publish to PyPI"
+sequence = [
+    {ref = "_check_env UV_PUBLISH_TOKEN"},
+    {cmd = "rm -rf dist/*"},
+    {cmd = "uv build"},
+    {cmd = "uv publish"},
+]
+
+[tool.poe.tasks._check_env]
+help = "Assert an env var is set before proceeding"
+script = "juplit._dev:check_env"
+args = [{name = "env_name", positional = true}]
+
+[tool.juplit]
+notebook_src_dirs = ["juplit", "docs"]
+
+[tool.jupytext]
+formats = "ipynb,py:percent"
+
+[tool.pytest.ini_options]
+python_files = ["*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]