afterpython 0.0.1.dev2__tar.gz → 0.1.0.dev4__tar.gz

afterpython-0.1.0.dev4/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: afterpython
+Version: 0.1.0.dev4
+Summary: CLI tool for AfterPython
+Keywords: package-maintenance,project-website,static-site-generator,developer-tools,documentation,cli-tool,ci/cd,mystmd,semantic-release,python-packaging
+Author: Stephen Yau
+Author-email: Stephen Yau <softwareentrepreneer+afterpython@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: click>=8.3.1
+Requires-Dist: trogon>=0.6.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: tomlkit>=0.13.3
+Requires-Dist: ruamel-yaml>=0.18.16
+Requires-Dist: gitpython>=3.1.45
+Requires-Dist: pygithub>=2.8.1
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: pyproject-metadata>=0.9.1
+Requires-Dist: mystmd>=1.6.6
+Requires-Dist: pdoc>=16.0.0
+Requires-Dist: ruff>=0.14.5
+Requires-Dist: pre-commit>=4.4.0
+Requires-Dist: commitizen>=4.10.0
+Requires-Python: >=3.11
+Project-URL: documentation, https://docs.afterpython.org
+Project-URL: homepage, https://afterpython.org
+Project-URL: repository, https://github.com/AfterPythonOrg/afterpython
+Description-Content-Type: text/markdown
+
+# AfterPython: Python Package Maintenance Toolkit and Project Website Generator
+
+[![afterpython](https://afterpython.org/shield.svg)](https://afterpython.org)
+[![Pixi Badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://pixi.sh)
+![PyPI downloads](https://img.shields.io/pypi/dm/afterpython)
+[![PyPI](https://img.shields.io/pypi/v/afterpython.svg)](https://pypi.org/project/afterpython)
+![PyPI - Support Python Versions](https://img.shields.io/pypi/pyversions/afterpython)
+[![Discussions](https://img.shields.io/badge/Discussions-Let's%20Chat-green)](https://github.com/AfterPythonOrg/afterpython/discussions)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/AfterPythonOrg/afterpython)
+
+
+[MyST]: https://mystmd.org
+[MyST Markdown]: https://mystmd.org/spec/
+[Jupyter Notebook]: https://jupyter.org
+[pre-commit]: https://pre-commit.com
+[pagefind]: https://pagefind.app
+[SemVer]: https://semver.org
+[pdoc]: https://pdoc.dev/
+[GitHub Actions]: https://github.com/features/actions
+[PyTorch]: https://pytorch.org
+[Scikit-Learn]: https://scikit-learn.org
+[WebLLM]: https://webllm.mlc.ai/
+[project-website-template]: https://github.com/AfterPythonOrg/project-website-template
+[uv]: https://docs.astral.sh/uv/
+[ruff]: https://docs.astral.sh/ruff/
+
+
+## Problem
+Going from **writing Python code to publishing and maintaining a package** is **time-consuming**.
+First-time maintainers must learn multiple tools and concepts, e.g. [MyST], [SemVer], CI/CD ([pre-commit] hooks, GitHub workflows), and they often spending hours just to deploy a documentation site whereas well-resourced projects like [PyTorch] and [Scikit-Learn] have **dedicated websites** that serve as their project hubs.
+
+
+## Solution
+`afterpython` **automates** the tedious parts of Python package maintenance and generates a **project website** for **building community** and **hosting content** such as documentation, **blog posts**, tutorials, examples and more — empowering more developers to write packages with ease.
+
+---
+`afterpython` is a CLI tool that **abstracts away the complexity** of **content writing, website deployment, and package release/maintenance** by providing an opinionated set of modern tools — so you don’t have to spend time selecting or learning anything beyond the basics.
+
+
+## Core Features
+- [x] Write content directly in [MyST Markdown] or [Jupyter Notebook]
+- [x] Go from writing to website deployment in minutes — no need to learn any of the underlying tools
+- [x] Centralize all your content in a modern, unified project website — from documentation to blog posts
+- [ ] Export content as PDF — for example, combine all blog posts into a single PDF file
+- [ ] **⚡ Full-text search** across **ALL** your content in your website — docs, blogs, tutorials, everything
+- [ ] **🤖 Embedded AI Chatbot** that answers questions directly using an in-browser LLM — at no cost
+
+
+## Installation
+```bash
+# install afterpython as a dev dependency
+uv add --dev afterpython
+# initialize afterpython
+ap init
+```
+
+
+## Tech Stack
+- [MyST]
+- [project-website-template]
+- [pre-commit]
+- [GitHub Actions]
+- [pdoc]
+- [uv]
+- [ruff]
+- [pagefind]
+- [WebLLM]
+<!-- - ty -->
+<!-- - [pixi] -->

afterpython-0.1.0.dev4/README.md

@@ -0,0 +1,69 @@
+# AfterPython: Python Package Maintenance Toolkit and Project Website Generator
+
+[![afterpython](https://afterpython.org/shield.svg)](https://afterpython.org)
+[![Pixi Badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://pixi.sh)
+![PyPI downloads](https://img.shields.io/pypi/dm/afterpython)
+[![PyPI](https://img.shields.io/pypi/v/afterpython.svg)](https://pypi.org/project/afterpython)
+![PyPI - Support Python Versions](https://img.shields.io/pypi/pyversions/afterpython)
+[![Discussions](https://img.shields.io/badge/Discussions-Let's%20Chat-green)](https://github.com/AfterPythonOrg/afterpython/discussions)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/AfterPythonOrg/afterpython)
+
+
+[MyST]: https://mystmd.org
+[MyST Markdown]: https://mystmd.org/spec/
+[Jupyter Notebook]: https://jupyter.org
+[pre-commit]: https://pre-commit.com
+[pagefind]: https://pagefind.app
+[SemVer]: https://semver.org
+[pdoc]: https://pdoc.dev/
+[GitHub Actions]: https://github.com/features/actions
+[PyTorch]: https://pytorch.org
+[Scikit-Learn]: https://scikit-learn.org
+[WebLLM]: https://webllm.mlc.ai/
+[project-website-template]: https://github.com/AfterPythonOrg/project-website-template
+[uv]: https://docs.astral.sh/uv/
+[ruff]: https://docs.astral.sh/ruff/
+
+
+## Problem
+Going from **writing Python code to publishing and maintaining a package** is **time-consuming**.
+First-time maintainers must learn multiple tools and concepts, e.g. [MyST], [SemVer], CI/CD ([pre-commit] hooks, GitHub workflows), and they often spending hours just to deploy a documentation site whereas well-resourced projects like [PyTorch] and [Scikit-Learn] have **dedicated websites** that serve as their project hubs.
+
+
+## Solution
+`afterpython` **automates** the tedious parts of Python package maintenance and generates a **project website** for **building community** and **hosting content** such as documentation, **blog posts**, tutorials, examples and more — empowering more developers to write packages with ease.
+
+---
+`afterpython` is a CLI tool that **abstracts away the complexity** of **content writing, website deployment, and package release/maintenance** by providing an opinionated set of modern tools — so you don’t have to spend time selecting or learning anything beyond the basics.
+
+
+## Core Features
+- [x] Write content directly in [MyST Markdown] or [Jupyter Notebook]
+- [x] Go from writing to website deployment in minutes — no need to learn any of the underlying tools
+- [x] Centralize all your content in a modern, unified project website — from documentation to blog posts
+- [ ] Export content as PDF — for example, combine all blog posts into a single PDF file
+- [ ] **⚡ Full-text search** across **ALL** your content in your website — docs, blogs, tutorials, everything
+- [ ] **🤖 Embedded AI Chatbot** that answers questions directly using an in-browser LLM — at no cost
+
+
+## Installation
+```bash
+# install afterpython as a dev dependency
+uv add --dev afterpython
+# initialize afterpython
+ap init
+```
+
+
+## Tech Stack
+- [MyST]
+- [project-website-template]
+- [pre-commit]
+- [GitHub Actions]
+- [pdoc]
+- [uv]
+- [ruff]
+- [pagefind]
+- [WebLLM]
+<!-- - ty -->
+<!-- - [pixi] -->

afterpython-0.1.0.dev4/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-0.1.0.dev4/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-0.1.0.dev4/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-0.1.0.dev4/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-0.1.0.dev4/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-0.1.0.dev4/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-0.1.0.dev4/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-0.1.0.dev4/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-0.1.0.dev4/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-0.1.0.dev4/afterpython/cli/__init__.py

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