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

afterpython/cli/commands/dev.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from afterpython._typing import NodeEnv
+
+import subprocess
+import time
+
+import click
+from click.exceptions import Exit
+
+from afterpython.cli.commands.build import postbuild, prebuild
+from afterpython.const import CONTENT_TYPES
+from afterpython.utils import find_available_port, find_node_env
+
+
+@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(
+    "--doc",
+    is_flag=True,
+    help="Start the development server for documentation content",
+)
+@click.option(
+    "--blog",
+    is_flag=True,
+    help="Start the development server for blog content",
+)
+@click.option(
+    "--tutorial",
+    is_flag=True,
+    help="Start the development server for tutorial content",
+)
+@click.option(
+    "--example",
+    is_flag=True,
+    help="Start the development server for example content",
+)
+@click.option(
+    "--guide",
+    is_flag=True,
+    help="Start the development server for guide content",
+)
+@click.option(
+    "--execute", is_flag=True, help="Execute Jupyter notebooks for all content types"
+)
+@click.option(
+    "--no-website",
+    "-n",
+    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,
+    doc: bool,
+    blog: bool,
+    tutorial: bool,
+    example: bool,
+    guide: bool,
+    execute: bool,
+    no_website: bool,
+):
+    """Run the development server for the project website.
+
+    By default, runs only the website without any content servers.
+    Use --all to start all content types, or specify individual content types with --doc, --blog, etc.
+
+    Examples:
+      ap dev              # Website only
+      ap dev --all        # Website + all content types
+      ap dev --doc        # Website + doc content
+      ap dev --doc --blog # Website + doc and blog content
+
+    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"]
+
+    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
+
+    # Determine which content types to run
+    if all:
+        enabled_content_types = set(CONTENT_TYPES)
+    else:
+        # Check individual flags
+        content_flags = {
+            "doc": doc,
+            "blog": blog,
+            "tutorial": tutorial,
+            "example": example,
+            "guide": guide,
+        }
+        assert set(content_flags.keys()) == set(CONTENT_TYPES), (
+            "Incomplete content flags"
+        )
+        enabled_content_types = {ct for ct, flag in content_flags.items() if flag}
+
+    try:
+        prebuild()
+
+        # Clear .env.development before writing new ports
+        env_file = paths.website_path / ".env.development"
+        env_file.write_text("")  # Clear existing content
+
+        # myst development servers
+        if enabled_content_types:
+            next_port = 3000
+            for content_type in CONTENT_TYPES:
+                # Skip content types that are not enabled
+                if content_type not in enabled_content_types:
+                    continue
+
+                # 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)
+
+        postbuild(dev_build=True)
+
+        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 enabled_content_types:
+                # 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):
+    """Run ruff formatter"""
+    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,107 @@
+import shutil
+import subprocess
+
+import click
+
+import afterpython as ap
+
+
+def init_ruff_toml():
+    ruff_toml_path = ap.paths.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}")
+
+
+def init_website():
+    click.echo(f"Initializing project website template in {ap.paths.website_path}...")
+    subprocess.run(["ap", "update", "website"])
+
+
+def init_py_typed():
+    from afterpython.tools.pyproject import find_package_directory
+
+    try:
+        package_dir = find_package_directory()
+    except FileNotFoundError:
+        click.echo(
+            "Could not find package directory (__init__.py not found), skipping py-typed initialization"
+        )
+        return
+    py_typed_path = package_dir / "py.typed"
+    if py_typed_path.exists():
+        click.echo(f"py.typed file already exists at {py_typed_path}")
+        return
+    py_typed_path.touch()
+    click.echo(f"Created {py_typed_path}")
+
+
+@click.command()
+@click.option(
+    "--yes",
+    "-y",
+    is_flag=True,
+    help="Automatically answer yes to all prompts",
+)
+@click.pass_context
+def init(ctx, yes):
+    """Initialize AfterPython project structure and website template"""
+    from afterpython.tools._afterpython import init_afterpython
+    from afterpython.tools.commitizen import init_commitizen
+    from afterpython.tools.github_actions import (
+        create_dependabot,
+        create_workflow,
+    )
+    from afterpython.tools.myst import init_myst
+    from afterpython.tools.pre_commit import init_pre_commit
+    from afterpython.tools.pyproject import init_pyproject
+
+    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)
+
+    init_pyproject()
+
+    init_afterpython()
+
+    init_myst()
+
+    # TODO: init faq.yml
+
+    init_website()
+
+    # TODO: add type checking related stuff here
+    init_py_typed()
+
+    create_workflow("deploy")
+    create_workflow("ci")
+
+    if yes or click.confirm(
+        f"\nCreate .pre-commit-config.yaml in {afterpython_path}?", default=True
+    ):
+        init_pre_commit()
+
+    if yes or click.confirm(f"\nCreate ruff.toml in {afterpython_path}?", default=True):
+        init_ruff_toml()
+
+    if yes or click.confirm(
+        f"\nCreate commitizen configuration (cz.toml) in {afterpython_path} "
+        f"and release workflow in .github/workflows/release.yml?",
+        default=True,
+    ):
+        init_commitizen()
+        create_workflow("release")
+
+    if yes or click.confirm(
+        "\nCreate Dependabot configuration (.github/dependabot.yml) "
+        "to auto-update GitHub Actions versions?",
+        default=True,
+    ):
+        create_dependabot()

afterpython/cli/commands/init_branch_rules.py

@@ -0,0 +1,9 @@
+import click
+
+
+@click.command()
+def init_branch_rules():
+    """Create default branch protection rules for the current repository"""
+    from afterpython.tools.branch_rules import create_default_branch_rules
+
+    create_default_branch_rules()

afterpython/cli/commands/install.py

@@ -0,0 +1,28 @@
+import subprocess
+
+import click
+from click.exceptions import Exit
+
+from afterpython.utils import has_pixi, has_uv
+
+
+@click.command(
+    context_settings=dict(
+        ignore_unknown_options=True,
+        allow_extra_args=True,
+    )
+)
+def install():
+    """Install all project dependencies (manages both uv and pixi if present)"""
+    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)
+
+    if has_pixi():
+        result = subprocess.run(["pixi", "install"], check=False)
+        if result.returncode != 0:
+            raise Exit(result.returncode)

afterpython/cli/commands/lock.py

@@ -0,0 +1,23 @@
+import subprocess
+
+import click
+from click.exceptions import Exit
+
+from afterpython.utils import has_pixi, has_uv
+
+
+@click.command()
+def lock():
+    """Lock project dependencies (manages both uv and pixi if present)"""
+    if not has_uv():
+        click.echo("uv not found. Please install uv first.")
+        return
+
+    result = subprocess.run(["uv", "lock"], check=False)
+    if result.returncode != 0:
+        raise Exit(result.returncode)
+
+    if has_pixi():
+        result = subprocess.run(["pixi", "lock"], 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 hooks (uses afterpython/.pre-commit-config.yaml if available)"""
+    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"""
+    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")

afterpython/cli/commands/remove.py

@@ -0,0 +1,67 @@
+import subprocess
+
+import click
+from click.exceptions import Exit
+
+from afterpython.utils import has_pixi, has_uv
+
+
+@click.command()
+@click.option(
+    "--optional",
+    type=str,
+    default=None,
+    required=False,
+    help="Remove from an optional dependency group (pixi: mapped to 'optional' feature)",
+)
+@click.option(
+    "--group",
+    type=str,
+    default=None,
+    required=False,
+    help="Remove from a dependency group (pixi: mapped to same-named feature)",
+)
+@click.argument("lib", type=str, required=True)
+def remove(optional: str | None, group: str | None, lib: str):
+    """Remove a dependency from the project (manages both uv and pixi if present)"""
+    if not has_uv():
+        click.echo("uv not found. Please install uv first.")
+        return
+
+    if optional and group:
+        click.echo("Error: Cannot specify both --optional and --group")
+        raise Exit(1)
+
+    result = subprocess.run(
+        [
+            "uv",
+            "remove",
+            *(["--optional", optional] if optional else []),
+            *(["--group", group] if group else []),
+            lib,
+        ],
+        check=False,
+    )
+    if result.returncode != 0:
+        raise Exit(result.returncode)
+
+    if has_pixi():
+        # NOTE: pixi doesn't support --optional, so we need to use --feature instead
+        if optional:
+            feature_name = "optional"
+        elif group:
+            feature_name = group
+        else:
+            feature_name = None
+        result = subprocess.run(
+            [
+                "pixi",
+                "remove",
+                "--pypi",
+                *(["--feature", feature_name] if feature_name else []),
+                lib,
+            ],
+            check=False,
+        )
+        if result.returncode != 0:
+            raise Exit(result.returncode)