Skip to content

feat(api): 공개 함수를 패키지 최상위로 재export - #20

Merged
needsbuilder merged 1 commit into
mainfrom
feat/package-level-api
Aug 25, 2026
Merged

feat(api): 공개 함수를 패키지 최상위로 재export#20
needsbuilder merged 1 commit into
mainfrom
feat/package-level-api

Conversation

@needsbuilder

Copy link
Copy Markdown
Owner

문제

README 는 "공개 함수 6개"를 아키텍처의 중심으로 소개하는데, 정작 패키지 최상위에는
아무것도 없었다.

>>> from ttobak import simplify
ImportError: cannot import name 'simplify' from 'ttobak'

서브모듈 경로를 아는 사람만 코어를 가져다 쓸 수 있었고, README 에 import 예제도 없었다.
"복지단체·도서관·개발자·연구자가 확장 가능"하다는 재사용성 주장의 실제 진입로가 비어 있었다.

바꾼 것

다섯 함수(simplify score verify match render_html)를 최상위로 재export 하고
__all__ 을 선언했다. 정본은 각 서브모듈이며 여기서는 이름만 다시 노출한다 —
pipeline 이 monkeypatch 를 위해 score/verify 를 모듈 레벨로 들고 있는 구조는
건드리지 않았다(테스트로 동일성 고정).

parse 는 왜 빠졌나

ttobak.parse서브패키지 이름이기도 하다. 최상위 이름을 함수로 덮자 곧바로
회귀가 났다:

FAILED tests/parse/test_pdf_parser.py::test_parse_pdf_falls_back_to_pdfminer
E   ImportError: cannot import name 'pdf_parser' from 'parse' (unknown location)

하나의 이름이 모듈이면서 함수일 수는 없다. 마감을 앞두고 서브패키지를 리네임하는 것은
파괴적 변경이라 별도 결정 사항으로 두고, parsefrom ttobak.parse import parse
정본으로 유지한다. 이 제약을 테스트로 고정해 두었다 —
test_parse_stays_a_traversable_subpackage 가 앞으로 누가 최상위로 올리면 잡는다.

README 예제는 실제로 돌려봤다

처음 쓴 예제는 실행하면 죽었다:

IndexError: FakeProvider response queue is empty and no default was set

get_provider("fake") 는 기본 응답이 없으면 큐가 비는 즉시 던진다. 예제를 고쳐
default= 를 넘기게 했고, 문서에 실린 코드 그대로 실행해 통과를 확인했다
(verdict: pass).

테스트 수 표기도 417 → 427 로 동기화했다(배지 alt 텍스트 포함 세 곳).

검증

  • pytest -q427 passed (423 + 신규 4)
  • ruff check → clean
  • README 예제 직접 실행 → verdict: pass

README·결과보고서는 parse·simplify·score·verify·match·render_html 을 "공개 함수 6개"
로 소개하는데, ttobak/__init__.py 에는 __version__ 밖에 없어서 `from ttobak import
simplify` 가 ImportError 였다. 서브모듈 경로를 아는 사람만 코어를 가져다 쓸 수 있었고,
README 어디에도 import 예제가 없었다.

parse 만 제외한다. `ttobak.parse` 는 서브패키지 이름이기도 해서 최상위 이름을 함수로
덮으면 `import ttobak.parse.pdf_parser` 가 깨진다(실제로 재export 를 넣자 pdfminer
폴백 테스트가 죽었다). 하나의 이름이 모듈이면서 함수일 수는 없으므로 parse 는 모듈
경로를 정본으로 둔다. 서브패키지 리네임은 파괴적 변경이라 별도 결정 사항이다.

README 에 실제로 실행되는 예제를 넣었다 — get_provider("fake") 는 기본 응답이 없으면
IndexError 라, 예제도 그대로 돌려보고 default 를 넘기도록 고쳤다. 테스트 수 표기도
417 → 427 로 동기화했다(배지 alt 텍스트 포함, 세 곳 모두).
@needsbuilder
needsbuilder merged commit f5210d8 into main Aug 25, 2026
7 checks passed
@needsbuilder
needsbuilder deleted the feat/package-level-api branch August 25, 2026 05:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant