readitdown 0.1.0__tar.gz

readitdown-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.3
+Name: readitdown
+Version: 0.1.0
+Summary: 문서 파일을 마크다운으로 변환하는 라이브러리 및 CLI
+Author: 정우창
+Author-email: woochang4862@gmail.com
+Requires-Python: >=3.13,<3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: click (>=8.0.0)
+Requires-Dist: markitdown[all] (>=0.1.4,<0.2.0)
+Requires-Dist: openai (>=1.0.0)
+Requires-Dist: pymupdf (>=1.24.0)
+Requires-Dist: python-dotenv (>=1.0.0)

readitdown-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "readitdown"
+version = "0.1.0"
+description = "문서 파일을 마크다운으로 변환하는 라이브러리 및 CLI"
+authors = [
+    {name = "정우창", email = "woochang4862@gmail.com"}
+]
+requires-python = ">=3.13,<3.14"
+dependencies = [
+    "openai (>=1.0.0)",
+    "pymupdf (>=1.24.0)",
+    "python-dotenv (>=1.0.0)",
+    "markitdown[all] (>=0.1.4,<0.2.0)",
+    "click (>=8.0.0)",
+]
+
+[project.scripts]
+readitdown = "readitdown.cli:main"
+
+[[tool.poetry.packages]]
+include = "readitdown"
+from = "src"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

readitdown-0.1.0/src/readitdown/__init__.py

@@ -0,0 +1,25 @@
+"""readitdown - 문서를 마크다운으로 변환하는 라이브러리."""
+
+from readitdown.converter import (
+    ConvertStats,
+    convert_dir,
+    convert_file,
+    supported_formats,
+)
+from readitdown.exceptions import (
+    APIKeyMissingError,
+    ConversionError,
+    Doc2mdError,
+    UnsupportedFormatError,
+)
+
+__all__ = [
+    "convert_file",
+    "convert_dir",
+    "supported_formats",
+    "ConvertStats",
+    "Doc2mdError",
+    "APIKeyMissingError",
+    "ConversionError",
+    "UnsupportedFormatError",
+]

readitdown-0.1.0/src/readitdown/backends/hwp.py

@@ -0,0 +1,101 @@
+"""HWP/HWPX 백엔드 (LibreOffice 기반, 실험적)."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING, Callable
+
+from readitdown.exceptions import ConversionError, LibreOfficeNotFoundError
+
+if TYPE_CHECKING:
+    from openai import OpenAI
+
+HWP_EXTENSIONS = {".hwp", ".hwpx", ".hwt", ".hml", ".hwx", ".gul"}
+
+SOFFICE_PATHS = [
+    "/Applications/LibreOffice.app/Contents/MacOS/soffice",
+    shutil.which("soffice") or "",
+    shutil.which("libreoffice") or "",
+]
+
+
+def _find_soffice() -> str:
+    for p in SOFFICE_PATHS:
+        if p and os.path.isfile(p):
+            return p
+    raise LibreOfficeNotFoundError()
+
+
+def hwp_to_pdf(hwp_path: Path, output_path: Path) -> Path:
+    """HWP/HWPX 파일을 PDF로 변환합니다.
+
+    Args:
+        hwp_path: 변환할 HWP/HWPX 파일 경로
+        output_path: 저장할 PDF 경로
+
+    Returns:
+        저장된 PDF 파일 경로
+    """
+    hwp_path = hwp_path.resolve()
+    if not hwp_path.exists():
+        raise FileNotFoundError(f"파일을 찾을 수 없습니다: {hwp_path}")
+
+    soffice = _find_soffice()
+    output_path = output_path.resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # LibreOffice는 출력 디렉토리만 지정 가능 → 임시 디렉토리 사용 후 이동
+    with tempfile.TemporaryDirectory() as tmpdir:
+        result = subprocess.run(
+            [
+                soffice,
+                "--headless",
+                "--convert-to",
+                "pdf",
+                "--outdir",
+                tmpdir,
+                str(hwp_path),
+            ],
+            capture_output=True,
+            text=True,
+            timeout=300,
+        )
+
+        if result.returncode != 0:
+            raise ConversionError(f"LibreOffice 변환 실패: {result.stderr.strip()}")
+
+        generated_pdf = Path(tmpdir) / hwp_path.with_suffix(".pdf").name
+        if not generated_pdf.exists():
+            raise ConversionError(
+                "PDF 파일이 생성되지 않았습니다. "
+                "H2Orestart 확장이 설치되어 있는지 확인하세요: unopkg list"
+            )
+
+        shutil.move(str(generated_pdf), str(output_path))
+
+    return output_path
+
+
+def convert_hwp(
+    client: OpenAI,
+    file_path: Path,
+    *,
+    on_page: Callable[[int, int], None] | None = None,
+) -> str:
+    """HWP/HWPX → PDF 변환 후 PDF → 마크다운 변환.
+
+    Args:
+        client: OpenAI 클라이언트
+        file_path: HWP/HWPX 파일 경로
+        on_page: 페이지 진행 콜백 (current, total)
+    """
+    from readitdown.backends.vision import convert_pdf
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        pdf_path = Path(tmpdir) / file_path.with_suffix(".pdf").name
+        hwp_to_pdf(file_path, pdf_path)
+        return convert_pdf(client, pdf_path, on_page=on_page)

readitdown-0.1.0/src/readitdown/backends/office.py

@@ -0,0 +1,31 @@
+"""Office 문서 백엔드 (markitdown 기반)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def convert_office(file_path: Path) -> str:
+    """Office 문서(docx, pptx, doc, ppt)를 마크다운으로 변환합니다."""
+    from markitdown import MarkItDown
+
+    md = MarkItDown()
+    result = md.convert(str(file_path))
+    if result.text_content and len(result.text_content.strip()) > 10:
+        return result.text_content
+    return f"<!-- {file_path.name} - markitdown 변환 결과 없음 -->\n"
+
+
+def convert_excel(file_path: Path) -> str:
+    """Excel 파일을 markitdown으로 변환합니다."""
+    try:
+        from markitdown import MarkItDown
+
+        md = MarkItDown()
+        result = md.convert(str(file_path))
+        if result.text_content and len(result.text_content.strip()) > 50:
+            return result.text_content
+    except Exception:
+        pass
+
+    return f"<!-- Excel 파일: {file_path.name} - markitdown 변환 실패 -->\n"

