mystx.ext.github_readme_stats.base 源代码

"""
GitHub Readme Stats 指令的基础工具。

提供基类 `BaseGitHubCardDirective`，封装：
- 将选项字典转换为查询字符串；
- 生成原始 HTML `<img>` 节点用于嵌入卡片。
"""
from docutils import nodes
from docutils.parsers.rst import Directive



class BaseGitHubCardDirective(Directive):
    """GitHub 卡片指令的通用基类。

    继承自 `docutils.parsers.rst.Directive`，为各具体指令提供
    URL 构建与 HTML 节点生成的通用能力。
    """


    has_content = False




    def build_url(self, base_url, options):
        """根据基础地址和选项构建完整查询 URL。

        Args:
            base_url: GitHub Readme Stats 接口基础地址，例如
                `https://github-readme-stats.vercel.app/api`。
            options: 指令选项字典；布尔值 True 会被序列化为
                `key=true`，其他类型以 `key=value` 形式拼接。

        Returns:
            完整的查询 URL 字符串。
        """
        params = []
        for key, value in options.items():
            if isinstance(value, bool):
                if value:
                    params.append(f"{key}=true")
            else:
                params.append(f"{key}={value}")
        return f"{base_url}?{'&'.join(params)}"




    def create_image_node(self, url, alt="GitHub Card"):
        """创建原始 HTML 节点，以 `<img>` 标签插入卡片图片。

        Args:
            url: 图片地址（通常为 GitHub Readme Stats 服务的卡片 URL）。
            alt: 图片的替代文本。

        Returns:
            `docutils.nodes.raw` 节点，可直接嵌入到最终 HTML。
        """
        html = f'<img src="{url}" alt="{alt}">'
        return nodes.raw('', html, format='html')