pyproject.toml

[build-system]
requires = ["maturin>=1.7,<2"]
build-backend = "maturin"

[project]
name = "rhwp-python"
description = "PyO3 Python bindings for rhwp — parser and renderer for HWP/HWPX documents (Korean word processor format)"
requires-python = ">=3.10"
license = "MIT"
license-files = ["LICENSE", "external/rhwp/LICENSE"]
readme = "README.md"
authors = [
    { name = "Edward Kim" },
    { name = "DanMeon", email = "jgy5262@naver.com" },
]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Programming Language :: Python",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: Implementation :: CPython",
    "Programming Language :: Rust",
    "Operating System :: POSIX :: Linux",
    "Operating System :: Microsoft :: Windows",
    "Operating System :: MacOS",
    "Typing :: Typed",
    "Natural Language :: Korean",
    "Topic :: Office/Business :: Office Suites",
    "Topic :: Text Processing",
]
keywords = ["hwp", "hwpx", "hancom", "korean", "document", "parser"]
dynamic = ["version"]
# ^ Document IR (v0.2.0+) 은 Pydantic V2 기반 공개 모델 — callable Discriminator 는 2.5+ 도입
dependencies = [
    "pydantic>=2.5,<3",
]

[project.urls]
Homepage = "https://github.com/DanMeon/rhwp-python"
Repository = "https://github.com/DanMeon/rhwp-python"
Issues = "https://github.com/DanMeon/rhwp-python/issues"
Upstream = "https://github.com/edwardkim/rhwp"

[project.optional-dependencies]
# ^ v0.3.0+: text-splitters 는 RAG 사용처에서 거의 항상 동반되므로 [langchain] 에
#   포함하여 [cli,langchain] 조합으로도 chunks 서브커맨드가 작동한다.
langchain = ["langchain-core>=0.2", "langchain-text-splitters>=0.2"]
# ^ v0.3.0 부터 aparse() 가 stdlib asyncio.to_thread 사용 — aiofiles 의존성 제거.
#   `pip install rhwp[async]` 명령 호환을 위해 빈 배열 유지 (v0.4.0 에서 키 자체 제거 검토).
async = []
# ^ rhwp-py CLI (v0.3.0+). chunks 서브커맨드는 별도 [cli-chunks] 또는 [cli,langchain] 조합 필요
cli = ["typer>=0.12"]
# ^ rhwp-py chunks 서브커맨드 — RecursiveCharacterTextSplitter 사용
cli-chunks = [
    "typer>=0.12",
    "langchain-core>=0.2",
    "langchain-text-splitters>=0.2",
]
# ^ examples 는 01~06 예제 스크립트 일괄 실행용 우산 extras — typer + langchain-core +
#   text-splitters + fastmcp (06 MCP 데모) 합집합. v0.5.0+ 는 fastmcp v3 (jlowin) 포함.
examples = [
    "typer>=0.12",
    "langchain-core>=0.2",
    "langchain-text-splitters>=0.2",
    "fastmcp>=3,<4",
]
# ^ rhwp-mcp MCP 서버 (v0.5.0+). standalone fastmcp v3 (jlowin) — 2026-05 기준
#   현업 표준 (MCP 서버 약 70% 사용). 공식 mcp SDK 안의 FastMCP v1 은 frozen 상태고
#   v2/v3 의 OAuth / OpenTelemetry / server composition / streamable-http 우선 같은
#   프로덕션 기능은 standalone 에만 존재. 상세: docs/design/v0.5.0/mcp-research.md § 1.
mcp = ["fastmcp>=3,<4"]
# ^ rhwp-mcp 의 chunks 도구 (v0.5.0 S3 부터). text-splitters 가 추가로 필요.
mcp-chunks = [
    "fastmcp>=3,<4",
    "langchain-core>=0.2",
    "langchain-text-splitters>=0.2",
]

[project.scripts]
# ^ Entry point — typer 미설치 시 rhwp.cli.app() 가 친절 에러 + exit 2.
#   이름은 cli.md § 이름 선정 ("rhwp-py" 채택, 상류 rhwp 와 PATH 충돌 회피)
rhwp-py = "rhwp.cli:app"
# ^ Entry point — mcp 미설치 시 rhwp.mcp.run() 이 친절 에러 + exit 2 (cli 와 동일 패턴).
rhwp-mcp = "rhwp.mcp:run"

