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

afterpython/tools/_afterpython.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from tomlkit.toml_document import TOMLDocument
+
+    from afterpython._typing import tContentType
+
+import tomlkit
+
+import afterpython as ap
+from afterpython._io.toml import _to_tomlkit, read_toml, write_toml
+
+
+def get_default_thumbnail(
+    content_type: tContentType, file_path: Path | None = None
+) -> str:
+    """Get the default thumbnail value for a content type.
+
+    Reads default thumbnail configuration from afterpython.toml:
+    - Content type specific thumbnail: [website.{content_type}.thumbnail]
+    - Website-wide default thumbnail: [website.thumbnail]
+    - Falls back to empty string if no default is configured
+
+    Args:
+        content_type: The content type (blog, tutorial, etc.)
+        file_path: Optional path to the file needing the thumbnail (for calculating relative path)
+
+    Returns:
+        The thumbnail value to use (e.g., "./static/image.png", "../static/image.png", or "")
+    """
+    from afterpython._io.toml import _from_tomlkit
+    from afterpython.utils import get_relative_static_prefix, normalize_static_path
+
+    afterpython = read_afterpython()
+    try:
+        # website_default_thumbnail = normalize_static_path(
+        #     str(_from_tomlkit(afterpython.get("website", {})).get("thumbnail", ""))
+        # )
+        content_type_default_thumbnail = normalize_static_path(
+            str(
+                _from_tomlkit(afterpython.get("website", {}))
+                .get(content_type, {})
+                .get("thumbnail", "")
+            )
+        )
+    except ValueError as e:
+        print(f"Error in reading afterpython.toml for {content_type=}: {e}")
+        return "null"
+
+    # Determine the static prefix based on file location
+    if file_path is not None:
+        content_type_path = ap.paths.afterpython_path / content_type.lower()
+        static_prefix = get_relative_static_prefix(file_path, content_type_path)
+    else:
+        static_prefix = "./"  # Default fallback
+
+    if content_type_default_thumbnail:
+        return f"{static_prefix}static{content_type_default_thumbnail}"
+    # use "thumbnail" set in afterpython.toml [website]
+    # elif website_default_thumbnail:
+    # Website-wide static is one level up from content_type folder
+    # return f"{static_prefix}../static{website_default_thumbnail}"
+    else:
+        return ""
+
+
+def read_afterpython() -> TOMLDocument:
+    """Read afterpython.toml"""
+    return read_toml(ap.paths.afterpython_path / "afterpython.toml")
+
+
+def update_afterpython(data_update: dict):
+    """Update afterpython.toml
+
+    Args:
+        data_update: dict of data to update
+    """
+    from afterpython.utils import deep_merge
+
+    afterpython_toml_path = ap.paths.afterpython_path / "afterpython.toml"
+
+    # read existing data
+    if not afterpython_toml_path.exists():
+        afterpython_toml_path.touch()
+        existing_data = tomlkit.document()
+    else:
+        with open(afterpython_toml_path, "rb") as f:
+            existing_data = tomlkit.parse(f.read())
+    if existing_data is None:
+        existing_data = tomlkit.document()
+
+    # convert and update existing data
+    # Convert to tomlkit objects to use "array of inline tables" format
+    # e.g. authors = [{name = "..."}] instead of [[docs.authors]] (array of tables)
+    converted_data = _to_tomlkit(data_update)
+
+    existing_data = deep_merge(existing_data, converted_data)
+
+    # write updated data
+    write_toml(afterpython_toml_path, existing_data)
+
+
+def init_afterpython():
+    """Initialize afterpython.toml"""
+    afterpython_toml_path = ap.paths.afterpython_path / "afterpython.toml"
+    if afterpython_toml_path.exists():
+        print(f"afterpython.toml already exists at {afterpython_toml_path}")
+        return
+    afterpython_toml_path.touch()
+    print(f"Created {afterpython_toml_path}")
+    default_data = {
+        "company": {
+            "name": "",
+            "url": "",
+        },
+        "website": {
+            "url": "",
+            "favicon": "favicon.svg",
+            "logo": "logo.svg",
+            "logo_dark": "logo.svg",
+            "thumbnail": "thumbnail.png",
+        },
+    }
+    update_afterpython(default_data)

afterpython/tools/_git.py