readitdown-0.1.0/src/readitdown/backends/vision.py

@@ -0,0 +1,77 @@
+"""Gemini Vision 백엔드 (PDF, 이미지)."""
+
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+from typing import TYPE_CHECKING, Callable
+
+import fitz  # pymupdf
+
+from readitdown.prompts import PROMPT_IMAGE, PROMPT_PDF
+
+if TYPE_CHECKING:
+    from openai import OpenAI
+
+GEMINI_MODEL = "gemini-2.0-flash"
+
+
+def _image_to_base64(img_bytes: bytes) -> str:
+    return base64.b64encode(img_bytes).decode("utf-8")
+
+
+def _call_gemini(client: OpenAI, b64_img: str, prompt: str) -> str:
+    response = client.chat.completions.create(
+        model=GEMINI_MODEL,
+        messages=[
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": prompt},
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": f"data:image/png;base64,{b64_img}"},
+                    },
+                ],
+            }
+        ],
+        max_tokens=4096,
+    )
+    return response.choices[0].message.content
+
+
+def convert_pdf(
+    client: OpenAI,
+    pdf_path: Path,
+    *,
+    on_page: Callable[[int, int], None] | None = None,
+) -> str:
+    """PDF 파일을 마크다운으로 변환합니다.
+
+    Args:
+        client: OpenAI 클라이언트
+        pdf_path: PDF 파일 경로
+        on_page: 페이지 진행 콜백 (current, total)
+    """
+    doc = fitz.open(str(pdf_path))
+    pages_md = []
+    total = len(doc)
+
+    for i, page in enumerate(doc):
+        if on_page:
+            on_page(i + 1, total)
+        mat = fitz.Matrix(2, 2)
+        pix = page.get_pixmap(matrix=mat)
+        b64 = _image_to_base64(pix.tobytes("png"))
+        md = _call_gemini(client, b64, PROMPT_PDF)
+        pages_md.append(f"<!-- Page {i + 1} -->\n{md}")
+
+    doc.close()
+    return "\n\n---\n\n".join(pages_md)
+
+
+def convert_image(client: OpenAI, img_path: Path) -> str:
+    """이미지 파일을 마크다운으로 변환합니다."""
+    img_bytes = img_path.read_bytes()
+    b64 = _image_to_base64(img_bytes)
+    return _call_gemini(client, b64, PROMPT_IMAGE)

