afterpython 0.3.18__py3-none-any.whl → 0.4.0__py3-none-any.whl

afterpython/_typing.py

@@ -1,4 +1,4 @@
-from typing import Literal, TypeAlias
+from typing import Literal
 
-NodeEnv: TypeAlias = dict[str, str]
+type NodeEnv = dict[str, str]
 tContentType = Literal["doc", "blog", "tutorial", "example", "guide"]

afterpython/builders/marimo_notebook.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import os
 import re
+import shutil
 import subprocess
 from pathlib import Path
 from typing import Literal
@@ -48,6 +49,12 @@ def _export_marimo(
     execute: bool = False,
 ):
     """Run `marimo export` to produce HTML at `output_html`."""
+    # marimo is an optional dependency (the `marimo` extra)
+    if shutil.which("marimo") is None:
+        raise click.ClickException(
+            f"marimo is required to build {source.name} (a marimo notebook), "
+            'install it with: uv add --dev "afterpython[marimo]"'
+        )
     output_html.parent.mkdir(parents=True, exist_ok=True)
     subcommand = "html-wasm" if mode == "wasm" else "html"
     cmd = [

afterpython/cli/commands/build.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -147,7 +147,7 @@ def postbuild(dev_build: bool = False):
         source: Path,
         destination: Path,
         is_copy: bool = True,
-        ignore_copy: Callable[[str, list[str]], set[str]] | None = None,
+        ignore_copy: Callable[[str, list[str]], Iterable[str]] | None = None,
     ):
         """
         Move or copy files from source to destination.
@@ -156,7 +156,7 @@ def postbuild(dev_build: bool = False):
             source: Source path
             destination: Destination path
             is_copy: If True, copy files (merge with existing). If False, move files (replace destination)
-            ignore_copy: Optional ignore function for copytree, takes (directory, contents) and returns set of names to ignore
+            ignore_copy: Optional ignore function for copytree, takes (directory, contents) and returns the names to ignore
         """
         if not source.exists():
             return

afterpython/cli/commands/bump.py

@@ -1,118 +1,333 @@
+import os
 import subprocess
+import sys
 
 import click
-from click.exceptions import Exit
+from packaging.version import Version
 
