설치 가이드

이 문서는 PyPI에서 바로 패키지를 설치하는 방법과 저장소를 클론해 개발 환경을 구성하는 방법을 정리합니다. 대부분의 사용자는 PyPI 패키지를 설치한 뒤 제공되는 템플릿(hwpx.templates.blank_document_bytes)으로 바로 실습할 수 있습니다. 저장소에 포함된 예제 HWPX 파일이 필요한 경우에는 깃 클론 후 examples/ 디렉터리를 활용하세요.

요구 사항

• Python 3.10 이상 (프로젝트 테스트는 CPython 3.11 기준)

• pip, venv 모듈이 포함된 표준 Python 배포판

• Git 2.30 이상 (소스 설치 시)

PyPI에서 설치

python -m venv .venv
source .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install python-hwpx

설치 후 다음 명령으로 기본 모듈과 내장 템플릿이 정상 동작하는지 빠르게 확인할 수 있습니다.

python - <<'PY'
from io import BytesIO

from hwpx import HwpxDocument
from hwpx.templates import blank_document_bytes

doc = HwpxDocument.open(BytesIO(blank_document_bytes()))
print("sections:", len(doc.sections))
PY

소스 코드에서 개발용 설치

1. 저장소를 클론합니다.

   git clone <repository-url>
   cd python-hwpx
   

2. 가상 환경을 만들고 활성화합니다.

   python -m venv .venv
   source .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
   python -m pip install --upgrade pip
   

3. 편집 가능한 설치와 개발 도구를 한 번에 구성합니다.

   python -m pip install -e .[dev]
   

pip install -e를 사용하면 추가적인 PYTHONPATH 수정 없이도 hwpx 패키지를 바로 가져올 수 있습니다. 저장소 예제(examples/FormattingShowcase.hwpx)는 개발용 설치를 진행한 경우에만 사용할 수 있습니다.

설치 검증

다음 스니펫을 실행해 핵심 모듈이 정상적으로 로드되는지 확인하세요.

python - <<'PY'
from hwpx import HwpxPackage
print("Package class loaded:", hasattr(HwpxPackage, "open"))
PY

PyPI 패키지에는 예제 HWPX 파일이 포함되지 않으므로, 직접 확보한 문서를 대상으로 테스트하거나 저장소의 examples/ 디렉터리를 사용하세요.

테스트 실행 (선택 사항)

개발 환경을 준비했다면 단위 테스트로 기본 동작을 검증하세요.

python -m pytest

테스트가 모두 통과하면 라이브러리를 사용할 준비가 완료된 것입니다.