readitdown-0.1.0/src/readitdown/cli.py

@@ -0,0 +1,88 @@
+"""readitdown CLI (Click 기반)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from readitdown.converter import convert_dir, convert_file, supported_formats
+
+
+@click.group()
+def main():
+    """readitdown - 문서를 마크다운으로 변환합니다."""
+
+
+@main.command()
+@click.argument("path", type=click.Path(exists=True, path_type=Path))
+@click.option("-o", "--output", type=click.Path(path_type=Path), default=None, help="출력 파일 경로")
+@click.option("--api-key", envvar="GEMINI_API_KEY", default=None, help="Gemini API 키")
+def file(path: Path, output: Path | None, api_key: str | None):
+    """단일 파일을 마크다운으로 변환합니다."""
+
+    def on_page(current: int, total: int):
+        click.echo(f"  페이지 {current}/{total}...", nl=False)
+
+    try:
+        result = convert_file(path, api_key=api_key, on_page=on_page)
+    except Exception as e:
+        raise click.ClickException(str(e)) from e
+
+    click.echo()
+
+    if output:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(result, encoding="utf-8")
+        click.echo(f"저장: {output} ({len(result):,}자)")
+    else:
+        click.echo(result)
+
+
+@main.command()
+@click.argument("input_dir", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.argument("output_dir", type=click.Path(path_type=Path))
+@click.option("--skip-existing", is_flag=True, help="이미 변환된 파일 건너뛰기")
+@click.option("--only", type=str, default=None, help="파일명 필터 (예: '경기도')")
+@click.option("--api-key", envvar="GEMINI_API_KEY", default=None, help="Gemini API 키")
+def dir(input_dir: Path, output_dir: Path, skip_existing: bool, only: str | None, api_key: str | None):
+    """디렉토리 내 모든 문서를 일괄 변환합니다."""
+
+    def on_file(path: Path, status: str):
+        name = path.name
+        if status == "skipped":
+            click.echo(f"[건너뜀] {name}")
+        elif status == "converting":
+            click.echo(f"[변환중] {name}")
+        elif status.startswith("done:"):
+            chars = int(status.split(":")[1])
+            click.echo(f"  → 완료 ({chars:,}자)")
+
+    def on_page(current: int, total: int):
+        click.echo(f"  페이지 {current}/{total}...", nl=False)
+
+    def on_error(path: Path, error: Exception):
+        click.echo(f"  → 오류: {error}", err=True)
+
+    stats = convert_dir(
+        input_dir,
+        output_dir,
+        api_key=api_key,
+        skip_existing=skip_existing,
+        only=only,
+        on_file=on_file,
+        on_page=on_page,
+        on_error=on_error,
+    )
+
+    click.echo(f"\n완료: 성공 {stats.success}, 건너뜀 {stats.skipped}, 실패 {stats.failed}")
+
+
+@main.command()
+def formats():
+    """지원하는 파일 형식을 출력합니다."""
+    for category, exts in supported_formats().items():
+        click.echo(f"{category}:")
+        for ext in exts:
+            click.echo(f"  {ext}")
+        click.echo()

readitdown-0.1.0/src/readitdown/client.py

@@ -0,0 +1,33 @@
+"""OpenAI 클라이언트 팩토리 (Gemini Vision API용, 3-tier 키 해석)."""
+
+from __future__ import annotations
+
+import os
+
+from dotenv import load_dotenv
+from openai import OpenAI
+
+from readitdown.exceptions import APIKeyMissingError
+
+GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+
+
+def create_client(api_key: str | None = None) -> OpenAI:
+    """OpenAI 클라이언트를 생성합니다.
+
+    API 키 해석 순서:
+      1. 명시적 파라미터
+      2. 환경변수 GEMINI_API_KEY
+      3. .env 파일 (python-dotenv)
+    """
+    if api_key is None:
+        api_key = os.environ.get("GEMINI_API_KEY")
+
+    if api_key is None:
+        load_dotenv()
+        api_key = os.environ.get("GEMINI_API_KEY")
+
+    if not api_key:
+        raise APIKeyMissingError()
+
+    return OpenAI(api_key=api_key, base_url=GEMINI_BASE_URL)

readitdown-0.1.0/src/readitdown/converter.py

@@ -0,0 +1,174 @@
+"""메인 변환 라우터."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+from openai import OpenAI
+
+from readitdown.client import create_client
+from readitdown.exceptions import UnsupportedFormatError
+
+HWP_EXTENSIONS = {".hwp", ".hwpx", ".hwt", ".hml", ".hwx", ".gul"}
+MARKITDOWN_EXTENSIONS = {".docx", ".pptx", ".doc", ".ppt"}
+VISION_EXTENSIONS = {".pdf", ".jpg", ".jpeg", ".png"}
+EXCEL_EXTENSIONS = {".xlsx", ".xls"}
+SUPPORTED_EXTENSIONS = HWP_EXTENSIONS | MARKITDOWN_EXTENSIONS | VISION_EXTENSIONS | EXCEL_EXTENSIONS
+
+
+@dataclass
+class ConvertStats:
+    """디렉토리 변환 통계."""
+
+    success: int = 0
+    skipped: int = 0
+    failed: int = 0
+    errors: list[tuple[str, str]] = field(default_factory=list)
+
+
+def convert_file(
+    file_path: str | Path,
+    *,
+    api_key: str | None = None,
+    client: OpenAI | None = None,
+    on_page: Callable[[int, int], None] | None = None,
+) -> str:
+    """단일 파일을 마크다운으로 변환합니다.
+
+    Args:
+        file_path: 변환할 파일 경로
+        api_key: Gemini API 키 (없으면 환경변수/.env에서 탐색)
+        client: 기존 OpenAI 클라이언트 (재사용 시)
+        on_page: PDF 페이지 진행 콜백 (current, total)
+
+    Returns:
+        변환된 마크다운 문자열
+
+    Raises:
+        UnsupportedFormatError: 지원하지 않는 형식
+        ConversionError: 변환 실패
+        APIKeyMissingError: API 키 미설정 (Vision 백엔드 필요 시)
+    """
+    file_path = Path(file_path)
+    ext = file_path.suffix.lower()
+
+    if ext not in SUPPORTED_EXTENSIONS:
+        raise UnsupportedFormatError(ext)
+
+    # Vision 백엔드가 필요한 형식은 클라이언트 생성
+    needs_vision = ext in (HWP_EXTENSIONS | VISION_EXTENSIONS)
+    if needs_vision and client is None:
+        client = create_client(api_key)
+
+    if ext in HWP_EXTENSIONS:
+        from readitdown.backends.hwp import convert_hwp
+
+        return convert_hwp(client, file_path, on_page=on_page)
+    elif ext == ".pdf":
+        from readitdown.backends.vision import convert_pdf
+
+        return convert_pdf(client, file_path, on_page=on_page)
+    elif ext in {".jpg", ".jpeg", ".png"}:
+        from readitdown.backends.vision import convert_image
+
+        return convert_image(client, file_path)
+    elif ext in EXCEL_EXTENSIONS:
+        from readitdown.backends.office import convert_excel
+
+        return convert_excel(file_path)
+    elif ext in MARKITDOWN_EXTENSIONS:
+        from readitdown.backends.office import convert_office
+
+        return convert_office(file_path)
+
+    raise UnsupportedFormatError(ext)
+
+
+def convert_dir(
+    input_dir: str | Path,
+    output_dir: str | Path,
+    *,
+    api_key: str | None = None,
+    skip_existing: bool = False,
+    only: str | None = None,
+    on_file: Callable[[Path, str], None] | None = None,
+    on_page: Callable[[int, int], None] | None = None,
+    on_error: Callable[[Path, Exception], None] | None = None,
+) -> ConvertStats:
+    """디렉토리 내 모든 지원 파일을 일괄 변환합니다.
+
+    Args:
+        input_dir: 원본 파일 디렉토리
+        output_dir: 변환 결과 저장 디렉토리
+        api_key: Gemini API 키
+        skip_existing: 이미 변환된 파일 건너뛰기
+        only: 파일명 필터 문자열
+        on_file: 파일 처리 콜백 (path, status)
+        on_page: PDF 페이지 진행 콜백 (current, total)
+        on_error: 오류 발생 콜백 (path, exception)
+
+    Returns:
+        ConvertStats 통계 객체
+    """
+    input_dir = Path(input_dir)
+    output_dir = Path(output_dir)
+    stats = ConvertStats()
+
+    # 파일 수집
+    files = sorted(
+        f
+        for f in input_dir.rglob("*")
+        if f.is_file() and f.suffix.lower() in SUPPORTED_EXTENSIONS
+    )
+
+    if only:
+        files = [f for f in files if only in str(f)]
+
+    if not files:
+        return stats
+
+    client = create_client(api_key)
+
+    for file_path in files:
+        rel = file_path.relative_to(input_dir)
+        out_path = output_dir / rel.with_suffix(".md")
+
+        if skip_existing and out_path.exists():
+            if on_file:
+                on_file(file_path, "skipped")
+            stats.skipped += 1
+            continue
+
+        if on_file:
+            on_file(file_path, "converting")
+
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            result = convert_file(
+                file_path, client=client, on_page=on_page
+            )
+            out_path.write_text(result, encoding="utf-8")
+            if on_file:
+                on_file(file_path, f"done:{len(result)}")
+            stats.success += 1
+        except Exception as e:
+            if on_error:
+                on_error(file_path, e)
+            stats.failed += 1
+            stats.errors.append((str(rel), str(e)))
+
+    return stats
+
+
+def supported_formats() -> dict[str, list[str]]:
+    """지원 형식을 카테고리별로 반환합니다."""
+    return {
+        "HWP (LibreOffice)": sorted(HWP_EXTENSIONS),
+        "PDF (Gemini Vision)": sorted(VISION_EXTENSIONS - {".jpg", ".jpeg", ".png"}),
+        "이미지 (Gemini Vision)": sorted({".jpg", ".jpeg", ".png"}),
+        "Excel (markitdown)": sorted(EXCEL_EXTENSIONS),
+        "Office (markitdown)": sorted(MARKITDOWN_EXTENSIONS),
+    }

