pptx2markdown 0.1.0__py3-none-any.whl

pptx2markdown/__init__.py

@@ -0,0 +1,13 @@
+"""pptx2markdown — convert PPTX/PPT presentations to Markdown."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("pptx2markdown")
+except PackageNotFoundError:  # 개발 트리에서 미설치 상태로 import된 경우
+    __version__ = "0.0.0"
+
+from pptx2markdown.api import convert
+
+__all__ = ["convert", "__version__"]

pptx2markdown/api.py

@@ -0,0 +1,69 @@
+"""Programmatic API for pptx2markdown.
+
+Example:
+    import pptx2markdown
+
+    pptx2markdown.convert("deck.pptx", output_dir="out")
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Optional, Sequence, Union
+
+PathLike = Union[str, Path]
+
+
+def convert(
+    inputs: Union[PathLike, Sequence[PathLike], None] = None,
+    *,
+    output_dir: Optional[PathLike] = None,
+    work_dir: Optional[PathLike] = None,
+    output_format: str = "markdown",
+    headings: str = "auto",
+    placeholder_inheritance: str = "style",
+    inherited_shapes: str = "visible",
+    ppt_converter: str = "auto",
+    verbose: bool = False,
+) -> int:
+    """Convert PPTX/PPT file(s) to Markdown or JSON.
+
+    Args:
+        inputs: A path or list of paths to ``.pptx``/``.ppt`` files. If omitted,
+            every presentation in the current directory is processed.
+        output_dir: Where converted output is written
+            (default: ``./output``).
+        work_dir: Where intermediate artifacts and caches live
+            (default: ``./.pptx2markdown``).
+        output_format: ``"markdown"`` (default) or ``"json"``.
+    Returns:
+        Process-style exit code: ``0`` on success, ``1`` if any slide failed.
+    """
+    from pptx2markdown.main_converter.run_pptx_to_markdown import (
+        _build_config,
+        _configure_logging,
+        run,
+    )
+
+    if inputs is None:
+        input_list: list[str] = []
+    elif isinstance(inputs, (str, Path)):
+        input_list = [str(inputs)]
+    else:
+        input_list = [str(p) for p in inputs]
+
+    args = argparse.Namespace(
+        inputs=input_list,
+        output_dir=str(output_dir) if output_dir else None,
+        work_dir=str(work_dir) if work_dir else None,
+        output_format=output_format,
+        headings=headings,
+        pptx_inheritance=placeholder_inheritance,
+        inherited_shapes=inherited_shapes,
+        ppt_converter=ppt_converter,
+        verbose=bool(verbose),
+    )
+    _configure_logging(verbose=bool(verbose))
+    config = _build_config(args)
+    return run(config)

pptx2markdown/main_converter/asset_utils.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import filecmp
+import shutil
+from pathlib import Path
+from typing import Dict, Optional
+
+
+def _same_content(path_a: Path, path_b: Path) -> bool:
+    try:
+        return filecmp.cmp(path_a, path_b, shallow=False)
+    except OSError:
+        return False
+
+
+def _find_existing_copy(src: Path, dest_dir: Path) -> Optional[Path]:
+    stem = src.stem
+    suffix = src.suffix
+    candidates = [dest_dir / src.name]
+    candidates.extend(sorted(dest_dir.glob(f"{stem}-*{suffix}")))
+    for candidate in candidates:
+        if candidate.is_file() and _same_content(src, candidate):
+            return candidate
+    return None
+
+
+def _copy_asset_to_dir(
+    path: str,
+    dest_dir: Optional[Path],
+    copied_assets: Optional[Dict[str, Path]] = None,
+) -> Optional[str]:
+    if path.startswith("[unresolved-image") or dest_dir is None:
+        return None
+
+    src = Path(path)
+    if not src.exists() or not src.is_file():
+        return None
+
+    try:
+        src_key = str(src.resolve())
+    except Exception:
+        src_key = str(src)
+
+    if copied_assets is not None and src_key in copied_assets:
+        return str(copied_assets[src_key])
+
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    existing_copy = _find_existing_copy(src, dest_dir)
+    if existing_copy is not None:
+        if copied_assets is not None:
+            copied_assets[src_key] = existing_copy
+        return str(existing_copy)
+
+    dest = dest_dir / src.name
+    if dest.exists():
+        try:
+            same_file = dest.resolve() == src.resolve()
+        except Exception:
+            same_file = False
+        if not same_file:
+            same_file = _same_content(src, dest)
+        if not same_file:
+            stem = src.stem
+            suffix = src.suffix
+            n = 2
+            while dest.exists():
+                candidate = dest_dir / f"{stem}-{n}{suffix}"
+                if candidate.is_file() and _same_content(src, candidate):
+                    dest = candidate
+                    same_file = True
+                    break
+                dest = candidate
+                n += 1
+        if same_file:
+            if copied_assets is not None:
+                copied_assets[src_key] = dest
+            return str(dest)
+
+    shutil.copy2(src, dest)
+    if copied_assets is not None:
+        copied_assets[src_key] = dest
+    return str(dest)
+
+
+def copy_media_asset(
+    path: str,
+    media_dir: Optional[Path],
+    copied_media: Optional[Dict[str, Path]] = None,
+) -> str:
+    copied = _copy_asset_to_dir(path, dest_dir=media_dir, copied_assets=copied_media)
+    if copied is None:
+        return path
+    return copied

