docs(skill): 셀렉터 자가치유 예시의 storage_args 는 .css() 인자가 아니다 — configure() 로 옮기고 kwargs 계약 테스트 추가

[Gforce10-design]

요약

문서의 셀렉터 자가치유 예시 page.css(SEL, auto_save=True, storage_args={...}) 가 이 저장소가 스스로 고정한 scrapling 0.4.x 에서 TypeError 를 낸다. 문서대로 옮겨 적은 crawl_script.py 는 수집 도중 죽는다.

재현 (upstream c64cfbf)

requirements.txt: scrapling[fetchers]>=0.4.8,<0.5   → 설치 0.4.15
Selector.css(selector, identifier='', adaptive=False, auto_save=False, percentage=40)   # storage_args 없음

실측 2026-09-01 books.toscrape.com:

TypeError: Selector.css() got an unexpected keyword argument 'storage_args'

문서 위치: .claude/skills/web-crawler/SKILL.md § 셀렉터 자가 치유, scripts/scrapling_reference.md §7·§8 (+ CLAUDE.md:312 산문).

실제 API (0.4.15 소스)

• storage_args 는 파서를 만드는 쪽 인자 — Selector.__init__(... adaptive, storage, storage_args) (parser.py:93-105)
• 전역: Fetcher.configure(adaptive=True, storage_args={"storage_file": ..., "url": url}) (engines/toolbelt/custom.py:205-227) — 파서 전용 configure 가 바로 이 용도
• 요청별: selector_config={...} (fetchers/requests.py:24-31 에서 configure 값과 병합)
• 생성 시 adaptive=True 가 없으면 css() 의 auto_save/adaptive 는 경고만 남기고 무시된다 (parser.py:176-194)
• url 을 주면 도메인별 버킷 (core/storage.py:24-27); 안 주면 default 하나
• FetcherSession 은 configure() 를 읽지 않는다 — plain_session(selector_config=...) 로 따로 넘겨야 함 (engines/static.py:87,677)
• 경로 미지정 시 기본값은 site-packages 안 scrapling/elements_storage.db (parser.py:47) — venv 지우면 핑거프린트도 사라진다

왜 기존 계약 테스트가 못 잡았나

test_doc_contracts.py 가 코드블록의 import 대상만 실제 모듈과 대조하고 호출 kwargs 는 보지 않았다.

수정

• 문서 3곳을 Fetcher.configure(adaptive=True, storage_args=...) 방식으로. 저장 실패가 수집을 죽이지 않게 try/except 폴백 예시. 세션 주의·기본 경로 주의 추가.
• CLAUDE.md:312 산문 정정.
• test_doc_contracts.py 섹션 4 신설: 문서 python 블록을 ast 로 파싱해 .css() 호출 kwargs 를 inspect.signature(Selector.css) 와 대조. 원본 문서로 돌리면 6건 실패, 수정 후 통과.
• .codex/skills 미러 재생성 (sync_codex_mirror.py --check exit 0).

검증

• pytest -q -k "not e2e" → 425 passed. sync_codex_mirror.py --check / sync_domain_list.py --check exit 0.
• 고쳐진 문서 블록 3개를 네트워크 차단(socket.connect 패치) 상태에서 로컬 HTML 로 그대로 exec — TypeError 없음, 지정 경로에 DB 생성(도메인별 버킷 확인), 셀렉터를 일부러 깨뜨린 HTML(div.item→div.product)에서 adaptive=True 재탐색 성공.
• 인용한 scrapling 소스 파일:라인 전부 실제 파일과 대조.

참고

scripts/scrapling_reference.md 는 기존 DOC_FILES 에 없어 import 검사를 받지 않는다(예: §6 의 AsyncFetcherSession). 이번엔 css-kwargs 검사에만 추가했다. DOC_FILES 편입 여부는 별도 판단.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KoBwBJZ5FyNxkbcX2RpCZT