readitdown-0.1.0/src/readitdown/exceptions.py

@@ -0,0 +1,33 @@
+"""doc2md 커스텀 예외."""
+
+
+class Doc2mdError(Exception):
+    """doc2md 기본 예외."""
+
+
+class APIKeyMissingError(Doc2mdError):
+    """API 키가 설정되지 않았을 때 발생."""
+
+    def __init__(self, msg: str = "GEMINI_API_KEY가 설정되지 않았습니다."):
+        super().__init__(msg)
+
+
+class ConversionError(Doc2mdError):
+    """문서 변환 중 오류 발생."""
+
+
+class UnsupportedFormatError(Doc2mdError):
+    """지원하지 않는 파일 형식."""
+
+    def __init__(self, ext: str):
+        super().__init__(f"지원하지 않는 형식입니다: {ext}")
+        self.ext = ext
+
+
+class LibreOfficeNotFoundError(Doc2mdError):
+    """LibreOffice가 설치되지 않았을 때 발생."""
+
+    def __init__(self):
+        super().__init__(
+            "LibreOffice를 찾을 수 없습니다. 설치하세요: brew install --cask libreoffice"
+        )

readitdown-0.1.0/src/readitdown/prompts.py

@@ -0,0 +1,19 @@
+"""Gemini Vision API 프롬프트 (한국어)."""
+
+PROMPT_PDF = (
+    "이 PDF 페이지를 마크다운으로 변환해주세요. "
+    "표가 있으면 마크다운 테이블로, 제목은 적절한 헤딩으로, 목록은 리스트로 변환하세요. "
+    "원문 내용을 빠짐없이 포함하세요. 마크다운만 출력하고 다른 설명은 하지 마세요."
+)
+
+PROMPT_IMAGE = (
+    "이 이미지의 내용을 마크다운으로 변환해주세요. "
+    "텍스트가 있으면 그대로 옮기고, 표가 있으면 마크다운 테이블로 변환하세요. "
+    "마크다운만 출력하고 다른 설명은 하지 마세요."
+)
+
+PROMPT_EXCEL = (
+    "이 엑셀 시트 이미지를 마크다운 테이블로 변환해주세요. "
+    "모든 셀 데이터를 빠짐없이 포함하세요. "
+    "마크다운만 출력하고 다른 설명은 하지 마세요."
+)