Question 1

python-docx가 설치되어 있을 때 DOCX 표가 추출된 텍스트 끝으로 이동하는 문제를 어떻게 해결하나요?

Accepted Answer

이 문제는 파서가 `document.paragraphs`를 먼저 읽고 `document.tables`를 그 다음에 읽으면서 Word 본문에서 두 요소의 교차 순서가 손실될 때 발생합니다. DOCX 순서 수정이 포함된 릴리스로 `book-to-skill`을 업그레이드하세요. 수정된 파서는 일반적으로 `document.iter_inner_content()`를 사용하여 본문 블록을 문서 순서대로 순회하면서 `Paragraph` 및 `Table` 객체가 나타나는 대로 처리합니다. 정렬된 블록 순회를 지원하지 않는 이전 `python-docx` 버전에서는 stdlib ZIP/XML 파서로 폴백합니다. 즉각적인 해결 방법으로, 가상 환경에서 `pip uninstall python-docx`를 실행하여 폴백을 강제하거나 `extract_docx_with_zipfile("document.docx")`를 직접 호출하세요. Chapter 2 앞에 나타나는 표가 `Chapter 2` 제목보다 먼저 추출되는지 확인하세요.

Question 2

CI에서 pytest가 bs4 및 trafilatura에 대해 건너뛴 테스트 5개를 표시하는 문제를 어떻게 수정하나요?

Accepted Answer

테스트는 `pytest.importorskip`을 사용하여 선택적 패키지를 요구하기 때문에 건너뜁니다. 전용 CI 작업에서 테스트 전용 종속성을 설치하세요:

```yaml
optional-deps:
  name: test (optional deps installed)
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-python@v5
      with:
        python-version: "3.12"
    - run: pip install pytest beautifulsoup4 trafilatura
    - run: pytest tests/ -q
```

기존의 종속성 없는 작업은 변경하지 않고 그대로 유지하세요. 로컬에서 확인하려면:

```bash
pip install pytest beautifulsoup4 trafilatura
python3 -m pytest tests/ -q
```

두 패키지를 모두 설치하면 결과가 `698 passed, 5 skipped`에서 `703 passed, 0 skipped`로 바뀝니다. 영향을 받는 테스트는 `tests/test_html_block_boundaries.py`에 있는 `bs4` 게이트 테스트와 `tests/test_html_boilerplate_extraction.py`에 있는 네 개의 `trafilatura` 게이트 테스트입니다.

Question 3

metadata.json에서 각 소스에 대해 chapter_headings_sample이 누락된 이유는 무엇인가요?

Accepted Answer

`book_to_skill/utils.py`의 CLI 메타데이터 프로젝션은 `chapters_detected`와 `chapters_method`를 복사했지만 소스별 `chapter_headings_sample`은 누락했습니다. 통합된 최상위 샘플만 직렬화되었습니다. PR #245, 커밋 `b27360ccfc2f92e0a6571dac03e32389a6e4cfe4`가 포함된 빌드로 업그레이드하세요:

```sh
pip install git+https://github.com/virgiliojr94/book-to-skill.git@b27360ccfc2f92e0a6571dac03e32389a6e4cfe4
```

그런 다음 추출을 다시 실행하세요. 예:

```sh
BOOK_SKILL_WORKDIR="$PWD/repro-output" python3 scripts/extract.py alpha.md beta.md --mode text --install-missing no
```

버전 1.4.0을 로컬에서 패치하는 경우, `extract_single_file()` 출력을 담고 있는 변수를 사용하여 `main()`에서 다른 챕터 필드 옆의 각 소스 객체에 기존 추출 결과를 추가하세요:

```python
"chapter_headings_sample": source.get("chapter_headings_sample", []),
```

샘플을 다시 계산하거나 통합된 최상위 샘플을 할당하지 마세요. 그렇게 하면 첫 번째 소스의 헤딩이 이후 소스에 붙을 수 있습니다. 빈 리스트와 유니코드 헤딩은 그대로 유지되어야 합니다. `pytest -q`와 `ruff check .`로 검증하세요.

Question 4

OPF manifest href에 프래그먼트 또는 퍼센트 인코딩된 파일명이 포함되어 있을 때 stdlib EPUB 폴백이 챕터를 아무 경고 없이 건너뛰는 문제를 해결하는 방법은?

Accepted Answer

PR `fix(epub): resolve encoded manifest hrefs`가 포함된 릴리스로 업그레이드하세요. 이 버그는 커밋 `f08d343`에 존재합니다. 폴백을 패치할 때는 가공되지 않은 OPF `href`를 `ZipFile.read()`에 직접 전달하지 마세요. 먼저 OPF 디렉터리를 기준으로 경로를 해석하고, 쿼리/프래그먼트 구성 요소를 제거한 다음, 퍼센트 이스케이프를 디코딩하세요:

```python
import posixpath
from urllib.parse import urlsplit, unquote

def manifest_member_name(opf_path, href):
    href_path = urlsplit(href).path  # ?query와 #fragment를 제거
    href_path = unquote(href_path)  # Chapter%201.xhtml -> Chapter 1.xhtml
    return posixpath.normpath(posixpath.join(posixpath.dirname(opf_path), href_path))
```

그런 다음 `zf.read(manifest_member_name(opf_path, href))`를 호출하세요. ElementTree와 같은 XML 파서는 속성 값의 XML 엔티티를 이미 디코딩합니다. 따라서 `chapter.xhtml#section-2`는 `chapter.xhtml`로 해석되고, `OEBPS/content.opf`에 있는 `Text/Chapter%201.xhtml`은 `OEBPS/Text/Chapter 1.xhtml`로 해석됩니다.

Question 5

Mongolian FVS, Khmer inherent vowel, Shorthand format controls와 같이 보이지 않는 Unicode Default_Ignorable 문자가 제거되지 않거나 감지되지 않는 문제를 어떻게 해결할 수 있나요?

Accepted Answer

누락된 할당 `Default_Ignorable_Code_Point=Yes` 코드 포인트 전체 집합(`U+17B4`, `U+17B5`, `U+180B`, `U+180C`, `U+180D`, `U+1BCA0`, `U+1BCA1`, `U+1BCA2`, `U+1BCA3`)을 포함하도록 `book_to_skill/sanitize.py::is_invisible_codepoint()`를 패치하세요. 예를 들어, 공유 보이지 않는 코드 포인트 집합에 해당 스칼라 값을 추가하세요: `0x17B4, 0x17B5, 0x180B, 0x180C, 0x180D, 0x1BCA0, 0x1BCA1, 0x1BCA2, 0x1BCA3`. 별도의 스캐너 목록을 유지하지 마세요. `tools/scan_generated_skill.py`는 동일한 프레디케이트를 임포트하므로, 이를 업데이트하면 추출 시 이 문자들이 제거되고 스캐너가 동일한 집합을 일관되게 보고하게 됩니다. 이 문제는 Python 3.9.5와 Unicode 13.0.0 환경에서 확인되었으며, 9개 코드 포인트 모두 이미 해당 버전에 할당되어 있습니다. 패치 후 테스트 스위트를 다시 실행하고 영향을 받는 스킬을 재생성/재스캔하세요.

book-to-skill

개요

README 미리보기

FAQ (5)

同类型项目

hermes-agent

firecrawl

go

markitdown