pptx2markdown/main_converter/converter_models.py

@@ -0,0 +1,323 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+def utc_now_z() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+@dataclass(frozen=True)
+class ParagraphSegment:
+    kind: str
+    text: str
+    target: Optional[str] = None
+    font_pt: Optional[float] = None
+
+
+@dataclass(frozen=True)
+class ShapeBlock:
+    kind: str
+    segments: List[ParagraphSegment] = field(default_factory=list)
+    level: Optional[int] = None
+    list_explicit_none: bool = False
+
+    @property
+    def plain_text(self) -> str:
+        parts = [
+            segment.text
+            for segment in self.segments
+            if segment.kind != "break" and segment.text.strip()
+        ]
+        return " ".join(parts).strip()
+
+    @property
+    def markdown_text(self) -> str:
+        rendered: List[str] = []
+        for segment in self.segments:
+            if segment.kind == "break":
+                if rendered:
+                    rendered.append("\n")
+                continue
+            text = segment.text.strip()
+            if not text:
+                continue
+            if segment.kind == "hyperlink" and segment.target:
+                label = text.replace("\\", "\\\\").replace("[", "\\[").replace("]", "\\]")
+                text = f"[{label}]({segment.target})"
+            if rendered and not rendered[-1].endswith("\n"):
+                rendered.append(" ")
+            rendered.append(text)
+        return "".join(rendered).strip()
+
+    @property
+    def has_math(self) -> bool:
+        return any(segment.kind in {"math_inline", "math_block"} for segment in self.segments)
+
+    @property
+    def is_math_only(self) -> bool:
+        non_empty = [segment for segment in self.segments if segment.text.strip()]
+        return bool(non_empty) and all(
+            segment.kind in {"math_inline", "math_block"} for segment in non_empty
+        )
+
+
+class SourceDocument(BaseModel):
+    """Stable source identity without machine-specific absolute paths."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(min_length=1)
+    format: Literal["pptx", "ppt"]
+
+    @model_validator(mode="after")
+    def validate_name_is_basename(self) -> "SourceDocument":
+        if Path(self.name).name != self.name:
+            raise ValueError("source name must be a basename")
+        return self
+
+
+class BoundingBox(BaseModel):
+    """Shape bounds in PowerPoint English Metric Units (EMU)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    x: int
+    y: int
+    width: int = Field(gt=0)
+    height: int = Field(gt=0)
+    unit: Literal["emu"] = "emu"
+
+    @classmethod
+    def from_corners(cls, corners: tuple[int, int, int, int]) -> "BoundingBox":
+        x1, y1, x2, y2 = corners
+        return cls(x=x1, y=y1, width=x2 - x1, height=y2 - y1)
+
+
+class ContentBlock(BaseModel):
+    """A rendered content unit in presentation reading order."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    kind: Literal[
+        "text",
+        "heading",
+        "list",
+        "math",
+        "image",
+        "chart",
+        "smartart",
+        "table",
+        "attachment",
+        "unsupported",
+    ]
+    content: str = Field(min_length=1)
+    shape_id: Optional[str] = None
+    heading_level: Optional[int] = Field(default=None, ge=1, le=6)
+    bbox: Optional[BoundingBox] = None
+    source_part: Literal["slide", "layout", "master"] = "slide"
+
+    @model_validator(mode="after")
+    def validate_heading_contract(self) -> "ContentBlock":
+        if not self.content.strip():
+            raise ValueError("content must not be blank")
+        if self.kind == "heading" and self.heading_level is None:
+            raise ValueError("heading blocks require heading_level")
+        if self.kind != "heading" and self.heading_level is not None:
+            raise ValueError("heading_level is only valid for heading blocks")
+        return self
+
+
+class SlideDocument(BaseModel):
+    """JSON-serializable intermediate representation for one slide."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    page: int = Field(ge=1)
+    hidden: bool = False
+    blocks: List[ContentBlock] = Field(default_factory=list)
+    notes: Optional[str] = None
+
+
+class PresentationDocument(BaseModel):
+    """Canonical intermediate representation shared by all output formats."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: Literal["1.0"] = "1.0"
+    source: SourceDocument
+    slides: List[SlideDocument] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def validate_slide_order(self) -> "PresentationDocument":
+        pages = [slide.page for slide in self.slides]
+        if pages != sorted(set(pages)):
+            raise ValueError("slide pages must be unique and strictly increasing")
+        return self
+
+
+def render_slide_markdown(slide: SlideDocument) -> str:
+    parts = [f"[Page_{slide.page}]"]
+    if slide.hidden:
+        parts.append("<!-- hidden: true -->")
+    for block in slide.blocks:
+        content = block.content.strip()
+        if not content:
+            continue
+        if block.kind == "heading" and block.heading_level is not None:
+            content = f"{'#' * block.heading_level} {content}"
+        parts.append(content)
+    if slide.notes and slide.notes.strip():
+        parts.extend(["[Speaker_Notes]", slide.notes.strip()])
+    return "\n\n".join(parts).rstrip() + "\n"
+
+
+def render_presentation_markdown(document: PresentationDocument) -> str:
+    rendered_slides = [render_slide_markdown(slide).rstrip() for slide in document.slides]
+    merged = "\n\n".join(rendered_slides).strip()
+    return f"{merged}\n" if merged else ""
+
+
+class SlideStats(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    blocks_total: int = 0
+    text_blocks: int = 0
+    math_blocks: int = 0
+    inline_math_segments: int = 0
+    block_math_segments: int = 0
+    math_conversion_failures: int = 0
+    image_blocks: int = 0
+    chart_blocks: int = 0
+    smartart_blocks: int = 0
+    table_blocks: int = 0
+    attachment_blocks: int = 0
+    table_skipped_blocks: int = 0
+    unsupported_blocks: int = 0
+    skipped_blocks: int = 0
+    resolved_images: int = 0
+    unresolved_images: int = 0
+    warnings: List[str] = Field(default_factory=list)
+    rels_path: Optional[str] = None
+
+    def to_slide_row_fields(self) -> Dict[str, object]:
+        return {
+            "blocks_total": self.blocks_total,
+            "text_blocks": self.text_blocks,
+            "math_blocks": self.math_blocks,
+            "inline_math_segments": self.inline_math_segments,
+            "block_math_segments": self.block_math_segments,
+            "math_conversion_failures": self.math_conversion_failures,
+            "image_blocks": self.image_blocks,
+            "chart_blocks": self.chart_blocks,
+            "smartart_blocks": self.smartart_blocks,
+            "table_blocks": self.table_blocks,
+            "attachment_blocks": self.attachment_blocks,
+            "table_skipped_blocks": self.table_skipped_blocks,
+            "unsupported_blocks": self.unsupported_blocks,
+            "skipped_blocks": self.skipped_blocks,
+            "rels_path": self.rels_path,
+            "warnings": list(self.warnings),
+        }
+
+
+class ManifestSummary(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    processed_packages: int = 0
+    processed_slides: int = 0
+    failed: int = 0
+    math_blocks: int = 0
+    inline_math_segments: int = 0
+    block_math_segments: int = 0
+    math_conversion_failures: int = 0
+    resolved_images: int = 0
+    unresolved_images: int = 0
+    chart_blocks: int = 0
+    smartart_blocks: int = 0
+    table_blocks: int = 0
+    attachment_blocks: int = 0
+    table_skipped_blocks: int = 0
+
+    def add_slide(self, stats: SlideStats) -> None:
+        self.processed_slides += 1
+        self.math_blocks += stats.math_blocks
+        self.inline_math_segments += stats.inline_math_segments
+        self.block_math_segments += stats.block_math_segments
+        self.math_conversion_failures += stats.math_conversion_failures
+        self.resolved_images += stats.resolved_images
+        self.unresolved_images += stats.unresolved_images
+        self.chart_blocks += stats.chart_blocks
+        self.smartart_blocks += stats.smartart_blocks
+        self.table_blocks += stats.table_blocks
+        self.attachment_blocks += stats.attachment_blocks
+        self.table_skipped_blocks += stats.table_skipped_blocks
+
+
+class ConversionManifest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    started_at: str = Field(default_factory=utc_now_z)
+    packages: List[Dict[str, object]] = Field(default_factory=list)
+    summary: ManifestSummary = Field(default_factory=ManifestSummary)
+    finished_at: Optional[str] = None
+
+    def mark_finished(self) -> None:
+        self.finished_at = utc_now_z()
+
+
+class PreparedPackage(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
+
+    package_dir: Path
+    source_pptx_path: Path
+
+    @property
+    def source_stem(self) -> str:
+        stem = self.source_pptx_path.stem.strip()
+        return stem or self.package_dir.name
+
+    @property
+    def package_dir_name(self) -> str:
+        return self.source_stem
+
+    @property
+    def name(self) -> str:
+        return self.package_dir.name
+
+    @property
+    def output_markdown_name(self) -> str:
+        return f"{self.source_stem}.md"
+
+    def output_markdown_path(self, output_dir: Path) -> Path:
+        return output_dir / self.name / self.output_markdown_name
+
+    @property
+    def output_json_name(self) -> str:
+        return f"{self.source_stem}.json"
+
+    def output_json_path(self, output_dir: Path) -> Path:
+        return output_dir / self.name / self.output_json_name
+
+    def with_package_dir(self, package_dir: Path) -> "PreparedPackage":
+        return self.model_copy(update={"package_dir": package_dir})
+
+
+# 전체 변환 파이프라인의 정규화된 실행 설정이다.
+class ConverterConfig(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
+
+    cwd: Path
+    output_dir: Path
+    inputs: List[str] = Field(default_factory=list)
+    output_format: str = "markdown"
+    heading_mode: str = "auto"
+    strict: bool = False
+    pptx_inheritance: str = "style"
+    inherited_shapes: str = "visible"
+    ppt_converter: str = "auto"