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

afterpython/builders/jupyter_notebook.py

@@ -0,0 +1,293 @@
+import json
+import os
+from pathlib import Path
+
+import click
+
+import afterpython as ap
+from afterpython.const import CONTENT_TYPES
+from afterpython.tools.pyproject import read_metadata
+
+
+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 _read_notebook(notebook_path: Path, content_path: Path) -> dict | None:
+    """Read and validate a Jupyter notebook.
+
+    Returns:
+        Notebook dict if valid, None if invalid or error occurred
+    """
+    try:
+        with open(notebook_path) as f:
+            notebook = json.load(f)
+    except json.JSONDecodeError:
+        click.echo(f"✗ Skipping {content_path} - invalid or empty JSON")
+        return None
+    except Exception as e:
+        click.echo(f"✗ Error reading {content_path}: {e}")
+        return None
+
+    # Validate notebook structure
+    if "cells" not in notebook:
+        click.echo(f"✗ Skipping {content_path} - not a valid Jupyter notebook")
+        return None
+
+    return notebook
+
+
+def _write_notebook(notebook: dict, notebook_path: Path):
+    """Write a notebook dict to file."""
+    with open(notebook_path, "w") as f:
+        json.dump(notebook, f, indent=1)
+
+
+def _has_frontmatter(notebook: dict) -> bool:
+    """Check if a notebook has frontmatter in the first cell."""
+    if not notebook["cells"]:
+        return False
+
+    first_cell = notebook["cells"][0]
+    return (
+        first_cell.get("cell_type") == "markdown"
+        and first_cell.get("source")
+        and isinstance(first_cell["source"], list)
+        and len(first_cell["source"]) > 0
+        and first_cell["source"][0].strip().startswith("---")
+    )
+
+
+def _read_frontmatter(notebook: dict) -> str | None:
+    """Read frontmatter content from a notebook.
+
+    Returns:
+        Frontmatter content as a string if it exists, None otherwise
+    """
+    if not _has_frontmatter(notebook):
+        return None
+
+    first_cell = notebook["cells"][0]
+    return "".join(first_cell["source"])
+
+
+def _write_frontmatter(notebook: dict, content: str):
+    """Write frontmatter content to a notebook cell.
+
+    Low-level function that handles cell manipulation.
+    If frontmatter cell exists, updates it. If not, creates a new one.
+
+    Args:
+        notebook: The notebook dict to modify
+        content: The complete frontmatter content as a string (should include --- delimiters)
+    """
+    # Convert content string to list of lines
+    source_lines = [
+        line if line.endswith("\n") else line + "\n" for line in content.split("\n")
+    ]
+    # Remove the last empty line if the content ends with \n
+    if source_lines and source_lines[-1] == "\n":
+        source_lines.pop()
+
+    if _has_frontmatter(notebook):
+        # Update existing frontmatter cell
+        notebook["cells"][0]["source"] = source_lines
+    else:
+        # Create new frontmatter cell
+        frontmatter_cell = {
+            "cell_type": "markdown",
+            "id": "frontmatter-cell",
+            "metadata": {},
+            "source": source_lines,
+        }
+        notebook["cells"].insert(0, frontmatter_cell)
+
+
+def _add_fields_to_frontmatter(notebook: dict, fields: dict[str, str]):
+    """Add or update fields in frontmatter.
+
+    High-level function that handles frontmatter field manipulation.
+    If frontmatter exists, adds new fields to it. If not, creates new frontmatter with those fields.
+
+    Args:
+        notebook: The notebook dict to modify
+        fields: A dict of fields to add/update (e.g., {"thumbnail": "null"})
+    """
+    existing_content = _read_frontmatter(notebook)
+
+    if existing_content:
+        # Parse existing frontmatter and add new fields
+        lines = existing_content.split("\n")
+
+        # Find the closing --- of frontmatter
+        closing_index = -1
+        for i in range(1, len(lines)):
+            if lines[i].strip().startswith("---"):
+                closing_index = i
+                break
+
+        if closing_index > 0:
+            # Insert new fields before the closing ---
+            for key, value in fields.items():
+                # Check if field already exists
+                if not any(line.strip().startswith(f"{key}:") for line in lines):
+                    lines.insert(closing_index, f"{key}: {value}")
+                    closing_index += 1  # Adjust index for next insertion
+
+            new_content = "\n".join(lines)
+            _write_frontmatter(notebook, new_content)
+    else:
+        # Create new frontmatter with the provided fields
+        field_lines = [f"{key}: {value}" for key, value in fields.items()]
+        new_content = "---\n" + "\n".join(field_lines) + "\n---"
+        _write_frontmatter(notebook, new_content)
+
+
+def _add_thumbnail_to_notebook(
+    notebook: dict, thumbnail: str, content_path: Path
+) -> bool:
+    """Add thumbnail field to a single notebook's frontmatter.
+
+    Args:
+        notebook: The notebook dict to modify
+        thumbnail: The thumbnail value to add
+        content_path: Path for logging purposes
+
+    Returns:
+        True if thumbnail was added, False if it already exists
+    """
+    # Read frontmatter content
+    frontmatter_content = _read_frontmatter(notebook)
+
+    # Check if thumbnail is already set in frontmatter
+    if frontmatter_content and "thumbnail:" in frontmatter_content:
+        return False
+
+    # Add thumbnail using the fields parameter
+    _add_fields_to_frontmatter(notebook, fields={"thumbnail": thumbnail})
+
+    if frontmatter_content:
+        click.echo(
+            f"  ↳ Added 'thumbnail: {thumbnail}' to frontmatter in: {content_path}"
+        )
+    else:
+        click.echo(
+            f"  ↳ Created frontmatter with 'thumbnail: {thumbnail}' in: {content_path}"
+        )
+
+    return True
+
+
+def _add_molab_badge_to_notebook(notebook: dict, github_url: str, content_path: Path):
+    """Add a molab badge markdown cell to a single notebook.
+
+    Args:
+        notebook: The notebook dict to modify
+        github_url: The GitHub repository URL
+        content_path: Path relative to afterpython/ for generating the molab URL
+
+    Note:
+        The jupyter notebook needs 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.
+    """
+    molab_url = _create_molab_url(github_url, content_path)
+    badge_md = f"[![Open in molab]({_get_molab_badge()})]({molab_url})"
+
+    # 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],
+    }
+
+    # Determine insertion position (after frontmatter if it exists)
+    insert_position = 1 if _has_frontmatter(notebook) else 0
+
+    # Check if badge already exists at the expected position
+    if (
+        len(notebook["cells"]) > insert_position
+        and notebook["cells"][insert_position].get("id") == "molab-badge-cell"
+    ):
+        # Update existing badge
+        notebook["cells"][insert_position] = badge_cell
+        click.echo(f"✓ Updated molab badge in: {content_path}")
+    else:
+        # Insert at the correct position
+        notebook["cells"].insert(insert_position, badge_cell)
+        click.echo(f"✓ Added molab badge to: {content_path}")
+
+
+def build_jupyter_notebooks():
+    """Build Jupyter notebooks for all content types"""
+    from afterpython.tools._afterpython import get_default_thumbnail
+
+    # Check if molab badge feature is enabled
+    add_molab_badge = os.getenv("AP_MOLAB_BADGE", "1") == "1"
+
+    # Get GitHub URL once if needed for molab badges
+    github_url = None
+    if add_molab_badge:
+        metadata = read_metadata()
+        if "repository" in metadata.urls:
+            github_url = metadata.urls["repository"]
+        else:
+            click.echo(
+                "⚠ Repository URL not found in [project.urls] in pyproject.toml, skipping molab badge"
+            )
+            add_molab_badge = False
+
+    for content_type in CONTENT_TYPES:
+        click.echo(f"Building Jupyter notebooks for {content_type}/...")
+
+        path = ap.paths.afterpython_path / content_type.lower()
+
+        # Iterate over all .ipynb files once
+        for notebook_path in path.rglob("*.ipynb"):
+            # Skip files in _build directory
+            if "_build" in notebook_path.parts:
+                continue
+
+            # Get path relative to afterpython/
+            content_path = notebook_path.relative_to(ap.paths.afterpython_path)
+
+            # Get default thumbnail for this content type
+            # explicitly set to "null" if no default thumbnail is set to avoid using the first image (very likely to be "open in molab" badge image) as thumbnail
+            default_thumbnail = (
+                get_default_thumbnail(content_type, notebook_path) or "null"
+            )
+
+            # Read the notebook
+            notebook = _read_notebook(notebook_path, content_path)
+            if notebook is None:
+                continue
+
+            # Track if notebook was modified
+            modified = False
+
+            # Add molab badge if enabled
+            if add_molab_badge and github_url:
+                _add_molab_badge_to_notebook(notebook, github_url, content_path)
+                modified = True
+
+            # Add thumbnail to frontmatter
+            if content_type != "doc" and _add_thumbnail_to_notebook(
+                notebook, default_thumbnail, content_path
+            ):
+                modified = True
+
+            # Write back if modified
+            if modified:
+                _write_notebook(notebook, notebook_path)

