afterpython 0.0.1.dev2__py3-none-any.whl → 0.1.0.dev5__py3-none-any.whl

afterpython/cli/commands/check.py

@@ -0,0 +1,36 @@
+import subprocess
+
+import click
+from click.exceptions import Exit
+
+
+@click.command(
+    add_help_option=False,  # disable click's --help option so that ruff check --help can work
+    context_settings=dict(
+        ignore_unknown_options=True,
+        allow_extra_args=True,
+    ),
+)
+@click.pass_context
+def check(ctx):
+    """Simple wrapper for ruff check for convenience, always use the afterpython/ruff.toml if it exists"""
+    from afterpython.utils import handle_passthrough_help
+
+    # Show both our options and ruff's help and exit
+    handle_passthrough_help(
+        ctx,
+        ["ruff", "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)
+    if result.returncode != 0:
+        raise Exit(result.returncode)

afterpython/cli/commands/clean.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from afterpython._typing import NodeEnv
+
+import shutil
+import subprocess
+
+import click
+from click.exceptions import Exit
+
+from afterpython.utils import find_node_env, has_content_for_myst
+from afterpython.const import CONTENT_TYPES
+
+
+@click.command(
+    add_help_option=False,  # disable click's --help option so that ap clean --help can work
+    context_settings=dict(
+        ignore_unknown_options=True,
+        allow_extra_args=True,
+    ),
+)
+@click.pass_context
+@click.option(
+    "--all",
+    is_flag=True,
+    help='--all passed to "myst clean", also clean afterpython build directories (_build/ and _website/build/)',
+)
+def clean(ctx, all: bool):
+    """Clean the build directory"""
+    from afterpython.utils import handle_passthrough_help
+
+    # Show both our options and myst's help and exit
+    handle_passthrough_help(
+        ctx,
+        ["myst", "clean"],
+        show_underlying=True,
+    )
+
+    paths = ctx.obj["paths"]
+    node_env: NodeEnv = find_node_env()
+
+    # Clean MyST builds for each content type
+    for content_type in CONTENT_TYPES:
+        content_path = paths.afterpython_path / content_type
+
+        # Skip if no content exists
+        if not has_content_for_myst(content_path):
+            click.echo(f"Skipping {content_type}/ (no content found)")
+            continue
+
+        click.echo(f"Cleaning {content_type}/...")
+        # Pass through any extra args to myst clean (e.g., --cache, --templates)
+        result = subprocess.run(
+            ["myst", "clean", *ctx.args, *(["--all"] if all else [])],
+            cwd=content_path,
+            env=node_env,
+            check=False,
+        )
+        if result.returncode != 0:
+            raise Exit(result.returncode)
+
+    # Clean afterpython's build directories if --all flag is used
+    if all:
+        click.echo("Cleaning afterpython build directories...")
+
+        # Clean _build/
+        build_path = paths.build_path
+        if build_path.exists():
+            shutil.rmtree(build_path)
+            click.echo(f"  Removed: {build_path}")
+
+        # Clean _website/build/
+        website_build = paths.website_path / "build"
+        if website_build.exists():
+            shutil.rmtree(website_build)
+            click.echo(f"  Removed: {website_build}")
+
+        click.echo("Done cleaning all build directories!")
+    else:
+        click.echo(
+            "Done! Use 'ap clean --all' to also remove afterpython build directories."
+        )

afterpython/cli/commands/commit.py

@@ -0,0 +1,34 @@
+import os
+import subprocess
+
+import click
+
+
+@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
+@click.option(
+    "--no-cz", "--no-commitizen", is_flag=True, help="Skip running 'cz commit'"
+)
+def commit(ctx, no_cz: bool):
+    """Run 'cz commit'"""
+    from afterpython.utils import handle_passthrough_help
+
+    # Show both our options and commitizen's help and exit
+    handle_passthrough_help(
+        ctx,
+        ["cz", "commit"],
+        show_underlying=True,
+    )
+
+    if not no_cz:
+        subprocess.run(["ap", "cz", "commit", *ctx.args])
+    else:
+        env = os.environ.copy()
+        env["SKIP"] = "commitizen,commitizen-branch"
+        subprocess.run(["git", "commit", *ctx.args], env=env)

afterpython/cli/commands/commitizen.py

@@ -0,0 +1,32 @@
+import subprocess
+
+import click
+from click.exceptions import Exit
+
+
+@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 commitizen(ctx):
+    """Run commitizen"""
+    from afterpython.utils import handle_passthrough_help
+
+    # Show both our options and commitizen's help and exit
+    handle_passthrough_help(
+        ctx,
+        ["cz"],
+        show_underlying=True,
+    )
+
+    paths = ctx.obj["paths"]
+    cz_toml_path = paths.afterpython_path / "cz.toml"
+    result = subprocess.run(
+        ["cz", "--config", str(cz_toml_path), *ctx.args], check=False
+    )
+    if result.returncode != 0:
+        raise Exit(result.returncode)

afterpython/cli/commands/dev.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from afterpython._typing import NodeEnv
+
+import time
+import subprocess
+
+import click
+from click.exceptions import Exit
+
+from afterpython.utils import find_node_env, find_available_port
+from afterpython.const import CONTENT_TYPES
+
+
+@click.command(
+    add_help_option=False,  # disable click's --help option so that ap dev --help can work
+    context_settings=dict(
+        ignore_unknown_options=True,
+        allow_extra_args=True,
+    ),
+)
+@click.pass_context
+@click.option(
+    "--all",
+    is_flag=True,
+    help="Start the development server for all content types and the project website",
+)
+@click.option(
+    "--execute", is_flag=True, help="Execute Jupyter notebooks for all content types"
+)
+@click.option(
+    "--no-website",
+    is_flag=True,
+    help="Skip running the website dev server (pnpm dev). Useful when you want to run pnpm dev manually with custom options.",
+)
+def dev(ctx, all: bool, execute: bool, no_website: bool):
+    """Run the development server for the project website.
+
+    If --all is enabled, starts MyST dev servers for all content types (doc/blog/tutorial/example/guide)
+    and the project website.
+
+    Any extra arguments are passed to the MyST servers (via 'ap doc/blog/tutorial/example/guide' commands).
+    See "myst start --help" for more details.
+
+    Use --execute to execute Jupyter notebooks for all content types.
+
+    Use --no-website to skip the automatic 'pnpm dev' command, allowing you to run it manually
+    with custom Vite options in the afterpython/_website directory.
+    """
+
+    from afterpython.utils import handle_passthrough_help
+
+    # Show both our options and myst's help and exit
+    handle_passthrough_help(
+        ctx,
+        ["myst", "start"],
+        show_underlying=True,
+    )
+
+    # Track all MyST processes for cleanup
+    myst_processes = []
+
+    paths = ctx.obj["paths"]
+
+    # OPTIMIZE: should implement incremental build?
+    subprocess.run(["ap", "build", "--dev"])
+
+    def cleanup_processes():
+        """Clean up all MyST server processes"""
+        click.echo("\nShutting down MyST servers...")
+        for proc in myst_processes:
+            try:
+                proc.terminate()
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+            except Exception:
+                pass
+
+    try:
+        if all:
+            # Clear .env.development before writing new ports
+            env_file = paths.website_path / ".env.development"
+            env_file.write_text("")  # Clear existing content
+
+            next_port = 3000
+            for content_type in CONTENT_TYPES:
+                # Find available port for MyST server
+                myst_port = find_available_port(start_port=next_port)
+                next_port = myst_port + 1
+                click.echo(
+                    click.style(
+                        f"Starting MyST {content_type} server on port {myst_port}...",
+                        fg="green",
+                    )
+                )
+
+                # Append port to .env.development for SvelteKit
+                with open(env_file, "a") as f:
+                    f.write(
+                        f"PUBLIC_{content_type.upper()}_URL=http://localhost:{myst_port}\n"
+                    )
+
+                myst_process = subprocess.Popen(
+                    [
+                        "ap",
+                        f"{content_type}",
+                        "--port",
+                        str(myst_port),
+                        *(["--execute"] if execute else []),
+                        *ctx.args,
+                    ],
+                    # stdout=subprocess.DEVNULL,  # Suppress output (optional)
+                    # stderr=subprocess.DEVNULL,  # Suppress errors (optional)
+                )
+                myst_processes.append(myst_process)
+
+                # NOTE: MyST internally uses additional ports beyond the one specified by --port.
+                # Without this delay, multiple MyST servers may attempt to bind to the same internal port,
+                # causing "address already in use" errors.
+                time.sleep(3)
+
+        if not no_website:
+            node_env: NodeEnv = find_node_env()
+            click.echo("Running the web dev server...")
+            result = subprocess.run(
+                ["pnpm", "dev"], cwd=paths.website_path, env=node_env, check=False
+            )
+            if result.returncode != 0:
+                raise Exit(result.returncode)
+        else:
+            click.echo(
+                "Skipping website dev server (--no-website flag). Run 'pnpm dev' manually in afterpython/_website/ with your custom options."
+            )
+            if all:
+                # Keep the process running to maintain MyST servers
+                click.echo("Press Ctrl+C to stop MyST servers...")
+                while True:
+                    time.sleep(1)
+    except KeyboardInterrupt:
+        # Handle Ctrl+C during subprocess.run
+        pass
+    finally:
+        cleanup_processes()

afterpython/cli/commands/format.py

@@ -0,0 +1,28 @@
+import subprocess
+
+import click
+from click.exceptions import Exit
+
+
+@click.command(
+    add_help_option=False,  # disable click's --help option so that ruff format --help can work
+    context_settings=dict(
+        ignore_unknown_options=True,
+        allow_extra_args=True,
+    ),
+)
+@click.pass_context
+def format(ctx):
+    """Simple wrapper for ruff format for convenience"""
+    from afterpython.utils import handle_passthrough_help
+
+    # Show both our options and ruff's help and exit
+    handle_passthrough_help(
+        ctx,
+        ["ruff", "format"],
+        show_underlying=True,
+    )
+
+    result = subprocess.run(["ruff", "format", *ctx.args], check=False)
+    if result.returncode != 0:
+        raise Exit(result.returncode)

afterpython/cli/commands/init.py

@@ -0,0 +1,98 @@
+import shutil
+import subprocess
+
+import click
+
+import afterpython as ap
+
+
+def init_ruff_toml():
+    from afterpython.tools.pre_commit import update_pre_commit
+
+    afterpython_path = ap.paths.afterpython_path
+    ruff_toml_path = afterpython_path / "ruff.toml"
+    if ruff_toml_path.exists():
+        click.echo(f"Ruff configuration file {ruff_toml_path} already exists")
+        return
+    ruff_template_path = ap.paths.templates_path / "ruff-template.toml"
+    shutil.copy(ruff_template_path, ruff_toml_path)
+    click.echo(f"Created {ruff_toml_path}")
+    # add ruff-pre-commit hook to .pre-commit-config.yaml
+    data_update = {
+        "repos": [
+            {
+                "repo": "https://github.com/astral-sh/ruff-pre-commit",
+                "rev": "v0.14.5",
+                "hooks": [
+                    {
+                        "id": "ruff-check",
+                        "stages": ["pre-commit"],
+                        "args": ["--config", "./afterpython/ruff.toml"],
+                    },
+                    {
+                        "id": "ruff-format",
+                        "stages": ["pre-commit"],
+                        "args": ["--config", "./afterpython/ruff.toml"],
+                    },
+                ],
+            },
+        ]
+    }
+    update_pre_commit(data_update)
+
+
+def init_website():
+    click.echo(f"Initializing project website template in {ap.paths.website_path}...")
+    subprocess.run(["ap", "update", "website"])
+
+
+@click.command()
+@click.pass_context
+def init(ctx):
+    """Initialize afterpython with MyST Markdown (by default) and project website template"""
+    from afterpython.tools.pyproject import init_pyproject
+    from afterpython.tools._afterpython import init_afterpython
+    from afterpython.tools.myst import init_myst
+    from afterpython.tools.pre_commit import init_pre_commit
+    from afterpython.tools.commitizen import init_commitizen
+    from afterpython.tools.github_actions import (
+        init_release_workflow,
+        init_deploy_workflow,
+    )
+
+    paths = ctx.obj["paths"]
+    click.echo("Initializing afterpython...")
+    afterpython_path = paths.afterpython_path
+    static_path = paths.static_path
+
+    afterpython_path.mkdir(parents=True, exist_ok=True)
+    static_path.mkdir(parents=True, exist_ok=True)
+    afterpython_path.joinpath("afterpython.toml").touch()
+
+    init_pyproject()
+
+    init_afterpython()
+
+    init_myst()
+
+    # TODO: init faq.yml
+
+    init_website()
+
+    if click.confirm(
+        f"\nCreate .pre-commit-config.yaml in {afterpython_path}?", default=True
+    ):
+        init_pre_commit()
+
+    if click.confirm(f"\nCreate ruff.toml in {afterpython_path}?", default=True):
+        init_ruff_toml()
+
+    if click.confirm(
+        f"\nCreate commitizen configuration (cz.toml) in {afterpython_path} "
+        f"and release workflow in .github/workflows/release.yml?",
+        default=True,
+    ):
+        init_commitizen()
+        init_release_workflow()
+
+    init_deploy_workflow()

afterpython/cli/commands/install.py

@@ -0,0 +1,22 @@
+import subprocess
+
+import click
+from click.exceptions import Exit
+
+from afterpython.utils import has_uv
+
+
+@click.command(
+    context_settings=dict(
+        ignore_unknown_options=True,
+        allow_extra_args=True,
+    )
+)
+def install():
+    """Run 'uv sync --all-extras --all-groups' to install all dependencies"""
+    if not has_uv():
+        click.echo("uv not found. Please install uv first.")
+        return
+    result = subprocess.run(["uv", "sync", "--all-extras", "--all-groups"], check=False)
+    if result.returncode != 0:
+        raise Exit(result.returncode)

afterpython/cli/commands/pre_commit.py

@@ -0,0 +1,66 @@
+import subprocess
+
+import click
+from click.exceptions import Exit
+
+
+def _command_supports_config(command: str) -> bool:
+    """Check if a pre-commit command supports --config flag by checking its help text."""
+    try:
+        result = subprocess.run(
+            ["pre-commit", command, "--help"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        return "--config" in result.stdout
+    except Exception:
+        return False
+
+
+@click.command(
+    add_help_option=False,  # disable click's --help option so that pre-commit --help can work
+    context_settings=dict(
+        ignore_unknown_options=True,
+        allow_extra_args=True,
+    ),
+)
+@click.pass_context
+def pre_commit(ctx):
+    """Run pre-commit, always use the afterpython/.pre-commit-config.yaml if it exists"""
+    from afterpython.utils import handle_passthrough_help
+
+    # Show both our options and pre-commit's help and exit
+    handle_passthrough_help(
+        ctx,
+        ["pre-commit"],
+        show_underlying=True,
+    )
+
+    args = ctx.args[:]
+    paths = ctx.obj["paths"]
+
+    # Find the first command in args (skip any flags that might come before the command)
+    command: str | None = None
+    command_idx: int | None = None
+    for i, arg in enumerate(args):
+        if not arg.startswith("-"):
+            command = arg
+            command_idx = i
+            break
+
+    # If we found a command and --config is not already specified
+    if (
+        command
+        and command_idx is not None
+        and "--config" not in args
+        and _command_supports_config(command)
+    ):
+        pre_commit_path = paths.afterpython_path / ".pre-commit-config.yaml"
+        # Insert --config right after the command
+        args.insert(command_idx + 1, "--config")
+        args.insert(command_idx + 2, str(pre_commit_path))
+
+    result = subprocess.run(["pre-commit", *args], check=False)
+    if result.returncode != 0:
+        raise Exit(result.returncode)

afterpython/cli/commands/preview.py

@@ -0,0 +1,22 @@
+import subprocess
+
+import click
+from click.exceptions import Exit
+
+
+@click.command()
+@click.pass_context
+def preview(ctx):
+    """Preview the production build of the project website (including myst's builds)"""
+    from afterpython.utils import find_node_env
+
+    paths = ctx.obj["paths"]
+    node_env = find_node_env()
+    click.echo(
+        "Previewing the production build of the project website (including myst's builds)..."
+    )
+    result = subprocess.run(
+        ["pnpm", "preview"], cwd=paths.website_path, env=node_env, check=False
+    )
+    if result.returncode != 0:
+        raise Exit(result.returncode)

afterpython/cli/commands/release.py

@@ -0,0 +1,67 @@
+import subprocess
+
+import click
+
+
+@click.command()
+@click.option(
+    "--force",
+    "-f",
+    is_flag=True,
+    help="Force release even for dev versions (not recommended)",
+)
+def release(force: bool):
+    """Manually trigger a release by pushing the current version tag.
+
+    This command is used to manually publish dev versions or pre-releases to PyPI
+    and create GitHub releases. It pushes the tag for the current version, which
+    triggers the GitHub Actions release workflow.
+
+    By default, releases are only allowed for non-dev versions (stable releases
+    and pre-releases like rc, alpha, beta). Use --force to release dev versions.
+
+    The release workflow will:
+    - Run tests in CI
+    - Publish to PyPI (if tests pass)
+    - Create a GitHub release (if tests pass)
+
+    Examples:
+        ap bump --pre      # Bump to pre-release (e.g., 0.1.0rc1)
+        ap release         # Push tag → triggers release workflow
+
+        ap bump            # Bump dev version (e.g., 0.1.0.dev4)
+        ap release --force # Push tag → triggers release workflow (dev version)
+    """
+    from afterpython.tools.pyproject import read_metadata
+
+    # Get current version from pyproject.toml
+    metadata = read_metadata()
+    version = metadata.version
+
+    if version is None:
+        raise click.ClickException("Unable to read version from pyproject.toml")
+
+    # Check if this is a dev version
+    if version.is_devrelease and not force:
+        raise click.ClickException(
+            f"Cannot release dev version '{version}' without --force flag.\n"
+            f"Dev versions are typically not published to PyPI.\n"
+            f"Use 'ap bump --release' for stable releases (auto-releases),\n"
+            f"or 'ap bump --pre' then 'ap release' for pre-releases,\n"
+            f"or 'ap release --force' to release this dev version anyway."
+        )
+
+    tag = f"v{version}"
+
+    click.echo(f"🏷️  Pushing tag {tag} to trigger release workflow...")
+    result = subprocess.run(["git", "push", "origin", tag], capture_output=False)
+
+    if result.returncode != 0:
+        click.echo(f"\n❌ Failed to push tag (exit code {result.returncode})", err=True)
+        raise click.ClickException("Git push failed")
+
+    click.echo(f"✅ Tag {tag} pushed successfully")
+    click.echo("\n📋 Check GitHub Actions to see the release workflow progress.")
+
+    if version.is_devrelease:
+        click.echo("   ⚠️  Warning: Publishing a dev version to PyPI and GitHub")