Scrapling 입문: 자가 적응 셀렉터로 깨지지 않는 파이썬 크롤러 만들기

"BeautifulSoup으로 잘 돌던 크롤러가 사이트 디자인 한 번 바뀌었다고 셀렉터 수십 개를 다 갈아엎어야 한다면?"

📌 핵심 3줄 요약

• Scrapling은 사이트 구조가 바뀌어도 셀렉터를 자동 보정하는 auto_match 옵션이 핵심인 파이썬 적응형 스크래핑 프레임워크다.
• 일반 HTTP용 Fetcher, 안티봇 우회용 StealthyFetcher(Camoufox 기반), 풀브라우저용 PlayWrightFetcher를 한 API에서 사용한다.
• MIT 라이선스, Python 3.9+ 호환이며 단발 요청부터 비동기 풀스케일 크롤링까지 한 라이브러리로 처리한다.

1. Scrapling이 BeautifulSoup·Scrapy와 다른 이유

기존 파이썬 크롤러의 가장 큰 비용은 유지보수다. 사이트가 클래스명을 한 번만 바꿔도 soup.select(".price-tag") 같은 셀렉터가 전부 깨진다. Scrapling은 페이지 구조 지문을 학습해 두었다가 셀렉터가 안 맞을 때 가장 비슷한 노드를 자동으로 다시 찾아 준다. BeautifulSoup·Scrapy로 같은 동작을 만들려면 별도 복구 로직이 필요하다.

2. 설치와 환경 준비

Python 3.9 이상이면 pip 한 줄로 끝난다. 안티봇 우회까지 쓰려면 Camoufox(Playwright 호환 Firefox 포크) 다운로드가 추가로 필요하다.

# 기본 설치
pip install scrapling

# StealthyFetcher 의존성(Camoufox) — 약 200MB
python -m scrapling install

Windows에서 첫 실행 시 Defender가 Camoufox 바이너리를 잠시 검사하는 화면이 나오는데, 정식 빌드라 신뢰 추가 후 진행하면 된다. 가상환경(venv·uv) 사용을 권장한다.

3. Fetcher 3종 사용법

일반 HTTP는 Fetcher, Cloudflare·DataDome 같은 안티봇은 StealthyFetcher, JS 렌더링이 필수면 PlayWrightFetcher로 분기한다.

from scrapling.fetchers import Fetcher, StealthyFetcher, PlayWrightFetcher

# 1) 빠른 HTTP 요청
page = Fetcher.get("https://quotes.toscrape.com/", stealthy_headers=True)

# 2) Cloudflare 우회
page = StealthyFetcher.fetch(
    "https://example.com",
    headless=True,
    network_idle=True,
    humanize=True,
)

# 3) JS 렌더링이 필수인 페이지
page = PlayWrightFetcher.fetch("https://example.com", real_chrome=True)

print(page.status, len(page.html_content))

4. 셀렉터 4종과 자가 적응(auto_match)

한 객체에서 CSS·XPath·텍스트·정규식을 모두 쓰고, auto_match=True를 켜면 다음 실행에서 셀렉터가 깨졌을 때 자동 보정된다.

# CSS + auto_match
quotes = page.css(".quote", auto_match=True)
for q in quotes:
    text = q.css_first(".text::text").clean()
    author = q.css_first("small.author::text").clean()
    print(author, "—", text)

# XPath, 텍스트, 정규식
title = page.xpath_first("//h1/text()")
links = page.find_by_text("Next", first_match=False)
emails = page.find_by_regex(r"[\w\.-]+@[\w\.-]+")

첫 실행에서 노드의 위치·텍스트·속성 패턴이 로컬 캐시에 기록된다. 이후 클래스명이 바뀌어도 가장 유사한 노드를 다시 찾아 반환하므로 셀렉터 패치 빈도가 줄어든다.

5. BeautifulSoup·Scrapy·Playwright와의 비교

항목	Scrapling	BeautifulSoup	Scrapy	Playwright
자가 적응 셀렉터	기본 내장	없음	없음	없음
안티봇 우회	StealthyFetcher 내장	별도 구현	미들웨어 추가	stealth 플러그인
JS 렌더링	PlayWrightFetcher	불가	scrapy-playwright	기본 지원
학습 곡선	낮음	매우 낮음	높음	중간
적합 시나리오	유지보수형 크롤러	단발성 파싱	대규모 분산	테스트·인터랙션

⚠️ 단점과 주의할 점

• StealthyFetcher 의존성이 무겁다 — Camoufox 바이너리만 200MB 안팎이라 컨테이너 이미지가 커지고 콜드스타트가 느리다.
• auto_match도 만능은 아니다. DOM이 통째로 재설계되거나 SPA 라우팅이 바뀌면 결국 셀렉터를 다시 짜야 한다.
• 안티봇 우회가 합법성을 보장하지 않는다. robots.txt 준수, 이용약관 확인, rate limit 강제가 기본이고, 한국에서는 정보통신망법·저작권법·개인정보보호법 위반 위험을 함께 점검해야 한다.
• 신생 프로젝트라 한국어 자료가 적다. 트러블슈팅은 GitHub Issues 검색이 빠르다.

🚀 지금 바로 할 일

1. 가상환경 만들고 pip install scrapling 후 python -m scrapling install로 Camoufox까지 받기.
2. quotes.toscrape.com 같은 연습용 사이트에서 Fetcher.get()·page.css(..., auto_match=True) 동작 확인하기.
3. 실서비스 적용 전 robots.txt·이용약관·rate limit·로깅·에러 알림 항목을 체크리스트로 정리해 운영 가이드 문서화하기.

💬 의견

운영 중인 크롤러가 사이트 개편으로 자주 깨졌던 사례가 있다면 댓글 부탁드립니다. 다음 글은 Scrapling으로 비동기 풀스케일 크롤러를 구성하는 패턴을 다룰 예정입니다.

함께 보면 좋은 글

• MCP 시작 가이드 — 외부 API·DB 연동을 Plugins(MCP) 쪽에서 풀고 싶을 때 함께 보면 Skills와의 역할 분담이 분명해진다.
• Cursor 시작 가이드 — 같은 워크플로를 다른 에디터에서 어떻게 만드는지 비교해 보고 싶다면.
• Claude Projects vs Custom GPTs — 컨텍스트 주입 방식이 제품마다 어떻게 다른지 큰 그림을 잡는 데 도움이 된다.
• OpenAI Agents SDK 튜토리얼 — 같은 "에이전트 + 도구" 개념을 OpenAI 쪽에서는 어떻게 표현하는지 대조해 볼 수 있다.

참고 자료

• Scrapling 공식 GitHub 저장소 — D4Vinci/Scrapling
• Scrapling 공식 문서 (ReadTheDocs) — Fetcher·셀렉터·auto_match API 레퍼런스
• PyPI 패키지 페이지 — 버전·의존성·설치 메타데이터
• Camoufox 프로젝트 — StealthyFetcher가 사용하는 Firefox 포크

---

작성자: 데이터 파이프라인 엔지니어

파이썬으로 데이터 수집 파이프라인을 다년간 운영하며 BeautifulSoup·Scrapy·Playwright를 모두 거쳐 왔습니다. 본 글은 Scrapling 공식 README, ReadTheDocs 문서, PyPI 페이지를 교차 검증해 작성했으며, 코드 예제는 공식 예제와 동일한 시그니처를 사용했습니다.