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

afterpython/.pre-commit-config.yaml

@@ -0,0 +1,48 @@
+default_install_hook_types:
+- pre-commit
+- commit-msg
+- pre-push
+exclude: ^afterpython/_website/
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v6.0.0
+  hooks:
+  - id: trailing-whitespace
+    stages:
+    - pre-commit
+  - id: end-of-file-fixer
+    stages:
+    - pre-commit
+  - id: check-yaml
+    stages:
+    - pre-commit
+  - id: check-toml
+    stages:
+    - pre-commit
+  - id: check-added-large-files
+    stages:
+    - pre-commit
+- 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
+- repo: https://github.com/commitizen-tools/commitizen
+  rev: v4.10.0
+  hooks:
+  - id: commitizen
+    stages:
+    - commit-msg
+  - id: commitizen-branch
+    stages:
+    - pre-push

afterpython/__init__.py

@@ -0,0 +1,13 @@
+# import builtins
+# from pprint import pprint
+from importlib.metadata import version
+
+from afterpython._paths import Paths
+
+# make pprint available in the global namespace
+# builtins.pprint = pprint
+
+paths = Paths()
+
+__version__ = version("afterpython")
+__all__ = ("__version__", "paths")

afterpython/_io/toml.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tomlkit.toml_document import TOMLDocument
+    from pathlib import Path
+
+import tomlkit
+
+
+# VIBE-CODED
+def _from_tomlkit(value):
+    """Recursively convert tomlkit objects to plain Python data structures.
+
+    This ensures compatibility with other libraries (like ruamel.yaml):
+    - tomlkit containers → plain Python containers
+    - tomlkit primitives → plain Python primitives
+    """
+    from tomlkit.items import Array, InlineTable, Table, AoT
+
+    if value is None:
+        return None
+
+    # Check containers first (these are the problematic ones)
+    if isinstance(value, (Table, InlineTable)):
+        # tomlkit dict-like → plain dict
+        return {k: _from_tomlkit(v) for k, v in value.items()}
+    elif isinstance(value, (Array, AoT)):
+        # tomlkit array → plain list
+        return [_from_tomlkit(item) for item in value]
+    elif isinstance(value, dict):
+        # Already a dict, but recurse to handle nested tomlkit objects
+        return {k: _from_tomlkit(v) for k, v in value.items()}
+    elif isinstance(value, list):
+        # Already a list, but recurse to handle nested tomlkit objects
+        return [_from_tomlkit(item) for item in value]
+
+    # Primitives - tomlkit primitives inherit from Python types
+    # Just convert explicitly to be safe
+    elif isinstance(value, bool):  # MUST check bool before int!
+        return bool(value)
+    elif isinstance(value, int):
+        return int(value)
+    elif isinstance(value, float):
+        return float(value)
+    elif isinstance(value, str):
+        return str(value)
+    else:
+        # datetime, date, time, or already plain Python type
+        return value
+
+
+# VIBE-CODED
+def _to_tomlkit(value):
+    """Recursively convert Python data structures to tomlkit objects.
+
+    This ensures proper TOML formatting:
+    - List of dicts → array of inline tables: [{key = val}]
+    - Nested dicts → nested tables with proper structure
+    """
+    from tomlkit import inline_table, array
+
+    if value is None:
+        return None
+
+    if isinstance(value, dict):
+        # Plain dict → recursively convert values
+        return {k: _to_tomlkit(v) for k, v in value.items()}
+    elif isinstance(value, list):
+        if not value:
+            # Empty list → empty tomlkit array
+            return array()
+
+        # Check if ALL items are dicts (should be inline tables)
+        if all(isinstance(item, dict) for item in value):
+            arr = array()
+            for item in value:
+                tbl = inline_table()
+                # Recursively convert the dict values
+                tbl.update({k: _to_tomlkit(v) for k, v in item.items()})
+                arr.append(tbl)
+            return arr
+        else:
+            # Mixed or non-dict items → regular array
+            arr = array()
+            for item in value:
+                arr.append(_to_tomlkit(item))
+            return arr
+    else:
+        # Primitives (str, int, float, bool, datetime, etc.)
+        # tomlkit handles these natively
+        return value
+
+
+def read_toml(file_path: Path) -> TOMLDocument:
+    with open(file_path, "rb") as f:
+        data: TOMLDocument = tomlkit.parse(f.read())
+    return data
+
+
+def write_toml(file_path: Path, data: TOMLDocument | dict):
+    with open(file_path, "w") as f:
+        f.write(tomlkit.dumps(data))

