프로젝트 소개

web-core는 Python을 위한 공유 웹 인프라 패키지로, wet-mcp MCP 서버 및 기타 다운스트림 애플리케이션의 기반이 되는 것으로 설명됩니다. 이 패키지는 타입이 지정된 공개 API 뒤에 여러 웹 대면 기능을 묶어 제공하며, README에 따르면 사이트별 셀렉터는 의도적으로 소비자 애플리케이션의 몫으로 남겨두었습니다. 패키지 자체는 일반적인 인프라만 제공하며, 도메인별 쿠키와 셀렉터는 환경 변수를 통해 공급됩니다. README에 나열된 주요 기능은 다음과 같습니다: - SearXNG 검색: 파일 락(file-lock) 기반의 교차 프로세스 싱글톤 러너(모든 Python 프로세스에서 단일 인스턴스 보장)와 재시도, 결과 중복 제거 및 도메인 필터링을 수행하는 클라이언트를 제공합니다. - 다중 전략 스크래핑: 전략 간 에스컬레이션을 수행하는 LangGraph 상태 머신 에이전트입니다. 포함된 전략 모듈에는 API 직접 페칭, 기본 HTTP, curl-cffi를 통한 TLS 핑거프린트 스푸핑, Crawl4AI를 통한 헤드리스 렌더링, Patchright 스텔스 브라우저 렌더링, RenderClient를 통한 원격 렌더링, CapSolver 기반의 CAPTCHA 전략이 포함됩니다. 전략은 캐시 권장 순서대로 시도되며, 응답이 검증되고 실패 시 자동으로 에스컬레이션됩니다(예: 렌더링이 부족한 JavaScript 셸을 렌더 백엔드로 전달). StrategyCache가 도메인별 성능을 추적합니다. - SSRF 안전 HTTP 클라이언트: DNS 핀닝이 적용된 httpx 클라이언트, URL 정규화, 추적 파라미터 제거 및 도메인 검증 헬퍼를 제공합니다. 모든 아웃바운드 HTTP는 DNS 리바인딩을 방지하기 위해 safe_httpx_client를 통해 전달되도록 설계되었습니다. - 브라우저 및 원격 렌더링: BrowserProvider 프로토콜과 Patchright(undetected Playwright) 제공자, 자체 호스팅 /content 엔드포인트용 BrowserlessClient, 그리고 JavaScript 렌더링을 오프로드하는 슬림 컨테이너를 위한 Cloudflare Browser Rendering 클라이언트를 제공합니다. - robots.txt 준수: 페칭 전 도메인별 캐시 확인을 수행합니다. - LLM 셀렉터 추론(옵션): 내장 셀렉터가 실패할 경우, 존재하는 API 키(Google Gemini, OpenAI, Anthropic, xAI)에 따라 제공자를 자동 감지합니다. 키가 설정되지 않은 경우 추론은 조용히 건너뜁니다. 커스텀 llm_caller를 주입할 수도 있으며, Gemini는 project/location 변수를 통해 Vertex AI로 라우팅될 수 있습니다. - 외부 API 어댑터: Google Drive 폴더/파일 페칭 및 MangaDex(만화, 챕터, 이미지)를 위한 타입 지정된 SSRF 안전 클라이언트를 제공합니다. 설치는 PyPI에서 n24q02m-web-core(uv add)로 가능하며, v2.x 안정 버전을 유지합니다. 설정은 전적으로 환경 변수로 구동되며 모든 변수는 선택 사항입니다. 변수를 생략하면 해당 기능이 비활성화되며, 패키지를 임포트하거나 사용하는 데 필수적인 변수는 없습니다. 문서화된 변수에는 SearXNG URL 및 실행 사용자, 스크래핑을 위한 도메인별 쿠키(JSON), 셀렉터 추론을 위한 LLM 제공자 키 및 모델 오버라이드가 포함됩니다. 원격 렌더 자격 증명은 생성자 인수로 전달됩니다. 아키텍처는 src/web_core 아래에 계층형 모듈로 구성되어 있습니다: http(SSRF 안전 프리미티브, URL 유틸리티), search(클라이언트, 모델, 러너), scraper(에이전트, 기본 전략, 캐시, robots, 셀렉터 추론, 상태, 유틸리티 및 전략 서브패키지), browsers(프로토콜, patchright, browserless, cf_rendering), adapters(google_drive, mangadex). 이 패키지는 PEP 561 타이핑을 위한 py.typed 마커를 포함합니다. 주요 설계 결정 사항으로는 SSRF 보호를 위한 DNS 핀닝, 자동 전략 에스컬레이션, 교차 프로세스 SearXNG 싱글톤, 그리고 브라우저 및 렌더 구현체가 기본 클래스를 상속받을 필요가 없도록 Protocol 기반의 구조적 타이핑을 사용한 점 등이 있습니다. 개발 환경은 Python 3.13과 uv를 타겟으로 하며, 선택적 mise 작업 단축키, pre-commit 훅, 린팅/포맷팅을 위한 ruff, 타입 체크를 위한 ty, 그리고 커버리지를 포함한 pytest를 사용합니다. 테스트 스위트는 95%의 커버리지 임계값을 강제하며 asyncio_mode auto를 사용합니다. 테스트 파일은 소스 모듈 구조를 그대로 반영합니다. 프로젝트는 Apache-2.0 라이선스로 배포됩니다.