[dependency-groups]
dev = ["maturin>=1.7"]
testing = [
    {include-group = "dev"},
    "pytest>=8",
    "pytest-cov",
    "langchain-core>=0.2",
    "langchain-text-splitters>=0.2",
    # ^ JSON Schema meta-validation (tests/test_ir_schema_export.py)
    "jsonschema>=4",
    # ^ rhwp-py CLI smoke / integration tests (tests/test_cli.py)
    "typer>=0.12",
    # ^ rhwp-mcp 서버 단위 테스트 (tests/test_mcp_server.py) — fastmcp 인스턴스 inspection.
    "fastmcp>=3,<4",
    # ^ v0.6.0 PNG 렌더링 회귀 테스트 (tests/test_render_png.py) — dimension 검증 (AC-3).
    #   render_png 자체는 Pillow 무관 (native skia 단독). 본 의존성은 *테스트 측* PNG
    #   디코드용. test-without-extras CI job 에서 미설치되어 file-level skip 발동.
    "pillow>=10",
]
linting = [
    {include-group = "dev"},
    "ruff",
    "pyright",
]
all = [
    {include-group = "dev"},
    {include-group = "testing"},
    {include-group = "linting"},
]

[tool.maturin]
python-source = "python"
module-name = "rhwp._rhwp"
bindings = "pyo3"
# ^ wheel 빌드 시 자기 crate 의 extension-module feature 를 켠다 (Cargo.toml [features] 정의).
#   Cargo.toml 의 default features 에서는 extension-module 이 빠져 있어 cargo test 가 정상 작동.
features = ["extension-module"]
include = [
    { path = "python/rhwp/py.typed", format = "wheel" },
    { path = "python/rhwp/**/*.pyi", format = "wheel" },
    # ^ Document IR v1 JSON Schema — in-package 1차 배포 (ir.md §JSON Schema 공개)
    { path = "python/rhwp/ir/schema/*.json", format = "wheel" },
    { path = "python/rhwp/ir/schema/*.json", format = "sdist" },
]
# ^ path dep vendoring 시 submodule 하위의 개발 아티팩트가 sdist 에 끼어드는 것을 방어
exclude = [
    { path = "**/.venv*/**", format = "sdist" },
    { path = "**/.git/**", format = "sdist" },
    { path = "**/node_modules/**", format = "sdist" },
    { path = "**/__pycache__/**", format = "sdist" },
    { path = "**/target/**", format = "sdist" },
    # ^ external/rhwp/samples ≈ 60 MB 테스트 fixture — sdist 에서 제외해 PyPI 100 MB 한도 준수
    { path = "**/samples/**", format = "sdist" },
]

[tool.pytest.ini_options]
testpaths = ["tests"]
minversion = "8.0"
addopts = ["-ra", "--strict-markers"]
markers = [
    "slow: 느린 테스트 (PDF 렌더링 등)",
    "langchain: LangChain 통합 테스트 (rhwp-python[langchain] extras 필요)",
    # ^ spec(spec_id) — 본 테스트가 검증하는 spec 인수조건 식별자.
    #   형식: 'vX.Y.Z/<topic>#AC-<N>' (CONVENTIONS § Trace report).
    #   v0.4.0+ 신규 spec 부터 적용 — 기존 v0.1.0~v0.3.0 Frozen 은 marker 없음.
    "spec(spec_id): link this test to a spec acceptance criterion (e.g. 'v0.4.0/cli#AC-3')",
]

[tool.pyright]
venvPath = "."
venv = ".venv"
include = ["python", "tests"]
reportMissingImports = true
reportMissingTypeStubs = false

[tool.ruff]
line-length = 100
target-version = "py310"

[tool.ruff.lint]
select = ["E", "F", "W", "I", "UP", "B"]

[tool.ruff.lint.per-file-ignores]
# ^ typer 의 권장 패턴: 함수 default 로 typer.Argument(...) / typer.Option(...) 호출.
#   B008 (function call in default arg) 와 충돌하나 typer 가 의도한 사용처라 ignore.
"python/rhwp/cli/*.py" = ["B008"]
"examples/*.py" = ["B008"]