afterpython/_io/yaml.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap
+
+
+def _get_yaml() -> YAML:
+    """Get configured YAML instance that preserves order, comments, and formatting"""
+    yaml = YAML()
+    yaml.preserve_quotes = True
+    yaml.default_flow_style = False
+    yaml.width = 4096  # Prevent line wrapping
+    return yaml
+
+
+def read_yaml(file_path: Path) -> CommentedMap:
+    yaml = _get_yaml()
+    with open(file_path) as f:
+        return yaml.load(f)
+
+
+def write_yaml(file_path: Path, data: dict):
+    """Write YAML data"""
+    yaml = _get_yaml()
+    with open(file_path, "w") as f:
+        yaml.dump(data, f)

afterpython/_paths.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Paths:
+    package_path: Path = field(init=False)
+    templates_path: Path = field(init=False)
+    user_path: Path = field(init=False)
+    pyproject_path: Path = field(init=False)
+    afterpython_path: Path = field(init=False)
+    website_path: Path = field(init=False)
+    build_path: Path = field(init=False)
+    static_path: Path = field(init=False)
+
+    def __post_init__(self):
+        # package path is the path to the afterpython package in user's site-packages
+        self.package_path = Path(__file__).resolve().parents[0]
+        self.templates_path = self.package_path / "templates"
+        self.user_path = self._find_project_root()
+        self.pyproject_path = self.user_path / "pyproject.toml"
+        self.afterpython_path = self.user_path / "afterpython"
+        self.website_path = self.afterpython_path / "_website"
+        self.build_path = self.afterpython_path / "_build"
+        self.static_path = self.afterpython_path / "static"
+
+    def _find_project_root(self) -> Path:
+        """Find the project root by looking for pyproject.toml in current or parent directories."""
+        current = Path.cwd()
+
+        # Check current directory and all parents
+        for path in [current, *current.parents]:
+            if (path / "pyproject.toml").exists():
+                return path
+
+        # If no pyproject.toml found, raise an error like uv does
+        raise FileNotFoundError(
+            "No pyproject.toml found in current directory or any parent directory"
+        )

afterpython/_typing.py

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

afterpython/builders/__init__.py

@@ -0,0 +1,8 @@
+from afterpython.builders.metadata import build_metadata
+from afterpython.builders.molab import add_molab_badge_to_jupyter_notebooks
+
+
+__all__ = (
+    "add_molab_badge_to_jupyter_notebooks",
+    "build_metadata",
+)

afterpython/builders/metadata.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pyproject_metadata import StandardMetadata
+
+import json
+
+import afterpython as ap
+
+
+build_path = ap.paths.build_path
+
+
+def convert_paths():
+    """
+    Convert paths in "description" field (README.md) in metadata.json to use the new paths in the build output.
+    e.g. convert ./afterpython/static/image.png to static/image.png
+    """
+    # Read metadata.json
+    with open(build_path / "metadata.json") as f:
+        metadata = json.load(f)
+        markdown_text = metadata["description"]
+
+    # Replace with the correct paths
+    updated_markdown = markdown_text.replace("./afterpython/static/", "/")
+
+    # Write back to metadata.json
+    metadata["description"] = updated_markdown
+    with open(build_path / "metadata.json", "w") as f:
+        json.dump(metadata, f, indent=2)
+
+    print("Completed path conversion in metadata.json")
+
+
+def build_metadata():
+    """Build metadata.json using pyproject.toml"""
+    from afterpython.tools.pyproject import read_metadata
+
+    metadata: StandardMetadata = read_metadata()
+
+    # Write to metadata.json
+    with open(build_path / "metadata.json", "w") as f:
+        json.dump(metadata.as_json(), f, indent=2)
+
+    convert_paths()