@@ -0,0 +1,137 @@
+# VIBE-CODED
+import re
+import subprocess
+
+from git import Repo
+
+from afterpython.utils import has_gh
+
+
+def get_git_user_config() -> dict | None:
+    """Get Git user configuration (name and email)."""
+    try:
+        # Get the repo
+        repo = Repo(search_parent_directories=True)
+
+        # Access git config
+        reader = repo.config_reader()
+
+        # Get user name and email
+        name = reader.get_value("user", "name", default=None)
+        email = reader.get_value("user", "email", default=None)
+
+        if not name or not email:
+            return None
+
+        return {"name": name, "email": email}
+    except Exception:
+        return None
+
+
+def get_github_url() -> str | None:
+    """Get GitHub repository URL from git remote origin."""
+    try:
+        # Get the repo
+        repo = Repo(search_parent_directories=True)
+
+        # Get origin remote URL
+        if "origin" not in repo.remotes:
+            return None
+
+        remote_url = repo.remotes.origin.url
+        # Verify it's a GitHub URL
+        if "github.com" not in remote_url:
+            return None
+
+        # Convert SSH format to HTTPS format
+        # git@github.com:user/repo.git -> https://github.com/user/repo
+        if remote_url.startswith("git@github.com:"):
+            remote_url = remote_url.replace("git@github.com:", "https://github.com/")
+
+        # Remove .git suffix if present
+        remote_url = re.sub(r"\.git$", "", remote_url)
+
+        return remote_url
+
+    except (ImportError, Exception):
+        # GitPython not installed or not in a git repo
+        return None
+
+
+def is_gh_authenticated():
+    """Guide user through GitHub authentication."""
+    if not has_gh():
+        print("""
+╭─────────────────────────────────────────╮
+│  GitHub CLI Required                    │
+╰─────────────────────────────────────────╯
+
+Install it:
+  • macOS:   brew install gh
+  • Linux:   https://github.com/cli/cli/releases
+  • Windows: https://cli.github.com/
+
+        """)
+        return False
+
+    result = subprocess.run(["gh", "auth", "status"], capture_output=True, check=False)
+
+    if result.returncode != 0:
+        print("""
+╭─────────────────────────────────────────╮
+│  GitHub Authentication Required         │
+╰─────────────────────────────────────────╯
+
+Please authenticate with GitHub:
+
+    gh auth login
+
+        """)
+        return False
+
+    return True
+
+
+def get_github_username() -> str | None:
+    """Get authenticated username via gh CLI."""
+    if not has_gh():
+        return None
+
+    result = subprocess.run(
+        ["gh", "api", "user", "--jq", ".login"],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout.strip()
+
+
+def get_current_user_id() -> int | None:
+    """
+    Get the GitHub user ID of the currently authenticated user.
+
+    Returns:
+        User ID or None if error
+    """
+    if not is_gh_authenticated():
+        return None
+
+    result = subprocess.run(
+        ["gh", "api", "user", "--jq", ".id"],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        print(f"Error fetching user ID: {result.stderr}")
+        return None
+
+    try:
+        return int(result.stdout.strip())
+    except ValueError:
+        print("Error: Failed to parse user ID")
+        return None
+
+
+# TODO: use gh's token for pygithub to get repo issues
+# def get_repo_issues(owner: str, repo: str) -> list[dict]:

afterpython/tools/branch_rules.py

@@ -0,0 +1,106 @@
+"""
+Branch protection rules for AfterPython projects.
+Uses gh CLI to create GitHub rulesets.
+"""
+
+import json
+import subprocess
+from copy import deepcopy
+
+from afterpython.tools._git import is_gh_authenticated
+
+DEFAULT_RULESET = {
+    "name": "afterpython-default",  # The ruleset identifier in GitHub
+    "target": "branch",  # This ruleset applies to branches (not tags)
+    "enforcement": "active",  # Rules are enforced (vs "disabled" or "evaluate")
+    "conditions": {  # Which branches this ruleset applies to
+        "ref_name": {
+            "include": ["refs/heads/main"],  # Only protect the 'main' branch
+            "exclude": [],  # No exclusions
+        }
+    },
+    "bypass_actors": [
+        {
+            "actor_id": 5,  # Repository admin role
+            "actor_type": "RepositoryRole",
+            "bypass_mode": "always",
+        }
+    ],
+    "rules": [  # Array of protection rules
+        # Rule 1: No Force Pushes
+        {"type": "non_fast_forward"},  # Prevents git push --force
+        # Rule 2: No Branch Deletion
+        {"type": "deletion"},  # Prevents branch from being deleted
+        # Rule 3: CI Status Checks
+        {
+            "type": "required_status_checks",
+            "parameters": {
+                "required_status_checks": [
+                    {"context": "lint"},
+                    {"context": "test"},
+                    {"context": "build"},
+                ],
+                # The PR branch must be up to date with the base branch (main) before merging
+                "strict_required_status_checks_policy": True,
+            },
+        },
+    ],
+}
+
+
+def list_rulesets() -> list[dict] | None:
+    """
+    List existing rulesets for the current repository.
+
+    Returns:
+        List of rulesets or None if error
+    """
+    if not is_gh_authenticated():
+        return None
+
+    result = subprocess.run(
+        ["gh", "api", "repos/{owner}/{repo}/rulesets"],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        print(f"Error listing rulesets: {result.stderr}")
+        return None
+
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError:
+        print("Error: Failed to parse rulesets JSON")
+        return None
+
+
+def create_default_branch_rules(branch: str = "main") -> bool:
+    if not is_gh_authenticated():
+        return False
+
+    # Check if ruleset already exists
+    existing_rulesets = list_rulesets()
+    if existing_rulesets:
+        print(f"Ruleset '{DEFAULT_RULESET['name']}' already exists.")
+        return False
+
+    # Build payload
+    payload = deepcopy(DEFAULT_RULESET)
+    if branch != "main":
+        payload["conditions"]["ref_name"]["include"] = [f"refs/heads/{branch}"]
+
+    # Create ruleset
+    result = subprocess.run(
+        ["gh", "api", "-X", "POST", "repos/{owner}/{repo}/rulesets", "--input", "-"],
+        input=json.dumps(payload),
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        print(f"Error creating ruleset: {result.stderr}")
+        return False
+
+    print(f"✓ Created branch ruleset '{DEFAULT_RULESET['name']}' for {branch=}")
+    return True

afterpython/tools/commitizen.py

@@ -0,0 +1,13 @@
+import shutil
+
+import afterpython as ap
+
+
+def init_commitizen():
+    commitizen_toml_path = ap.paths.afterpython_path / "cz.toml"
+    if commitizen_toml_path.exists():
+        print(f"Commitizen configuration file {commitizen_toml_path} already exists")
+        return
+    cz_template_path = ap.paths.templates_path / "cz-template.toml"
+    shutil.copy(cz_template_path, commitizen_toml_path)
+    print(f"Created {commitizen_toml_path}")

afterpython/tools/github_actions.py

@@ -0,0 +1,48 @@
+import shutil
+from pathlib import Path
+
+import click
+
+import afterpython as ap
+
+
+def _copy_github_template(template_name: str, target_path: Path):
+    """Helper to copy GitHub-related templates"""
+    if target_path.exists():
+        click.echo(f"{target_path} already exists")
+        return
+
+    # Create parent directory if it doesn't exist
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Copy template from package
+    template_path = ap.paths.templates_path / template_name
+    if not template_path.exists():
+        raise FileNotFoundError(
+            f"Template file not found: {template_path}\n"
+            "This might indicate a corrupted installation. Please reinstall afterpython."
+        )
+
+    shutil.copy(template_path, target_path)
+    print(f"Created {target_path}")
+
+
+def create_workflow(workflow_name: str):
+    """Create a GitHub Actions workflow from template"""
+    if ".yml" in workflow_name:
+        workflow_name = workflow_name.replace(".yml", "")
+
+    user_path = ap.paths.user_path
+    workflow_path = user_path / ".github" / "workflows" / f"{workflow_name}.yml"
+    template_name = f"{workflow_name}-workflow-template.yml"
+
+    _copy_github_template(template_name, workflow_path)
+
+
+def create_dependabot():
+    """Create Dependabot configuration for GitHub Actions updates"""
+    user_path = ap.paths.user_path
+    dependabot_path = user_path / ".github" / "dependabot.yml"
+    template_name = "dependabot-template.yml"
+
+    _copy_github_template(template_name, dependabot_path)

afterpython/tools/myst.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from afterpython._typing import NodeEnv, tContentType
+
+import subprocess
+
+import afterpython as ap
+from afterpython._io.yaml import read_yaml, write_yaml
+from afterpython.utils import deep_merge
+
+
+def update_authors_yml(data_update: dict):
+    """Update authors.yml while preserving order and formatting"""
+    file_path = ap.paths.afterpython_path / "authors.yml"
+
+    if not file_path.exists():
+        write_yaml(file_path, data_update)
+        return
+
+    existing_data = read_yaml(file_path) or {}
+
+    # merge authors, keep the author with more fields (e.g. github, x, etc.) to avoid duplication
+    merged_authors = {}
+    for author in (
+        existing_data["project"]["contributors"]
+        + data_update["project"]["contributors"]
+    ):
+        author_id = author["id"]
+        if author_id not in merged_authors:
+            merged_authors[author_id] = author
+        else:
+            # keep the author with more fields (e.g. github, x, etc.)
+            if len(author.keys()) > len(merged_authors[author_id].keys()):
+                merged_authors[author_id] = author
+    existing_data["project"]["contributors"] = list(merged_authors.values())
+
+    # set comments for project section for convenience
+    if "project" in existing_data and not existing_data["project"].ca.items.get(
+        "contributors"
+    ):
+        existing_data["project"].yaml_set_comment_before_after_key(
+            "contributors",
+            before="See more at: https://mystmd.org/guide/frontmatter#frontmatter-authors",
+        )
+    write_yaml(file_path, existing_data)
+
+
+def update_myst_yml(data_update: dict, path: Path, add_comments: bool = False):
+    """Update myst.yml while preserving order and formatting
+
+    Args:
+        data_update: dict of data to update
+        path: path to the myst.yml file, e.g. doc/, blog/, tutorial/, example/, guide/
+    """
+
+    file_path = path / "myst.yml"
+
+    if not file_path.exists():
+        raise FileNotFoundError(
+            f"myst.yml not found at {file_path}, did you forget to run `ap init` or `myst init`?"
+        )
+
+    existing_data = read_yaml(file_path) or {}
+    existing_data = deep_merge(existing_data, data_update, extend_lists=False)
+
+    # NOTE: this checking existing_data["key1"].ca.items.get("key2") is buggy
+    # only add_comments=True during init to avoid adding duplicate comments
+    if add_comments:
+        # set comments for project section for convenience
+        if "project" in existing_data:
+            if not existing_data["project"].ca.items.get("id"):
+                existing_data["project"].yaml_set_comment_before_after_key(
+                    "id",
+                    before="See how to create Table of Contents at: https://mystmd.org/guide/table-of-contents",
+                )
+            if not existing_data["project"].ca.items.get("authors"):
+                existing_data["project"].yaml_set_comment_before_after_key(
+                    "authors",
+                    before="See more authors' fields at: https://mystmd.org/guide/frontmatter#frontmatter-authors",
+                )
+            if not existing_data["project"].ca.items.get("venue"):
+                existing_data["project"].yaml_set_comment_before_after_key(
+                    "venue",
+                    before="See more venue's fields at: https://mystmd.org/guide/frontmatter#venue",
+                )
+        if "site" in existing_data:
+            if not existing_data["site"].ca.items.get("options"):
+                existing_data["site"].yaml_set_comment_before_after_key(
+                    "options",
+                    before="See options at: https://mystmd.org/guide/website-templates#site-options",
+                )
+            if not existing_data["site"].ca.items.get("actions"):
+                existing_data["site"].yaml_set_comment_before_after_key(
+                    "actions",
+                    before="See web layout at: https://mystmd.org/guide/website-navigation",
+                )
+
+    write_yaml(file_path, existing_data)
+
+
+def _write_index_file(content_type: tContentType):
+    """Create a placeholder index.md file for MyST to prevent first file from becoming index.
+
+    MyST treats the first file in TOC as index. This placeholder ensures all actual
+    content files get proper slugs. The generated index.html is deleted post-build
+    since SvelteKit owns the landing page route.
+
+    Note: This only creates the file. TOC modification is handled by the build process.
+
+    Raises:
+        FileExistsError: If index.md already exists (users shouldn't create this file).
+    """
+    if content_type == "doc":
+        return  # Doc doesn't need a placeholder index.md
+
+    content_path = ap.paths.afterpython_path / content_type
+    index_file = content_path / "index.md"
+
+    # Check if user created an index.md file
+    if index_file.exists():
+        raise FileExistsError(
+            f"\n"
+            f"Found existing 'index.md' in afterpython/{content_type}/\n"
+            f"\n"
+            f"The 'index.md' file is reserved for internal use by AfterPython.\n"
+            f"MyST treats the first file in TOC as index, which would conflict with\n"
+            f"SvelteKit (project-website-template)'s landing page route (/{content_type}).\n"
+            f"\n"
+            f"Please rename your file to something else (e.g., '{content_type}_intro.md')\n"
+            f"and update the reference in afterpython/{content_type}/myst.yml"
+        )
+
+    index_content = f"""---
+title: ← {content_type.capitalize()}
+---
+
+This is a placeholder index page. The actual {content_type} landing page is rendered by SvelteKit.
+"""
+    index_file.write_text(index_content)
+    return index_file
+
+
+def _write_welcome_file(content_type: tContentType):
+    welcome_file = ap.paths.afterpython_path / content_type / "index.md"
+    if welcome_file.exists():
+        return
+    welcome_content = f"""# Welcome to AfterPython
+
+Welcome to your project's {content_type}! This is a starter page to help you get started.
+
+## Getting Started
+
+Replace this placeholder content with your own. Here's what you can do:
+
+- Creating new `.md` or `.ipynb` files in the `afterpython/{content_type}/` directory
+- Writing in MyST Markdown format
+- Adding images to the `afterpython/static/` directory and referencing them
+
+## Resources
+
+- [AfterPython's Project Website](https://afterpython.afterpython.org)
+- [MyST Markdown Guide](https://mystmd.org)
+
+Start building your amazing project! 🚀
+"""
+    welcome_file.write_text(welcome_content)
+    return welcome_file
+
+
+def init_myst():
+    """
+    Initialize MyST Markdown (mystmd) and myst.yml files in
+    doc/, blog/, tutorial/, example/, guide/ directories with sensible defaults
+    """
+    from afterpython.const import CONTENT_TYPES
+    from afterpython.utils import find_node_env
+
+    # find any existing node.js version and use it, if no, install the Node.js version specified in NODEENV_VERSION
+    node_env: NodeEnv = find_node_env()
+    subprocess.run(["npm", "install", "-g", "pnpm"], env=node_env, check=True)
+    for content_type in CONTENT_TYPES:
+        path = ap.paths.afterpython_path / content_type
+        print(f"Initializing MyST Markdown (mystmd) in {path.name}/ directory ...")
+        path.mkdir(parents=True, exist_ok=True)
+        subprocess.run(["myst", "init"], cwd=path, input="n\n", text=True, env=node_env)
+        myst_yml_defaults = {
+            "extends": "../authors.yml",
+            "project": {
+                "license": "CC-BY-4.0",
+                "subject": content_type.capitalize()
+                if content_type != "doc"
+                else "Documentation",
+            },
+            "site": {
+                "options": {
+                    "analytics_google": "{{ GOOGLE_ANALYTICS_ID }}",
+                    # "twitter": "",
+                },
+            },
+        }
+        update_myst_yml(myst_yml_defaults, path, add_comments=True)
+        _write_welcome_file(content_type)
+    subprocess.run(["ap", "sync"])

afterpython/tools/pre_commit.py

@@ -0,0 +1,37 @@
+import shutil
+import subprocess
+
+import afterpython as ap
+from afterpython._io.yaml import read_yaml, write_yaml
+
+
+def install_pre_commit():
+    # installed in .git/hooks
+    subprocess.run(["ap", "pre-commit", "install", "--install-hooks"], check=True)
+
+
+def update_pre_commit(data_update: dict):
+    from afterpython.utils import deep_merge
+
+    pre_commit_path = ap.paths.afterpython_path / ".pre-commit-config.yaml"
+    if not pre_commit_path.exists():
+        raise FileNotFoundError(
+            f".pre-commit-config.yaml not found at {pre_commit_path}"
+        )
+    existing_data = read_yaml(pre_commit_path)
+    existing_data = deep_merge(existing_data, data_update)
+    write_yaml(pre_commit_path, existing_data)
+    install_pre_commit()
+
+
+def init_pre_commit():
+    pre_commit_path = ap.paths.afterpython_path / ".pre-commit-config.yaml"
+    if pre_commit_path.exists():
+        print(f".pre-commit-config.yaml already exists at {pre_commit_path}")
+        return
+    pre_commit_template_path = (
+        ap.paths.templates_path / "pre-commit-config-template.yaml"
+    )
+    shutil.copy(pre_commit_template_path, pre_commit_path)
+    print(f"Created {pre_commit_path}")
+    install_pre_commit()