full-stack-coding-assistant-agent 0.1.0__py3-none-any.whl

utils/pdf_reader.py

@@ -0,0 +1,122 @@
+"""
+PDF 文档读取器 - 从 PDF 文件中提取文本内容作为项目描述
+
+支持 PyPDF2 纯 Python 解析，零系统依赖。
+设计为可扩展，后续可增加 docx/txt 等格式。
+"""
+
+import re
+from pathlib import Path
+from typing import Tuple
+
+
+class PDFReader:
+    """PDF 文件文本提取器"""
+
+    @staticmethod
+    def extract_text(file_path: str) -> str:
+        """
+        从 PDF 文件中提取全部文本
+
+        Args:
+            file_path: PDF 文件路径
+
+        Returns:
+            提取的文本内容
+
+        Raises:
+            FileNotFoundError: 文件不存在
+            ValueError: 文件不是 PDF 或无法读取
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"文件不存在: {file_path}")
+
+        if path.suffix.lower() != ".pdf":
+            raise ValueError(f"文件不是 PDF 格式: {file_path}")
+
+        try:
+            from PyPDF2 import PdfReader
+        except ImportError:
+            raise ImportError("需要安装 PyPDF2: pip install PyPDF2")
+
+        reader = PdfReader(str(path))
+        pages = []
+        for page in reader.pages:
+            text = page.extract_text()
+            if text:
+                pages.append(text)
+
+        if not pages:
+            raise ValueError(f"PDF 文件中没有可提取的文本: {file_path}")
+
+        full_text = "\n\n".join(pages)
+        return PDFReader._clean_text(full_text)
+
+    @staticmethod
+    def extract_summary(
+        file_path: str,
+        max_chars: int = 100,
+    ) -> Tuple[str, str]:
+        """
+        从 PDF 提取文本，同时返回摘要和完整内容
+
+        Args:
+            file_path: PDF 文件路径
+            max_chars: 摘要最大字符数
+
+        Returns:
+            (summary, full_text) 元组
+        """
+        full_text = PDFReader.extract_text(file_path)
+        # 取第一段非空内容作为摘要
+        first_line = full_text.strip().split("\n")[0].strip() if full_text else ""
+        if len(first_line) > max_chars:
+            summary = first_line[:max_chars] + "..."
+        else:
+            summary = first_line[:max_chars]
+        return summary, full_text
+
+    @staticmethod
+    def _clean_text(text: str) -> str:
+        """
+        清洗 PDF 提取的文本：
+        - 合并多余空白行
+        - 修复断行（PDF 常见的换行符问题）
+        - 移除页码等噪音
+        """
+        # 移除多余空白行（3个以上连续空行合并为2个）
+        text = re.sub(r"\n{3,}", "\n\n", text)
+        # 移除行尾多余空格
+        text = re.sub(r"[ \t]+$", "", text, flags=re.MULTILINE)
+        # 移除页码模式（如 "Page 1 of 10" 或 "- 1 -"）
+        text = re.sub(
+            r"\n\s*(?:Page\s+\d+\s+of\s+\d+|[-\s]*\d+[-\s]*)\s*\n", "\n", text
+        )
+        return text.strip()
+
+
+def read_document(file_path: str) -> Tuple[str, str]:
+    """
+    通用文档读取入口，根据扩展名自动选择解析器
+
+    当前支持: .pdf
+    后续扩展: .docx, .txt, .md
+
+    Args:
+        file_path: 文档路径
+
+    Returns:
+        (summary, full_text) 元组
+    """
+    path = Path(file_path)
+    suffix = path.suffix.lower()
+
+    if suffix == ".pdf":
+        return PDFReader.extract_summary(file_path)
+    elif suffix in (".txt", ".md"):
+        content = path.read_text(encoding="utf-8")
+        summary = content[:100].replace("\n", " ").strip()
+        return summary, content
+    else:
+        raise ValueError(f"不支持的文件格式: {suffix}，当前支持 .pdf / .txt / .md")

utils/version.py

@@ -0,0 +1,188 @@
+"""
+版本管理工具模块
+
+提供版本号读取、校验和升级接口，版本号统一从项目根目录的 VERSION 文件读取。
+"""
+
+import re
+from pathlib import Path
+from typing import Literal, Optional
+
+# 项目根目录（向上查找 VERSION 文件）
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+VERSION_FILE = PROJECT_ROOT / "VERSION"
+
+# 语义化版本正则表达式（支持预发布标签和构建元数据）
+SEMVER_PATTERN = re.compile(
+    r"^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)"
+    r"(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?"
+    r"(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$"
+)
+
+
+def get_version() -> str:
+    """
+    从 VERSION 文件读取当前版本号
+
+    Returns:
+        版本号字符串（如 "0.1.0"）
+
+    Raises:
+        FileNotFoundError: VERSION 文件不存在
+        ValueError: VERSION 文件格式错误
+    """
+    if not VERSION_FILE.exists():
+        raise FileNotFoundError(f"VERSION 文件不存在: {VERSION_FILE}")
+
+    version = VERSION_FILE.read_text(encoding="utf-8").strip()
+
+    if not version:
+        raise ValueError("VERSION 文件为空")
+
+    # 校验版本号格式
+    if not validate_version(version):
+        raise ValueError(f"VERSION 文件中的版本号格式错误: {version}")
+
+    return version
+
+
+def validate_version(version: str) -> bool:
+    """
+    校验版本号是否符合语义化版本规范（SemVer 2.0.0）
+
+    Args:
+        version: 版本号字符串
+
+    Returns:
+        True 如果格式正确，否则 False
+    """
+    return SEMVER_PATTERN.match(version) is not None
+
+
+def bump_version(
+    part: Literal["major", "minor", "patch"] = "patch",
+    prerelease: Optional[str] = None,
+    dry_run: bool = False,
+) -> str:
+    """
+    升级版本号并写回 VERSION 文件
+
+    Args:
+        part: 升级部分（major/minor/patch）
+        prerelease: 预发布标签（如 "alpha.1"、"beta.1"）
+        dry_run: 如果为 True，只计算新版本号但不写入文件
+
+    Returns:
+        新版本号字符串
+
+    Examples:
+        >>> bump_version("patch")  # 0.1.0 -> 0.1.1
+        >>> bump_version("minor")  # 0.1.0 -> 0.2.0
+        >>> bump_version("major")  # 0.1.0 -> 1.0.0
+        >>> bump_version("patch", prerelease="alpha.1")  # 0.1.0 -> 0.1.1-alpha.1
+    """
+    current = get_version()
+    match = SEMVER_PATTERN.match(current)
+
+    if match is None:
+        raise ValueError(f"当前版本号格式错误: {current}")
+
+    major = int(match.group("major"))
+    minor = int(match.group("minor"))
+    patch = int(match.group("patch"))
+
+    # 升级对应部分
+    if part == "major":
+        major += 1
+        minor = 0
+        patch = 0
+    elif part == "minor":
+        minor += 1
+        patch = 0
+    elif part == "patch":
+        patch += 1
+    else:
+        raise ValueError(f"无效的升级部分: {part}，支持 major/minor/patch")
+
+    # 构建新版本号
+    new_version = f"{major}.{minor}.{patch}"
+    if prerelease:
+        new_version += f"-{prerelease}"
+
+    if not dry_run:
+        write_version(new_version)
+
+    return new_version
+
+
+def write_version(version: str) -> None:
+    """
+    将版本号写入 VERSION 文件
+
+    Args:
+        version: 版本号字符串
+
+    Raises:
+        ValueError: 版本号格式错误
+    """
+    if not validate_version(version):
+        raise ValueError(f"版本号格式错误: {version}")
+
+    VERSION_FILE.write_text(f"{version}\n", encoding="utf-8")
+
+
+def get_version_info() -> dict:
+    """
+    获取版本号详细信息
+
+    Returns:
+        包含版本号各部分的字典，如：
+        {
+            "version": "0.1.0",
+            "major": 0,
+            "minor": 1,
+            "patch": 0,
+            "prerelease": None,
+            "buildmetadata": None,
+        }
+    """
+    version = get_version()
+    match = SEMVER_PATTERN.match(version)
+
+    if match is None:
+        raise ValueError(f"版本号格式错误: {version}")
+
+    return {
+        "version": version,
+        "major": int(match.group("major")),
+        "minor": int(match.group("minor")),
+        "patch": int(match.group("patch")),
+        "prerelease": match.group("prerelease"),
+        "buildmetadata": match.group("buildmetadata"),
+    }
+
+
+if __name__ == "__main__":
+    # 命令行使用示例
+    import argparse
+
+    parser = argparse.ArgumentParser(description="版本管理工具")
+    parser.add_argument("--get", action="store_true", help="获取当前版本号")
+    parser.add_argument("--validate", type=str, help="校验版本号格式")
+    parser.add_argument("--bump", type=str, choices=["major", "minor", "patch"], help="升级版本号")
+    parser.add_argument("--prerelease", type=str, help="预发布标签")
+    parser.add_argument("--dry-run", action="store_true", help="只计算不写入")
+    args = parser.parse_args()
+
+    if args.get:
+        print(get_version())
+    elif args.validate is not None:
+        if validate_version(args.validate):
+            print(f"✅ 版本号格式正确: {args.validate}")
+        else:
+            print(f"❌ 版本号格式错误: {args.validate}")
+    elif args.bump:
+        new_version = bump_version(args.bump, prerelease=args.prerelease, dry_run=args.dry_run)
+        print(f"新版本号: {new_version}")
+    else:
+        print(get_version_info())