python-hwpx 1.8__tar.gz → 2.0__tar.gz

{python_hwpx-1.8/src/python_hwpx.egg-info → python_hwpx-2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 1.8
+Version: 2.0
 Summary: Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음
 Author: python-hwpx Maintainers
 License: Non-Commercial License
@@ -59,6 +59,10 @@ Requires-Dist: twine>=4.0; extra == "dev"
 Requires-Dist: pytest>=7.4; extra == "dev"
 Provides-Extra: test
 Requires-Dist: pytest>=7.4; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Provides-Extra: typecheck
+Requires-Dist: mypy>=1.10; extra == "typecheck"
+Requires-Dist: pyright>=1.1.390; extra == "typecheck"
 Dynamic: license-file
 
 # python-hwpx
@@ -101,7 +105,7 @@ Sphinx 문서는 `docs/` 아래에 있으며, `python -m pip install -r docs/req
 ```python
 from io import BytesIO
 
-from hwpx.document import HwpxDocument
+from hwpx import HwpxDocument
 from hwpx.templates import blank_document_bytes
 
 # 1) 빈 템플릿으로 문서 열기
@@ -121,15 +125,26 @@ table.set_cell_text(1, 1, str(len(document.paragraphs)))
 document.add_memo_with_anchor("배포 전 검토", paragraph=paragraph, memo_shape_id_ref="0")
 
 # 3) 다른 이름으로 저장
-document.save("output/example.hwpx")
+document.save_to_path("output/example.hwpx")
 ```
 
 `HwpxDocument.add_table()`은 문서에 정의된 테두리 채우기가 없으면 헤더 참조 목록에 "기본 실선" `borderFill`을 만들어 표와 모든 셀에 참조를 연결합니다.
 
-표 셀 텍스트를 편집하는 `table.set_cell_text()`는 기존 단락에 남아 있는 `lineSegArray`와 같은 줄 배치 캐시를 제거하여 한/글이 문서를 다시 열 때 줄바꿈을 새로 계산하도록 합니다.
+표 셀 텍스트를 편집하는 `table.set_cell_text()`는 기존 단락에 남아 있는 `lineSegArray`와 같은 줄 배치 캐시를 제거하여 한/글이 문서를 다시 열 때 줄바꿈을 새로 계산하도록 합니다. 병합된 표 구조를 다뤄야 한다면 `table.iter_grid()` 또는 `table.get_cell_map()`으로 논리 격자와 실제 셀의 매핑을 확인하고, `set_cell_text(..., logical=True, split_merged=True)`로 논리 좌표 기반 편집과 자동 병합 해제를 동시에 처리할 수 있습니다.
 
 더 많은 실전 패턴은 [빠른 시작](docs/quickstart.md)과 [사용 가이드](docs/usage.md)의 "빠른 예제 모음"에서 확인할 수 있습니다.
 
+### 저장 API 변경 안내
+
+`HwpxDocument`는 저장 사용 케이스를 다음처럼 분리해 제공합니다.
+
+- `save_to_path(path) -> str | PathLike[str]`: 지정한 경로로 저장하고 같은 경로를 반환
+- `save_to_stream(stream) -> BinaryIO`: 파일/버퍼 스트림에 저장하고 같은 스트림을 반환
+- `to_bytes() -> bytes`: 메모리에서 직렬화한 바이트를 반환
+
+기존 `save()`는 하위 호환을 위해 유지되지만 deprecated 경고를 발생시킵니다. 새 코드에서는 위 3개 메서드 사용을 권장합니다.
+
+
 ## 문서
  [사용법](https://airmang.github.io/python-hwpx/)
 

{python_hwpx-1.8 → python_hwpx-2.0}/README.md

@@ -38,7 +38,7 @@ Sphinx 문서는 `docs/` 아래에 있으며, `python -m pip install -r docs/req
 ```python
 from io import BytesIO
 
-from hwpx.document import HwpxDocument
+from hwpx import HwpxDocument
 from hwpx.templates import blank_document_bytes
 
 # 1) 빈 템플릿으로 문서 열기
@@ -58,15 +58,26 @@ table.set_cell_text(1, 1, str(len(document.paragraphs)))
 document.add_memo_with_anchor("배포 전 검토", paragraph=paragraph, memo_shape_id_ref="0")
 
 # 3) 다른 이름으로 저장
-document.save("output/example.hwpx")
+document.save_to_path("output/example.hwpx")
 ```
 
 `HwpxDocument.add_table()`은 문서에 정의된 테두리 채우기가 없으면 헤더 참조 목록에 "기본 실선" `borderFill`을 만들어 표와 모든 셀에 참조를 연결합니다.
 
-표 셀 텍스트를 편집하는 `table.set_cell_text()`는 기존 단락에 남아 있는 `lineSegArray`와 같은 줄 배치 캐시를 제거하여 한/글이 문서를 다시 열 때 줄바꿈을 새로 계산하도록 합니다.
+표 셀 텍스트를 편집하는 `table.set_cell_text()`는 기존 단락에 남아 있는 `lineSegArray`와 같은 줄 배치 캐시를 제거하여 한/글이 문서를 다시 열 때 줄바꿈을 새로 계산하도록 합니다. 병합된 표 구조를 다뤄야 한다면 `table.iter_grid()` 또는 `table.get_cell_map()`으로 논리 격자와 실제 셀의 매핑을 확인하고, `set_cell_text(..., logical=True, split_merged=True)`로 논리 좌표 기반 편집과 자동 병합 해제를 동시에 처리할 수 있습니다.
 
 더 많은 실전 패턴은 [빠른 시작](docs/quickstart.md)과 [사용 가이드](docs/usage.md)의 "빠른 예제 모음"에서 확인할 수 있습니다.
 
+### 저장 API 변경 안내
+
+`HwpxDocument`는 저장 사용 케이스를 다음처럼 분리해 제공합니다.
+
+- `save_to_path(path) -> str | PathLike[str]`: 지정한 경로로 저장하고 같은 경로를 반환
+- `save_to_stream(stream) -> BinaryIO`: 파일/버퍼 스트림에 저장하고 같은 스트림을 반환
+- `to_bytes() -> bytes`: 메모리에서 직렬화한 바이트를 반환
+
+기존 `save()`는 하위 호환을 위해 유지되지만 deprecated 경고를 발생시킵니다. 새 코드에서는 위 3개 메서드 사용을 권장합니다.
+
+
 ## 문서
  [사용법](https://airmang.github.io/python-hwpx/)
 

{python_hwpx-1.8 → python_hwpx-2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "1.8"
+version = "2.0"
 description = "Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE" }
@@ -36,6 +36,11 @@ dev = [
 ]
 test = [
     "pytest>=7.4",
+    "pytest-cov>=5.0",
+]
+typecheck = [
+    "mypy>=1.10",
+    "pyright>=1.1.390",
 ]
 
 [project.urls]
@@ -55,6 +60,7 @@ where = ["src"]
 include = ["hwpx*"]
 
 [tool.setuptools.package-data]
+"hwpx" = ["py.typed"]
 "hwpx.tools" = ["_schemas/*.xsd"]
 "hwpx.data" = ["Skeleton.hwpx"]
 
@@ -62,3 +68,19 @@ include = ["hwpx*"]
 pythonpath = ["src"]
 addopts = "-ra"
 testpaths = ["tests"]
+
+
+[tool.mypy]
+python_version = "3.10"
+files = ["src/hwpx/document.py", "src/hwpx/oxml/document.py"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["hwpx.document", "hwpx.oxml.document"]
+ignore_errors = true
+
+[tool.pyright]
+include = ["src/hwpx/document.py", "src/hwpx/oxml/document.py"]
+pythonVersion = "3.10"
+typeCheckingMode = "off"
+reportMissingTypeStubs = false

python_hwpx-2.0/src/hwpx/__init__.py

@@ -0,0 +1,36 @@
+"""High-level utilities for working with HWPX documents."""
+
+from importlib.metadata import PackageNotFoundError, version as _metadata_version
+
+
+def _resolve_version() -> str:
+    """패키지 메타데이터에서 현재 배포 버전을 조회합니다."""
+    try:
+        return _metadata_version("python-hwpx")
+    except PackageNotFoundError:
+        return "0+unknown"
+
+
+__version__ = _resolve_version()
+
+from .tools.text_extractor import (
+    DEFAULT_NAMESPACES,
+    ParagraphInfo,
+    SectionInfo,
+    TextExtractor,
+)
+from .tools.object_finder import FoundElement, ObjectFinder
+from .document import HwpxDocument
+from .package import HwpxPackage
+
+__all__ = [
+    "__version__",
+    "DEFAULT_NAMESPACES",
+    "ParagraphInfo",
+    "SectionInfo",
+    "TextExtractor",
+    "FoundElement",
+    "ObjectFinder",
+    "HwpxDocument",
+    "HwpxPackage",
+]

{python_hwpx-1.8 → python_hwpx-2.0}/src/hwpx/document.py

@@ -2,12 +2,16 @@
 
 from __future__ import annotations
 
+import io
+import warnings
 from datetime import datetime
+import logging
 import uuid
-import xml.etree.ElementTree as ET
 
 from os import PathLike
-from typing import BinaryIO, Iterator, List, Tuple
+from typing import Any, BinaryIO, Iterator, overload
+
+from lxml import etree
 
 from .oxml import (
     Bullet,
@@ -31,21 +35,62 @@ from .oxml import (
     TrackChange,
     TrackChangeAuthor,
 )
-from .package import HwpxPackage
+from .opc.package import HwpxPackage
 from .templates import blank_document_bytes
 
+ET.register_namespace("hp", "http://www.hancom.co.kr/hwpml/2011/paragraph")
+ET.register_namespace("hs", "http://www.hancom.co.kr/hwpml/2011/section")
+ET.register_namespace("hc", "http://www.hancom.co.kr/hwpml/2011/core")
+ET.register_namespace("hh", "http://www.hancom.co.kr/hwpml/2011/head")
+
 _HP_NS = "http://www.hancom.co.kr/hwpml/2011/paragraph"
 _HP = f"{{{_HP_NS}}}"
 _HH_NS = "http://www.hancom.co.kr/hwpml/2011/head"
 _HH = f"{{{_HH_NS}}}"
 
+logger = logging.getLogger(__name__)
+
+
+def _append_element(
+    parent: Any,
+    tag: str,
+    attributes: dict[str, str] | None = None,
+) -> Any:
+    """Create and append a child element that matches *parent*'s element type."""
+
+    child = parent.makeelement(tag, attributes or {})
+    parent.append(child)
+    return child
+
 
 class HwpxDocument:
     """Provides a user-friendly API for editing HWPX documents."""
 
-    def __init__(self, package: HwpxPackage, root: HwpxOxmlDocument):
+    def __init__(
+        self,
+        package: HwpxPackage,
+        root: HwpxOxmlDocument,
+        *,
+        managed_resources: tuple[Any, ...] = (),
+    ):
         self._package = package
         self._root = root
+        self._managed_resources = list(managed_resources)
+        self._closed = False
+
+    def __repr__(self) -> str:
+        """Return a compact and safe summary of the document state."""
+
+        return (
+            f"{self.__class__.__name__}("
+            f"sections={len(self.sections)}, "
+            f"paragraphs={len(self.paragraphs)}, "
+            f"headers={len(self.headers)}, "
+            f"master_pages={len(self.master_pages)}, "
+            f"histories={len(self.histories)}, "
+            f"closed={self._closed}"
+            ")"
+        )
 
     # ------------------------------------------------------------------
     # construction helpers
@@ -54,10 +99,21 @@ class HwpxDocument:
         cls,
         source: str | PathLike[str] | bytes | BinaryIO,
     ) -> "HwpxDocument":
-        """Open *source* and return a :class:`HwpxDocument` instance."""
-        package = HwpxPackage.open(source)
+        """Open *source* and return a :class:`HwpxDocument` instance.
+
+        Raises:
+            HwpxStructureError: 필수 파일이나 구조가 올바르지 않은 HWPX를 열 때 발생합니다.
+            HwpxPackageError: 패키지를 여는 과정에서 일반적인 I/O/포맷 오류가 발생하면 전달됩니다.
+        """
+        internal_resources: list[Any] = []
+        open_source = source
+        if isinstance(source, bytes):
+            stream = io.BytesIO(source)
+            open_source = stream
+            internal_resources.append(stream)
+        package = HwpxPackage.open(open_source)
         root = HwpxOxmlDocument.from_package(package)
-        return cls(package, root)
+        return cls(package, root, managed_resources=tuple(internal_resources))
 
     @classmethod
     def new(cls) -> "HwpxDocument":
@@ -67,10 +123,69 @@ class HwpxDocument:
 
     @classmethod
     def from_package(cls, package: HwpxPackage) -> "HwpxDocument":
-        """Create a document backed by an existing :class:`HwpxPackage`."""
+        """Create a document backed by an existing :class:`HwpxPackage`.
+
+        Args:
+            package: :class:`hwpx.opc.package.HwpxPackage` 인스턴스.
+        """
         root = HwpxOxmlDocument.from_package(package)
         return cls(package, root)
 
+    def __enter__(self) -> "HwpxDocument":
+        """컨텍스트 매니저 진입 시 현재 문서 인스턴스를 반환합니다."""
+
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:
+        """예외 발생 여부와 무관하게 내부 자원을 안전하게 정리합니다."""
+
+        self.close()
+        return False
+
+    def close(self) -> None:
+        """문서가 관리하는 내부 패키지/스트림 자원을 정리합니다.
+
+        정리 정책:
+        - ``flush()`` 가능한 자원은 먼저 flush를 시도합니다.
+        - ``close()`` 가능한 자원은 flush 이후 close를 시도합니다.
+        - flush/close 중 발생한 예외는 로깅하고 무시하여 정리 루틴을 계속 진행합니다.
+        - 같은 문서에서 ``close()``를 여러 번 호출해도 안전합니다.
+        """
+
+        if self._closed:
+            return
+
+        self._flush_resource(self._package)
+        for resource in self._managed_resources:
+            self._flush_resource(resource)
+
+        self._close_resource(self._package)
+        for resource in self._managed_resources:
+            self._close_resource(resource)
+
+        self._managed_resources.clear()
+        self._closed = True
+
+    @staticmethod
+    def _flush_resource(resource: Any) -> None:
+        flush = getattr(resource, "flush", None)
+        if not callable(flush):
+            return
+        try:
+            flush()
+        except Exception:
+            logger.debug("자원 flush 중 예외를 무시합니다: resource=%r", resource, exc_info=True)
+
+    @staticmethod
+    def _close_resource(resource: Any) -> None:
+        close = getattr(resource, "close", None)
+        if not callable(close):
+            return
+        try:
+            close()
+        except Exception:
+            logger.debug("자원 close 중 예외를 무시합니다: resource=%r", resource, exc_info=True)
+
     # ------------------------------------------------------------------
     # properties exposing document content
     @property
@@ -84,22 +199,22 @@ class HwpxDocument:
         return self._root
 
     @property
-    def sections(self) -> List[HwpxOxmlSection]:
+    def sections(self) -> list[HwpxOxmlSection]:
         """Return the sections contained in the document."""
         return self._root.sections
 
     @property
-    def headers(self) -> List[HwpxOxmlHeader]:
+    def headers(self) -> list[HwpxOxmlHeader]:
         """Return the header parts referenced by the document."""
         return self._root.headers
 
     @property
-    def master_pages(self) -> List[HwpxOxmlMasterPage]:
+    def master_pages(self) -> list[HwpxOxmlMasterPage]:
         """Return the master-page parts declared in the manifest."""
         return self._root.master_pages
 
     @property
-    def histories(self) -> List[HwpxOxmlHistory]:
+    def histories(self) -> list[HwpxOxmlHistory]:
         """Return document history parts referenced by the manifest."""
         return self._root.histories
 
@@ -190,10 +305,10 @@ class HwpxDocument:
         return self._root.track_change_author(author_id_ref)
 
     @property
-    def memos(self) -> List[HwpxOxmlMemo]:
+    def memos(self) -> list[HwpxOxmlMemo]:
         """Return all memo entries declared in every section."""
 
-        memos: List[HwpxOxmlMemo] = []
+        memos: list[HwpxOxmlMemo] = []
         for section in self._root.sections:
             memos.extend(section.memos)
         return memos
@@ -270,9 +385,10 @@ class HwpxDocument:
             char_ref = "0"
         char_ref = str(char_ref)
 
-        run_begin = ET.Element(f"{_HP}run", {"charPrIDRef": char_ref})
-        ctrl_begin = ET.SubElement(run_begin, f"{_HP}ctrl")
-        field_begin = ET.SubElement(
+        paragraph_element = paragraph.element
+        run_begin = paragraph_element.makeelement(f"{_HP}run", {"charPrIDRef": char_ref})
+        ctrl_begin = _append_element(run_begin, f"{_HP}ctrl")
+        field_begin = _append_element(
             ctrl_begin,
             f"{_HP}fieldBegin",
             {
@@ -284,14 +400,14 @@ class HwpxDocument:
             },
         )
 
-        parameters = ET.SubElement(field_begin, f"{_HP}parameters", {"count": "5", "name": ""})
-        ET.SubElement(parameters, f"{_HP}stringParam", {"name": "ID"}).text = memo.id or ""
-        ET.SubElement(parameters, f"{_HP}integerParam", {"name": "Number"}).text = str(max(1, number))
-        ET.SubElement(parameters, f"{_HP}stringParam", {"name": "CreateDateTime"}).text = created_value
-        ET.SubElement(parameters, f"{_HP}stringParam", {"name": "Author"}).text = author_value
-        ET.SubElement(parameters, f"{_HP}stringParam", {"name": "MemoShapeID"}).text = memo_shape_id
+        parameters = _append_element(field_begin, f"{_HP}parameters", {"count": "5", "name": ""})
+        _append_element(parameters, f"{_HP}stringParam", {"name": "ID"}).text = memo.id or ""
+        _append_element(parameters, f"{_HP}integerParam", {"name": "Number"}).text = str(max(1, number))
+        _append_element(parameters, f"{_HP}stringParam", {"name": "CreateDateTime"}).text = created_value
+        _append_element(parameters, f"{_HP}stringParam", {"name": "Author"}).text = author_value
+        _append_element(parameters, f"{_HP}stringParam", {"name": "MemoShapeID"}).text = memo_shape_id
 
-        sub_list = ET.SubElement(
+        sub_list = _append_element(
             field_begin,
             f"{_HP}subList",
             {
@@ -301,7 +417,7 @@ class HwpxDocument:
                 "vertAlign": "TOP",
             },
         )
-        sub_para = ET.SubElement(
+        sub_para = _append_element(
             sub_list,
             f"{_HP}p",
             {
@@ -313,12 +429,12 @@ class HwpxDocument:
                 "merged": "0",
             },
         )
-        sub_run = ET.SubElement(sub_para, f"{_HP}run", {"charPrIDRef": char_ref})
-        ET.SubElement(sub_run, f"{_HP}t").text = memo.id or field_value
+        sub_run = _append_element(sub_para, f"{_HP}run", {"charPrIDRef": char_ref})
+        _append_element(sub_run, f"{_HP}t").text = memo.id or field_value
 
-        run_end = ET.Element(f"{_HP}run", {"charPrIDRef": char_ref})
-        ctrl_end = ET.SubElement(run_end, f"{_HP}ctrl")
-        ET.SubElement(ctrl_end, f"{_HP}fieldEnd", {"beginIDRef": field_value, "fieldid": field_value})
+        run_end = paragraph_element.makeelement(f"{_HP}run", {"charPrIDRef": char_ref})
+        ctrl_end = _append_element(run_end, f"{_HP}ctrl")
+        _append_element(ctrl_end, f"{_HP}fieldEnd", {"beginIDRef": field_value, "fieldid": field_value})
 
         paragraph.element.insert(0, run_begin)
         paragraph.element.append(run_end)
@@ -384,7 +500,7 @@ class HwpxDocument:
         return memo, target_paragraph, field_value
 
     @property
-    def paragraphs(self) -> List[HwpxOxmlParagraph]:
+    def paragraphs(self) -> list[HwpxOxmlParagraph]:
         """Return all paragraphs across every section."""
         return self._root.paragraphs
 
@@ -430,10 +546,10 @@ class HwpxDocument:
         underline_type: str | None = None,
         underline_color: str | None = None,
         char_pr_id_ref: str | int | None = None,
-    ) -> List[HwpxOxmlRun]:
+    ) -> list[HwpxOxmlRun]:
         """Return runs matching the requested style criteria."""
 
-        matches: List[HwpxOxmlRun] = []
+        matches: list[HwpxOxmlRun] = []
         target_char = str(char_pr_id_ref).strip() if char_pr_id_ref is not None else None
 
         for run in self.iter_runs():
@@ -712,12 +828,62 @@ class HwpxDocument:
             target_section = self._root.sections[-1]
         target_section.properties.remove_footer(page_type=page_type)
 
+    def save_to_path(self, path: str | PathLike[str]) -> str | PathLike[str]:
+        """Persist pending changes to *path* and return the same path."""
+
+        updates = self._root.serialize()
+        result = self._package.save(path, updates)
+        self._root.reset_dirty()
+        return path if result is None else result
+
+    def save_to_stream(self, stream: BinaryIO) -> BinaryIO:
+        """Persist pending changes to *stream* and return the same stream."""
+
+        updates = self._root.serialize()
+        result = self._package.save(stream, updates)
+        self._root.reset_dirty()
+        return stream if result is None else result
+
+    def to_bytes(self) -> bytes:
+        """Serialize pending changes and return the HWPX archive as bytes."""
+
+        updates = self._root.serialize()
+        result = self._package.save(None, updates)
+        self._root.reset_dirty()
+        if isinstance(result, bytes):
+            return result
+        raise TypeError("package.save(None) must return bytes")
+
+    @overload
+    def save(self, path_or_stream: None = None) -> bytes: ...
+
+    @overload
+    def save(self, path_or_stream: str | PathLike[str]) -> str | PathLike[str]: ...
+
+    @overload
+    def save(self, path_or_stream: BinaryIO) -> BinaryIO: ...
+
     def save(
         self,
         path_or_stream: str | PathLike[str] | BinaryIO | None = None,
-    ) -> str | PathLike[str] | BinaryIO | bytes | None:
-        """Persist pending changes to *path_or_stream* or the original source."""
-        updates = self._root.serialize()
-        result = self._package.save(path_or_stream, updates)
-        self._root.reset_dirty()
-        return result
+    ) -> str | PathLike[str] | BinaryIO | bytes:
+        """Deprecated compatibility wrapper around save_to_path/save_to_stream/to_bytes.
+
+        Deprecated:
+            ``save()``는 하위 호환을 위해 유지되며 향후 제거될 수 있습니다.
+            - 경로 저장: ``save_to_path(path)``
+            - 스트림 저장: ``save_to_stream(stream)``
+            - 바이트 반환: ``to_bytes()``
+        """
+
+        warnings.warn(
+            "HwpxDocument.save()는 deprecated 예정입니다. "
+            "save_to_path()/save_to_stream()/to_bytes() 사용을 권장합니다.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        if path_or_stream is None:
+            return self.to_bytes()
+        if isinstance(path_or_stream, (str, PathLike)):
+            return self.save_to_path(path_or_stream)
+        return self.save_to_stream(path_or_stream)