afterpython/builders/molab.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from afterpython._typing import tContentType
+
+import json
+from pathlib import Path
+
+from pyproject_metadata import StandardMetadata
+
+import afterpython as ap
+from afterpython.tools.pyproject import read_metadata
+from afterpython.const import CONTENT_TYPES
+
+
+def _get_molab_badge() -> str:
+    return "https://marimo.io/molab-shield.svg"
+
+
+def _create_molab_url(github_url: str, content_path: Path):
+    """Create a molab URL for a given content type and notebook path.
+    Args:
+        github_url: str, e.g. "https://github.com/AfterPythonOrg/afterpython"
+        content_path: str, e.g. "tutorial/test.ipynb"
+    """
+    github_url = github_url.replace("https://github.com/", "github/")
+    return f"https://molab.marimo.io/{github_url}/blob/main/afterpython/{content_path.as_posix()}"
+
+
+def add_molab_badge_to_jupyter_notebooks(content_type: tContentType):
+    """Add a badge markdown cell to the top of Jupyter notebooks in the given content type directory, e.g. tutorial/, blog/, etc.
+    # NOTE
+    Note that the jupyter notebooks need to exist in the github repository first.
+    If you have renamed a notebook, you need to push the changes to the github repository first for the badge to work.
+    """
+    assert content_type.lower() in CONTENT_TYPES, (
+        f"Invalid content type: {content_type}"
+    )
+    metadata: StandardMetadata = read_metadata()
+
+    if "repository" not in metadata.urls:
+        return "Repository URL not found in [project.urls] in pyproject.toml, cannot add molab badge"
+    else:
+        github_url = metadata.urls["repository"]
+
+    path = ap.paths.afterpython_path / content_type.lower()
+
+    # iterate over all files in the path
+    for notebook_path in path.rglob("*.ipynb"):
+        # Skip files in _build directory
+        if "_build" in notebook_path.parts:
+            continue
+
+        # Get path relative to afterpython/ (includes tutorial/ in the path)
+        content_path = notebook_path.relative_to(ap.paths.afterpython_path)
+        molab_url = _create_molab_url(github_url, content_path)
+        badge_md = f"[![Open in molab]({_get_molab_badge()})]({molab_url})"
+
+        # Read the notebook
+        try:
+            # Read the notebook
+            with open(notebook_path) as f:
+                notebook = json.load(f)
+        except json.JSONDecodeError:
+            print(f"✗ Skipping {content_path} - invalid or empty JSON")
+            continue
+        except Exception as e:
+            print(f"✗ Error reading {content_path}: {e}")
+            continue
+
+        # Validate notebook structure
+        if "cells" not in notebook:
+            print(f"✗ Skipping {content_path} - not a valid Jupyter notebook")
+            continue
+
+        # Create a markdown cell with the badge
+        badge_cell = {
+            "cell_type": "markdown",
+            "id": "molab-badge-cell",  # Unique ID for the badge cell
+            "metadata": {
+                "tags": ["molab", "hide-input"]  # Optional: use MyST tags
+            },
+            "source": [badge_md],
+        }
+
+        # Check if first cell is already a badge cell (avoid duplicates)
+        if notebook["cells"] and notebook["cells"][0].get("id") == "molab-badge-cell":
+            # Update existing badge
+            notebook["cells"][0] = badge_cell
+            print(f"✓ Updated molab badge in: {content_path}")
+        else:
+            # Insert at the beginning
+            notebook["cells"].insert(0, badge_cell)
+            print(f"✓ Added molab badge to: {content_path}")
+
+        # Write back
+        with open(notebook_path, "w") as f:
+            json.dump(notebook, f, indent=1)

afterpython/cli/__init__.py

@@ -0,0 +1,4 @@
+from afterpython.cli.main import afterpython_group
+
+
+__all__ = ["afterpython_group"]