afterpython/builders/markdown.py

@@ -0,0 +1,271 @@
+from pathlib import Path
+
+import click
+
+import afterpython as ap
+from afterpython.const import CONTENT_TYPES
+
+
+def _read_markdown(markdown_path: Path, content_path: Path) -> str | None:
+    """Read and validate a markdown file.
+
+    Args:
+        markdown_path: Absolute path to the markdown file
+        content_path: Path relative to afterpython/ for logging
+
+    Returns:
+        Markdown content as a string if valid, None if invalid or error occurred
+    """
+    try:
+        with open(markdown_path, encoding="utf-8") as f:
+            content = f.read()
+        return content
+    except FileNotFoundError:
+        click.echo(f"✗ Skipping {content_path} - file not found")
+        return None
+    except Exception as e:
+        click.echo(f"✗ Error reading {content_path}: {e}")
+        return None
+
+
+def _write_markdown(content: str, markdown_path: Path):
+    """Write markdown content to file.
+
+    Args:
+        content: The markdown content to write
+        markdown_path: Absolute path to the markdown file
+    """
+    with open(markdown_path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+
+def _has_frontmatter(content: str) -> bool:
+    """Check if markdown content has frontmatter.
+
+    Args:
+        content: The markdown file content as a string
+
+    Returns:
+        True if the content starts with ---, False otherwise
+    """
+    return content.strip().startswith("---")
+
+
+def _read_frontmatter(content: str) -> str | None:
+    """Read frontmatter content from markdown.
+
+    Args:
+        content: The markdown file content as a string
+
+    Returns:
+        Frontmatter content as a string (including --- delimiters) if it exists, None otherwise
+    """
+    if not _has_frontmatter(content):
+        return None
+
+    lines = content.split("\n")
+
+    # Find the closing --- of frontmatter
+    closing_index = -1
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            closing_index = i
+            break
+
+    if closing_index == -1:
+        return None
+
+    # Return frontmatter including both --- delimiters
+    return "\n".join(lines[: closing_index + 1])
+
+
+def _write_frontmatter(content: str, frontmatter: str) -> str:
+    """Write frontmatter content to markdown.
+
+    Low-level function that handles frontmatter replacement.
+    If frontmatter exists in content, replaces it. If not, prepends it.
+
+    Args:
+        content: The markdown file content as a string
+        frontmatter: The complete frontmatter content as a string (should include --- delimiters)
+
+    Returns:
+        The updated markdown content with the new frontmatter
+    """
+    if _has_frontmatter(content):
+        # Replace existing frontmatter
+        lines = content.split("\n")
+
+        # Find the closing --- of existing frontmatter
+        closing_index = -1
+        for i in range(1, len(lines)):
+            if lines[i].strip() == "---":
+                closing_index = i
+                break
+
+        if closing_index > -1:
+            # Remove old frontmatter and prepend new one
+            body = "\n".join(lines[closing_index + 1 :])
+            return frontmatter + "\n" + body
+        else:
+            # Malformed frontmatter, just prepend new frontmatter
+            return frontmatter + "\n" + content
+    else:
+        # No frontmatter exists, prepend it
+        return frontmatter + "\n" + content
+
+
+def _ensure_blank_line_after_frontmatter(content: str) -> str:
+    """Ensure there's a blank line between frontmatter and content.
+
+    Args:
+        content: The markdown content
+
+    Returns:
+        Content with blank line after frontmatter if frontmatter exists
+    """
+    if not _has_frontmatter(content):
+        return content
+
+    lines = content.split("\n")
+
+    # Find the closing --- of frontmatter
+    closing_index = -1
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            closing_index = i
+            break
+
+    if closing_index == -1:
+        return content
+
+    # Check if there's already a blank line after the closing ---, and if the next line is not empty, insert a blank line
+    if closing_index + 1 < len(lines) and lines[closing_index + 1].strip() != "":
+        lines.insert(closing_index + 1, "")
+
+    return "\n".join(lines)
+
+
+def _add_fields_to_frontmatter(content: str, fields: dict[str, str]) -> str:
+    """Add or update fields in frontmatter.
+
+    High-level function that handles frontmatter field manipulation.
+    If frontmatter exists, adds new fields to it. If not, creates new frontmatter with those fields.
+
+    Args:
+        content: The markdown file content as a string
+        fields: A dict of fields to add/update (e.g., {"thumbnail": "null"})
+
+    Returns:
+        The updated markdown content with the new fields in frontmatter
+    """
+    existing_frontmatter = _read_frontmatter(content)
+
+    if existing_frontmatter:
+        # Parse existing frontmatter and add new fields
+        lines = existing_frontmatter.split("\n")
+
+        # Find the closing --- of frontmatter
+        closing_index = -1
+        for i in range(1, len(lines)):
+            if lines[i].strip() == "---":
+                closing_index = i
+                break
+
+        if closing_index > 0:
+            # Insert new fields before the closing ---
+            for key, value in fields.items():
+                # Check if field already exists
+                if not any(line.strip().startswith(f"{key}:") for line in lines):
+                    lines.insert(closing_index, f"{key}: {value}")
+                    closing_index += 1  # Adjust index for next insertion
+
+            new_frontmatter = "\n".join(lines)
+            return _write_frontmatter(content, new_frontmatter)
+    else:
+        # Create new frontmatter with the provided fields
+        field_lines = [f"{key}: {value}" for key, value in fields.items()]
+        new_frontmatter = "---\n" + "\n".join(field_lines) + "\n---"
+        return _write_frontmatter(content, new_frontmatter)
+
+    return content
+
+
+def _add_thumbnail_to_markdown(
+    content: str, thumbnail: str, content_path: Path
+) -> tuple[str, bool]:
+    """Add thumbnail field to a markdown file's frontmatter.
+
+    Args:
+        content: The markdown content
+        thumbnail: The thumbnail value to add
+        content_path: Path for logging purposes
+
+    Returns:
+        Tuple of (modified_content, was_modified)
+    """
+    # Check if thumbnail is already set in frontmatter
+    frontmatter_content = _read_frontmatter(content)
+    if frontmatter_content and "thumbnail:" in frontmatter_content:
+        return content, False
+
+    # Add thumbnail using the fields parameter
+    modified_content = _add_fields_to_frontmatter(
+        content, fields={"thumbnail": thumbnail}
+    )
+
+    if frontmatter_content:
+        click.echo(
+            f"  ↳ Added 'thumbnail: {thumbnail}' to frontmatter in: {content_path}"
+        )
+    else:
+        click.echo(
+            f"  ↳ Created frontmatter with 'thumbnail: {thumbnail}' in: {content_path}"
+        )
+
+    return modified_content, True
+
+
+def build_markdown():
+    """Build markdown files for all content types"""
+    from afterpython.tools._afterpython import get_default_thumbnail
+
+    for content_type in CONTENT_TYPES:
+        # Skip doc content type - docs don't need default thumbnails
+        if content_type == "doc":
+            continue
+
+        click.echo(f"Building markdown files for {content_type}/...")
+
+        path = ap.paths.afterpython_path / content_type.lower()
+
+        # Iterate over all .md files
+        for markdown_path in path.rglob("*.md"):
+            # Skip files in _build directory
+            if "_build" in markdown_path.parts:
+                continue
+
+            # Get path relative to afterpython/
+            content_path = markdown_path.relative_to(ap.paths.afterpython_path)
+
+            # Get default thumbnail for this content type
+            default_thumbnail = get_default_thumbnail(content_type, markdown_path)
+
+            # Read the markdown file
+            content = _read_markdown(markdown_path, content_path)
+            if content is None:
+                continue
+
+            # Ensure blank line after frontmatter (fixes existing files)
+            original_content = content
+            content = _ensure_blank_line_after_frontmatter(content)
+            blank_line_added = content != original_content
+
+            # Add thumbnail to frontmatter
+            modified_content, was_modified = _add_thumbnail_to_markdown(
+                content, default_thumbnail, content_path
+            )
+
+            # Write back if modified (either blank line or thumbnail)
+            if was_modified or blank_line_added:
+                _write_markdown(modified_content, markdown_path)

afterpython/builders/metadata.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pyproject_metadata import StandardMetadata
+
+import json
+
+import click
+
+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)
+
+    click.echo("Completed path conversion in metadata.json")
+
+
+def build_metadata():
+    """Build metadata.json using pyproject.toml"""
+    from afterpython.tools.pyproject import read_metadata
+
+    click.echo("Building metadata.json...")
+
+    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/cli/__init__.py

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

afterpython/cli/commands/add.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="Add to an optional dependency group (pixi: mapped to 'optional' feature)",
+)
+@click.option(
+    "--group",
+    type=str,
+    default=None,
+    required=False,
+    help="Add to a dependency group (pixi: mapped to same-named feature)",
+)
+@click.argument("lib", type=str, required=True)
+def add(optional: str | None, group: str | None, lib: str):
+    """Add a new dependency to 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",
+            "add",
+            *(["--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",
+                "add",
+                "--pypi",
+                *(["--feature", feature_name] if feature_name else []),
+                lib,
+            ],
+            check=False,
+        )
+        if result.returncode != 0:
+            raise Exit(result.returncode)