-from afterpython.utils import has_pixi
+# uv's --bump names for PEP 440 pre-release markers
+PRE_KINDS = {"a": "alpha", "b": "beta", "rc": "rc"}
+CHANGELOG = "CHANGELOG.md"
+# git-cliff ignores pre-release and dev tags (e.g. v0.4.0rc1, v0.4.0.dev2),
+# so a stable release's section has every commit since the previous stable release
+PRE_RELEASE_TAGS = "(a|b|rc|dev)[0-9]+"
 
 
-@click.command(
-    add_help_option=False,  # disable click's --help option so that cz --help can work
-    context_settings=dict(
-        ignore_unknown_options=True,
-        allow_extra_args=True,
-    ),
-)
-@click.pass_context
+def _uv_version_args(
+    version: Version, release: bool, pre: bool, level: str
+) -> list[str]:
+    """Arguments for `uv version`, either `--bump ...` or an exact version"""
+    is_stable = not version.is_prerelease  # dev versions count as pre-releases too
+    if not is_stable and level != "patch":
+        raise click.ClickException(
+            f"--{level} only applies to stable versions, current version is {version}"
+        )
+    if release:
+        # e.g. 0.1.0rc0 -> 0.1.0, 0.3.19 -> 0.3.20
+        return ["--bump", "stable" if not is_stable else level]
+    if is_stable:
+        # e.g. 0.3.19 -> 0.3.20 (or 0.3.20rc0 with --pre)
+        return ["--bump", level, *(["--bump", "rc=0"] if pre else [])]
+    if version.is_devrelease:
+        if not pre:
+            # e.g. 0.1.0.dev3 -> 0.1.0.dev4
+            return ["--bump", "dev"]
+        if version.pre is None:
+            # e.g. 0.1.0.dev3 -> 0.1.0rc0
+            return ["--bump", "rc=0"]
+        # e.g. 0.1.0rc0.dev2 -> 0.1.0rc0 (uv's --bump rc would skip to rc1)
+        kind, number = version.pre
+        return [str(Version(f"{version.base_version}{kind}{number}"))]
+    # e.g. 0.1.0a1 -> 0.1.0a2, 0.1.0rc0 -> 0.1.0rc1
+    assert version.pre is not None  # not stable and not dev, so it's a pre-release
+    return ["--bump", PRE_KINDS[version.pre[0]]]
+
+
+def _git(*args: str) -> subprocess.CompletedProcess:
+    import afterpython as ap
+
+    return subprocess.run(
+        ["git", *args],
+        cwd=ap.paths.user_path,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def _restore(files: list[str], new_files: list[str]):
+    """Undo the version bump in the working tree and index"""
+    import afterpython as ap
+
+    _git("restore", "--source=HEAD", "--staged", "--worktree", "--", *files)
+    for file in new_files:
+        # --force, a hook (e.g. end-of-file-fixer) may have changed the file after it was staged
+        _git("rm", "--cached", "--force", "--quiet", "--ignore-unmatch", "--", file)
+        (ap.paths.user_path / file).unlink(missing_ok=True)
+    click.echo(f"↩️  Restored {', '.join(files + new_files)}", err=True)
+
+
+def _write_changelog(tag: str):
+    """Write the release section for tag to CHANGELOG.md with git-cliff"""
+    import afterpython as ap
+
+    cmd = [
+        "git-cliff",
+        "--config",
+        str(ap.paths.afterpython_path / "cliff.toml"),
+        "--tag",
+        tag,
+        "--ignore-tags",
+        PRE_RELEASE_TAGS,
+    ]
+    if (ap.paths.user_path / CHANGELOG).exists():
+        # only add the new section on top, keeping manual edits to older ones;
+        # a range from the previous stable tag, since --unreleased would drop
+        # the commits before an ignored pre-release tag (e.g. v0.4.1rc0)
+        previous = _git(
+            "describe",
+            "--tags",
+            "--abbrev=0",
+            "--match",
+            "v*",
+            *(f"--exclude=*{kind}[0-9]*" for kind in ("a", "b", "rc", "dev")),
+        ).stdout.strip()
+        cmd += [f"{previous}..HEAD" if previous else "--unreleased"]
+        cmd += ["--prepend", CHANGELOG]
+    else:
+        # git-cliff can't prepend to a missing file, so create it from the full history
+        cmd += ["--output", CHANGELOG]
+    result = subprocess.run(
+        cmd, cwd=ap.paths.user_path, capture_output=True, text=True, check=False
+    )
+    if result.returncode != 0:
+        raise click.ClickException(f"git-cliff failed:\n{result.stderr.strip()}")
+    # the blank line after each release also ends up at the end of the file,
+    # end it with a single newline as end-of-file-fixer wants
+    path = ap.paths.user_path / CHANGELOG
+    path.write_text(path.read_text().rstrip("\n") + "\n")
+
+
+def _is_interactive() -> bool:
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def _edit_changelog():
+    """Open CHANGELOG.md in git's editor, the bump continues once it's closed"""
+    import afterpython as ap
+
+    result = _git("var", "GIT_EDITOR")
+    if result.returncode != 0:
+        raise click.ClickException(
+            f"Failed to find git's editor:\n{result.stderr.strip()}"
+        )
+    editor = result.stdout.strip()
+    click.echo(
+        f"✏️  Opening {CHANGELOG} in {editor}, save and close it to commit the bump "
+        "(to abort, press Ctrl+C or exit the editor with an error, e.g. :cq in vim)"
+    )
+    # raises ClickException if the editor exits with an error, which rolls back the bump
+    click.edit(filename=str(ap.paths.user_path / CHANGELOG), editor=editor)
+
+
+@click.command()
 @click.option(
     "--pre",
     is_flag=True,
-    help="bump to pre-release version (e.g., dev3 -> rc0, a1 -> a2)",
+    help="bump to pre-release version (e.g., 0.1.0.dev3 -> 0.1.0rc0, 0.1.0a1 -> 0.1.0a2)",
+)
+@click.option(
+    "--release",
+    is_flag=True,
+    help="bump to stable version (e.g., 0.1.0rc0 -> 0.1.0, 0.3.19 -> 0.3.20) and push it with its tag to trigger the release workflow (default branch only)",
 )
 @click.option(
-    "--release", is_flag=True, help="bump to stable release (uses cz bump default)"
+    "--minor",
+    is_flag=True,
+    help="bump the minor version instead of patch (stable versions only, e.g., 0.3.19 -> 0.4.0)",
+)
+@click.option(
+    "--major",
+    is_flag=True,
+    help="bump the major version instead of patch (stable versions only, e.g., 0.3.19 -> 1.0.0)",
+)
+@click.option(
+    "--no-edit",
+    is_flag=True,
+    help="don't open CHANGELOG.md in git's editor before committing a stable bump",
 )
-def bump(ctx, release: bool, pre: bool):
-    """Bump project version with granular control.
+@click.option(
+    "--dry-run", is_flag=True, help="show the new version without changing anything"
+)
+def bump(
+    release: bool, pre: bool, minor: bool, major: bool, no_edit: bool, dry_run: bool
+):
+    """Bump project version, commit it and tag it.
 
+    \b
     By default, stays within current release phase:
     - Dev releases (e.g., 0.1.0.dev3) -> increment dev number (0.1.0.dev4)
     - Pre-releases (e.g., 0.1.0a1) -> increment pre-release (0.1.0a2)
+    - Stable releases (e.g., 0.3.19) -> increment patch (0.3.20), or --minor/--major
 
     Use --pre to transition from dev to pre-release, or pre-release to next pre-release.
-    Use --release to bump to next stable version (cz bump default behavior).
+    Stable bumps also add the new release section to CHANGELOG.md with git-cliff
+    (if afterpython/cliff.toml exists, see `ap init cliff`) and open it in git's editor,
+    the bump is committed once you close it (use --no-edit to skip).
+    Use --release to bump to a stable version and push it with its tag (triggers the release workflow),
+    only allowed on the default branch (e.g. main).
     """
+    import afterpython as ap
+    from afterpython.tools._git import check_release_branch
     from afterpython.tools.pyproject import read_metadata
-    from afterpython.utils import handle_passthrough_help
-
-    # Show both our options and commitizen's help and exit
-    handle_passthrough_help(
-        ctx,
-        ["cz", "bump"],
-        show_underlying=True,
-    )
+    from afterpython.utils import has_pixi
 
     if release and pre:
         raise click.ClickException("Only one of --release or --pre can be specified")
+    if minor and major:
+        raise click.ClickException("Only one of --minor or --major can be specified")
+    level = "minor" if minor else "major" if major else "patch"
 
-    # bump using cz bump's default behavior
+    # before changing anything, so a wrong branch doesn't leave a bump behind
     if release:
-        subprocess.run(["ap", "cz", "bump", *ctx.args])
+        check_release_branch()
 
-        # Skip tag push if this is a dry run
-        if "--dry-run" in ctx.args:
-            return
+    version = read_metadata().version
+    if version is None:
+        raise click.ClickException("Unable to read version from pyproject.toml")
+    uv_args = _uv_version_args(version, release, pre, level)
 
-        # Get the new version after bump
-        metadata = read_metadata()
-        new_version = metadata.version
-        if new_version is None:
-            raise click.ClickException("Unable to read version after bump")
+    user_path = ap.paths.user_path
+    # without uv.lock, --frozen stops uv from creating one; with it, uv updates it
+    has_uv_lock = (user_path / "uv.lock").exists()
+    uv_lock_arg = "--no-sync" if has_uv_lock else "--frozen"
+    result = subprocess.run(
+        ["uv", "version", *uv_args, "--dry-run", "--short", "--frozen"],
+        cwd=user_path,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise click.ClickException(result.stderr.strip())
+    new_version = result.stdout.strip()
+    tag = f"v{new_version}"
 
-        tag = f"v{new_version}"
+    uses_pixi = (user_path / "pixi.lock").exists()
+    if uses_pixi and not has_pixi():
+        click.echo("⚠️  pixi.lock found but pixi is not installed, skip updating it")
+        uses_pixi = False
+    candidates = [
+        "pyproject.toml",
+        *(["uv.lock"] if has_uv_lock else []),
+        *(["pixi.lock"] if uses_pixi else []),
+    ]
+    # only stable bumps write the changelog, and only when afterpython/cliff.toml was set up
+    writes_changelog = (
+        not Version(new_version).is_prerelease
+        and (ap.paths.afterpython_path / "cliff.toml").exists()
+    )
+    if writes_changelog:
+        candidates.append(CHANGELOG)
+    # no editor in CI or tests
+    edits_changelog = writes_changelog and not no_edit and _is_interactive()
+    files = _git("ls-files", "--", *candidates).stdout.split()
+    if "pyproject.toml" not in files:
+        raise click.ClickException("pyproject.toml is not tracked by git")
+    # CHANGELOG.md created by this bump, removed again if the bump fails
+    new_files: list[str] = []
+    if writes_changelog and CHANGELOG not in files:
+        if (user_path / CHANGELOG).exists():
+            raise click.ClickException(
+                f"{CHANGELOG} exists but is not tracked by git, commit or remove it first"
+            )
+        new_files.append(CHANGELOG)
 
-        # Auto-push the specific tag to trigger release workflow
-        click.echo(f"\n🚀 Pushing tag {tag} to trigger release workflow...")
-        subprocess.run(["git", "push", "origin", tag])
-    else:
-        metadata = read_metadata()
-        version = metadata.version
-
-        if version is None:
-            raise click.ClickException("Unable to read version from pyproject.toml")
-
-        args = ctx.args  # default: pass through all extra args
-
-        # by default, bump dev-release version
-        if version.is_devrelease and not pre:
-            devrelease_number = int(version.dev) if version.dev is not None else 0
-            if "--devrelease" not in ctx.args:
-                args = ["--devrelease", str(devrelease_number + 1), *ctx.args]
-        # exclude e.g. 0.1.0.dev1 which is both dev-release and pre-release (with version.pre = None)
-        elif version.is_prerelease:
-            prerelease_type = version.pre[0] if version.pre is not None else "rc"
-            if prerelease_type == "a":
-                prerelease_type = "alpha"
-            elif prerelease_type == "b":
-                prerelease_type = "beta"
-            if "--prerelease" not in ctx.args:
-                args = ["--prerelease", prerelease_type, *ctx.args]
-
-        subprocess.run(["ap", "cz", "bump", *args])
-
-    # Update pixi.lock after version bump (editable install requires lock refresh)
-    if has_pixi():
-        result = subprocess.run(["pixi", "install"], check=False)
+    # the bump commit only contains the version change
+    dirty = _git("status", "--porcelain", "--", *files).stdout.strip()
+    if dirty:
+        raise click.ClickException(
+            f"Commit or stash your changes to these files first:\n{dirty}"
+        )
+    if _git("rev-parse", "--quiet", "--verify", f"refs/tags/{tag}").returncode == 0:
+        raise click.ClickException(f"Tag {tag} already exists")
+    # otherwise uv would re-lock other packages into the bump commit
+    if has_uv_lock and (
+        subprocess.run(
+            ["uv", "lock", "--check"], cwd=user_path, capture_output=True, check=False
+        ).returncode
+        != 0
+    ):
+        raise click.ClickException(
+            "uv.lock is out of date, run `uv lock` and commit it first"
+        )
+
+    if dry_run:
+        click.echo(f"{version} → {new_version}")
+        if writes_changelog:
+            click.echo(f"Would write the {new_version} section to {CHANGELOG}")
+            if edits_changelog:
+                click.echo(f"Would open {CHANGELOG} in git's editor before committing")
+        click.echo(f"Would commit {', '.join(files + new_files)} and create tag {tag}")
+        if release:
+            click.echo(f"Would push the current branch and tag {tag} to origin")
+        return
+
+    try:
+        result = subprocess.run(
+            ["uv", "version", *uv_args, uv_lock_arg], cwd=user_path, check=False
+        )
         if result.returncode != 0:
-            raise Exit(result.returncode)
+            raise click.ClickException("uv version failed")
+        if read_metadata().version != Version(new_version):
+            raise click.ClickException(
+                f"Expected version {new_version} in pyproject.toml after the bump"
+            )
+        # refresh the pixi env; older pixi versions also record the editable version in pixi.lock
+        if uses_pixi:
+            result = subprocess.run(["pixi", "install"], cwd=user_path, check=False)
+            if result.returncode != 0:
+                raise click.ClickException("pixi install failed")
+        if writes_changelog:
+            _write_changelog(tag)
+            click.echo(f"📝 Wrote the {new_version} section to {CHANGELOG}")
+        if edits_changelog:
+            _edit_changelog()
+        if new_files:
+            # `git commit -- <files>` only takes files git already knows about
+            result = _git("add", "--", *new_files)
+            if result.returncode != 0:
+                raise click.ClickException(f"git add failed:\n{result.stderr.strip()}")
 
-        # Check if pixi.lock was modified
-        status = subprocess.run(
-            ["git", "diff", "--name-only", "pixi.lock"],
-            capture_output=True,
-            text=True,
+        # skip the commit message check, "bump" is not one of the commit types
+        env = os.environ.copy()
+        env["SKIP"] = ",".join(filter(None, [env.get("SKIP"), "ap-commit"]))
+        message = f"bump: version {version} → {new_version}"
+        # `git commit -- <files>` commits only these files, leaving anything else staged as is
+        result = subprocess.run(
+            ["git", "commit", "-m", message, "--", *files, *new_files],
+            cwd=user_path,
+            env=env,
             check=False,
         )
-        if status.stdout.strip():
-            # Stage and commit pixi.lock
-            subprocess.run(["git", "add", "pixi.lock"], check=True)
-            subprocess.run(
-                [
-                    "git",
-                    "commit",
-                    "-m",
-                    "build: update pixi.lock after version bump",
-                ],
-                check=True,
+        if result.returncode != 0:
+            raise click.ClickException("git commit failed")
+    except (click.ClickException, KeyboardInterrupt):
+        _restore(files, new_files)
+        raise
+
+    result = _git("tag", tag)
+    if result.returncode != 0:
+        raise click.ClickException(
+            f"Committed the bump but failed to create tag {tag}:\n{result.stderr.strip()}"
+        )
+    click.echo(f"✅ Bumped {version} → {new_version} and tagged {tag}")
+
+    if release:
+        # ap release pushes the branch and the tag, which triggers the release workflow
+        click.echo()
+        result = subprocess.run(["ap", "release"], cwd=user_path, check=False)
+        if result.returncode != 0:
+            raise click.ClickException(
+                f"Bumped and tagged {tag} but didn't push it, retry with: ap release"
             )
-            click.echo("✓ Committed pixi.lock update")

afterpython/cli/commands/changelog.py

@@ -0,0 +1,45 @@
+import subprocess
+
+import click
+from click.exceptions import Exit
+
+import afterpython as ap
+
+
+@click.command(
+    add_help_option=False,  # disable click's --help option so that git-cliff --help can work
+    context_settings=dict(
+        ignore_unknown_options=True,
+        allow_extra_args=True,
+    ),
+)
+@click.pass_context
+def changelog(ctx):
+    """Preview the changelog with git-cliff (using afterpython/cliff.toml)
+
+    \b
+    Without arguments, prints the unreleased changes, i.e. the section
+    the next stable `ap bump` will add to CHANGELOG.md.
+    Any arguments are passed to git-cliff instead, e.g.
+    `ap changelog --latest` for the latest release.
+    """
+    from afterpython.cli.commands.bump import PRE_RELEASE_TAGS
+    from afterpython.utils import handle_passthrough_help
+
+    # Show both our options and git-cliff's help and exit
+    handle_passthrough_help(ctx, ["git-cliff"], show_underlying=True)
+
+    cliff_toml_path = ap.paths.afterpython_path / "cliff.toml"
+    if not cliff_toml_path.exists():
+        raise click.ClickException(
+            f"{cliff_toml_path} not found, run `ap init cliff` first"
+        )
+    cmd = ["git-cliff", "--config", str(cliff_toml_path)]
+    # like `ap bump`: no sections for pre-release and dev tags,
+    # their commits belong to the next stable release
+    if "--ignore-tags" not in ctx.args:
+        cmd += ["--ignore-tags", PRE_RELEASE_TAGS]
+    args = ctx.args or ["--unreleased"]
+    result = subprocess.run([*cmd, *args], cwd=ap.paths.user_path, check=False)
+    if result.returncode != 0:
+        raise Exit(result.returncode)

afterpython/cli/commands/check.py

@@ -1,11 +1,19 @@
+# NOTE: ty has no `extend` option yet (unlike ruff), so we must pass --config-file ourselves,
+# and plain `ty` / editors don't find afterpython/ty.toml without extra setup.
+# TODO: once ty supports `extend`, migrate to pyproject.toml's
+# [tool.ty] extend = "afterpython/ty.toml" (like [tool.ruff]) and drop --config-file here.
+# NOTE: the ty hook runs this command (see pre-commit-config-template.yaml for why it's not
+# the official astral-sh/ty-pre-commit hook), so it uses the same config and environment.
 import subprocess
 
 import click
 from click.exceptions import Exit
 
+import afterpython as ap
+
 
 @click.command(
-    add_help_option=False,  # disable click's --help option so that ruff check --help can work
+    add_help_option=False,  # disable click's --help option so that ty check --help can work
     context_settings=dict(
         ignore_unknown_options=True,
         allow_extra_args=True,
@@ -13,24 +21,23 @@ from click.exceptions import Exit
 )
 @click.pass_context
 def check(ctx):
-    """Run ruff linter (uses afterpython/ruff.toml if available)"""
+    """Run ty type checker"""
     from afterpython.utils import handle_passthrough_help
 
-    # Show both our options and ruff's help and exit
+    # Show both our options and ty's help and exit
     handle_passthrough_help(
         ctx,
-        ["ruff", "check"],
+        ["ty", "check"],
         show_underlying=True,
     )
 
-    paths = ctx.obj["paths"]
-    ruff_toml = paths.afterpython_path / "ruff.toml"
-    if ruff_toml.exists():
-        click.echo(f"Using ruff configuration from {ruff_toml}")
-        result = subprocess.run(
-            ["ruff", "check", "--config", str(ruff_toml), *ctx.args], check=False
-        )
-    else:
-        result = subprocess.run(["ruff", "check", *ctx.args], check=False)
+    # absolute paths so that it works from any folder, e.g. inside afterpython/
+    # (ty would otherwise treat the folder with the nearest ty.toml as the project root)
+    cmd = ["ty", "check", "--project", str(ap.paths.user_path)]
+    ty_toml_path = ap.paths.afterpython_path / "ty.toml"
+    # without afterpython/ty.toml, let ty find its config itself (e.g. the user's own [tool.ty])
+    if ty_toml_path.exists():
+        cmd += ["--config-file", str(ty_toml_path)]
+    result = subprocess.run([*cmd, *ctx.args], check=False)
     if result.returncode != 0:
         raise Exit(result.returncode)