afterpython/cli/commands/build.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+from collections.abc import Callable
+
+if TYPE_CHECKING:
+    from afterpython._typing import NodeEnv
+    from pathlib import Path
+
+import os
+import shutil
+import subprocess
+
+import click
+from click.exceptions import Exit
+
+import afterpython as ap
+from afterpython.utils import find_node_env
+from afterpython.const import CONTENT_TYPES
+from afterpython.builders import (
+    build_metadata,
+    add_molab_badge_to_jupyter_notebooks,
+)
+
+
+def prebuild():
+    def _check_initialized():
+        # Check if 'ap init' has been run
+        afterpython_toml = ap.paths.afterpython_path / "afterpython.toml"
+        if not afterpython_toml.exists():
+            raise click.ClickException(
+                "AfterPython is not initialized!\n"
+                "Run 'ap init' first to set up your project."
+            )
+
+    def _clean_build_directory():
+        print("Cleaning up build directory...")
+        build_path = ap.paths.build_path
+        if build_path.exists():
+            shutil.rmtree(build_path)
+        build_path.mkdir(parents=True, exist_ok=True)
+
+    _check_initialized()
+    _clean_build_directory()
+
+    if os.getenv("AP_MOLAB_BADGE", "0") == "1":
+        for content_type in CONTENT_TYPES:
+            add_molab_badge_to_jupyter_notebooks(content_type)
+
+
+def postbuild():
+    def _move_files(
+        source: Path,
+        destination: Path,
+        is_copy: bool = True,
+        ignore_copy: Callable[[str, list[str]], set[str]] | None = None,
+    ):
+        """
+        Move or copy files from source to destination.
+
+        Args:
+            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
+        """
+        if not source.exists():
+            return
+        if is_copy:
+            shutil.copytree(source, destination, dirs_exist_ok=True, ignore=ignore_copy)
+            print(f"Copied: {source} to {destination}")
+        else:
+            # Remove destination if it exists (move will fail otherwise)
+            if destination.exists():
+                shutil.rmtree(destination)
+            shutil.move(str(source), str(destination))
+            print(f"Moved: {source} to {destination}")
+
+    website_static = ap.paths.website_path / "static"
+    website_static.mkdir(parents=True, exist_ok=True)
+
+    for content_type in CONTENT_TYPES:
+        myst_build = ap.paths.afterpython_path / content_type / "_build"
+        afterpython_content_build = ap.paths.build_path / content_type
+        # Move myst builds from afterpython/{content_type}/_build to afterpython/_build/{content_type}
+        _move_files(myst_build, afterpython_content_build, is_copy=False)
+        # Copy afterpython/_build/{content_type}/html to afterpython/_website/static/{content_type}
+        _move_files(
+            afterpython_content_build / "html",
+            website_static / content_type,
+            is_copy=True,
+        )
+
+    # Copy all files from afterpython/_build to afterpython/_website/static/
+    _move_files(
+        ap.paths.build_path,
+        website_static,
+        is_copy=True,
+        # ignore all content builds e.g. doc/, blog/, only their html/ files will be copied
+        ignore_copy=lambda dir, contents: [
+            name for name in contents if name in CONTENT_TYPES
+        ],
+    )
+
+    # Copy all static files from afterpython/static/ to afterpython/_website/static/
+    _move_files(ap.paths.static_path, website_static, is_copy=True)
+
+
+@click.command(
+    add_help_option=False,  # disable click's --help option so that ap build --help can work
+    context_settings=dict(
+        ignore_unknown_options=True,
+        allow_extra_args=True,
+    ),
+)
+@click.pass_context
+@click.option(
+    "--dev",
+    is_flag=True,
+    hidden=True,  # Internal flag used by `ap dev`, not exposed to users
+    help="Development build - only build metadata for the landing page, skip content and production builds",
+)
+@click.option(
+    "--execute", is_flag=True, help="Execute Jupyter notebooks for all content types"
+)
+def build(ctx, dev: bool, execute: bool):
+    """Build the project website and all contents for production.
+
+    This command builds MyST content (doc/blog/tutorial/example/guide) and the SvelteKit website.
+
+    Any extra arguments are passed to the 'myst build --html' command for each content type.
+    See "myst build --help" for more details.
+
+    Use --execute to execute Jupyter notebooks for all content types.
+    """
+    from afterpython.utils import has_content_for_myst
+    from afterpython.utils import handle_passthrough_help
+
+    # Show both our options and myst's help and exit
+    handle_passthrough_help(
+        ctx,
+        ["myst", "build"],
+        show_underlying=True,
+    )
+
+    paths = ctx.obj["paths"]
+    prebuild()
+
+    click.echo("Building metadata.json...")
+    build_metadata()
+
+    # myst's production build
+    if not dev:
+        node_env: NodeEnv = find_node_env()
+        for content_type in CONTENT_TYPES:
+            content_path = paths.afterpython_path / content_type
+            if not has_content_for_myst(content_path):
+                click.echo(f"Skipping {content_type}/ (no content files found)")
+                continue
+
+            click.echo(f"Building {content_type}/...")
+            # NOTE: needs to set BASE_URL so that the project website can link to the content pages correctly at e.g. localhost:5173/doc
+            # BASE_PATH is set by the GitHub Actions workflow
+            base_path = os.getenv("BASE_PATH", "")
+            base_url = f"{base_path}/{content_type}"
+            build_env = {**node_env, "BASE_URL": base_url}
+            result = subprocess.run(
+                [
+                    "myst",
+                    "build",
+                    "--html",
+                    *(["--execute"] if execute else []),
+                    *ctx.args,
+                ],
+                cwd=content_path,
+                env=build_env,
+                check=False,
+            )
+            if result.returncode != 0:
+                raise Exit(result.returncode)
+
+    postbuild()
+
+    # website's production build
+    if not dev:
+        click.echo("Building project website...")
+        result = subprocess.run(
+            ["pnpm", "build"], cwd=paths.website_path, env=node_env, check=False
+        )
+        if result.returncode != 0:
+            raise Exit(result.returncode)

afterpython/cli/commands/bump.py

@@ -0,0 +1,88 @@
+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(
+    "--pre",
+    is_flag=True,
+    help="bump to pre-release version (e.g., dev3 -> rc0, a1 -> a2)",
+)
+@click.option(
+    "--release", is_flag=True, help="bump to stable release (uses cz bump default)"
+)
+def bump(ctx, release: bool, pre: bool):
+    """Bump project version with granular control.
+
+    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)
+
+    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).
+    """
+    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,
+    )
+
+    if release and pre:
+        raise click.ClickException("Only one of --release or --pre can be specified")
+
+    # bump using cz bump's default behavior
+    if release:
+        subprocess.run(["ap", "cz", "bump", *ctx.args])
+
+        # Skip tag push if this is a dry run
+        if "--dry-run" in ctx.args:
+            return
+
+        # 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")
+
+        tag = f"v{new_version}"
+
+        # 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 "--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])