D4Vinci/Scrapling — 웹사이트가 바뀌어도
알아서 살아남는 적응형 스크래핑 프레임워크

52.2k 스타·5k 포크의 Python 웹 스크래핑 신예. CSS 셀렉터가 어제 잘 되다가 오늘 깨졌을 때, adaptive=True 한 줄로 유사도 알고리즘이 변경된 요소를 자동으로 다시 찾아준다. Cloudflare Turnstile/Interstitial을 그냥 통과하고, BS4보다 ~1679배 빠른 lxml 기반 파서, Scrapy 스타일 Spider, 내장 MCP 서버까지 한 라이브러리에 묶었다.

1한 줄 요약

3가지 Fetcher(HTTP / Stealthy / Dynamic)와 Scrapy 스타일 Spider 프레임워크, 그리고 내장 MCP 서버까지 갖춰서 한 라이브러리로 단발 스크래퍼부터 풀스케일 크롤러, AI 에이전트 도구까지 커버한다. Karim Shoair가 2024년부터 단독 메인테이너로 끌어왔고, 2026년 6월 기준 v0.4.9까지 47번 릴리즈했다.

2왜 지금 주목받는가

1) "셀렉터가 깨지는 지옥"을 코드 한 줄로 해결

웹 스크래퍼를 운영해본 사람이라면 알고 있다 — 사이트가 디자인을 한번 바꾸면 그날부터 셀렉터가 우수수 깨진다. CSS 클래스명만 바뀌어도 다 다시 짜야 한다.

Scrapling은 첫 매칭 때 auto_save=True로 요소 정보를 저장하고, 다음 실행 때 adaptive=True를 켜면 알아서 비슷한 요소를 다시 찾는다. 유지보수 비용을 거의 0으로 만드는 발상이다.

products = p.css('.product', auto_save=True)   # 1차 실행: 요소 지문 저장
# ... 며칠 후 사이트 구조 변경 ...
products = p.css('.product', adaptive=True)    # 2차 실행: 자동 재탐색

2) Cloudflare Turnstile/Interstitial 즉시 우회

대부분의 상업 사이트는 Cloudflare·DataDome·PerimeterX 같은 봇 차단 시스템 뒤에 있다. requests나 일반 Playwright로는 첫 페이지부터 막힌다.

Scrapling의 StealthyFetcher는 Patchright(스텔스 Playwright 포크) + browserforge(브라우저 지문 위조) + Apify 지문 데이터셋을 결합해서 Cloudflare Turnstile을 solve_cloudflare=True 한 줄로 통과한다.

3) BS4보다 ~1679배 빠른 파서

벤치마크 결과(5000개 중첩 요소 텍스트 추출, 100회 평균):

JSON 직렬화도 orjson 사용으로 표준 라이브러리 대비 10배 빠르다.

4) AI 에이전트와의 자연스러운 통합 — MCP 서버 내장

pip install "scrapling[ai]" 한 줄이면 Model Context Protocol(MCP) 서버가 함께 설치된다. Claude/Cursor 같은 AI 코딩 도구에 등록하면, AI가 직접 사이트를 긁어와서 파싱한 결과만 받는다.

핵심 가치: AI에게 HTML 1MB를 통째로 보내는 게 아니라, Scrapling이 먼저 셀렉터로 잘라낸 깔끔한 데이터만 전달해서 토큰 비용을 대폭 줄인다. Anthropic 공식 에이전트 스킬(agent-skill/ 폴더), OpenClaw Skill도 번들로 제공.

5) Scrapy의 학습 곡선 없이 풀크롤러를 짤 수 있다

Scrapy는 강력하지만 프로젝트 구조·미들웨어·파이프라인·설정 파일이 복잡하다. Scrapling Spider는 한 파일에 Spider 클래스 하나만 정의하면 끝. 동시성·throttling·robots.txt 준수·pause/resume·스트리밍을 다 내장.

3기술 스택 전체 지도

파서/코어 (필수 의존성)

Fetchers (선택 — pip install "scrapling[fetchers]")

AI/Shell (선택)

인프라 / 빌드

• Python 3.10+ (3.10, 3.11, 3.12, 3.13 테스트)
• uv — Astral의 Rust 기반 Python 패키지 매니저. Dockerfile에서 사용해 빌드 캐시 효율 극대화.
• Docker — python:3.12-slim-trixie 베이스 + Playwright Chromium + 모든 extras 자동 빌드. GHCR과 DockerHub 동시 배포.
• setuptools 빌드 시스템 + ruff(린트) + pyright/mypy(타입 검사) + pytest + bandit(보안) + tox(멀티 Python 테스트).
• Read the Docs 호스팅(.readthedocs.yaml). Zensical 문서 빌더(zensical.toml).
• BSD-3-Clause 라이선스 — 상업적 활용 자유.

릴리즈 자동화

• GitHub Actions가 매 릴리즈마다 PyPI 배포 + Docker 이미지 빌드 + Playwright 브라우저 번들 + GHCR 푸시까지 한 번에.
• MCP 서버 등록: server.json에 PyPI(uvx)와 OCI(Docker) 양쪽 배포 방식 명세 → MCP 레지스트리에서 자동 인덱싱.

4아키텍처 심화 분석 — 적응형 파서 + 3종 Fetcher

전체 시스템 구조도

핵심 설계 패턴 1 — Smart Element Tracking (적응형 요소 추적)

Scrapling을 다른 스크래퍼와 결정적으로 차별화하는 부분이다. 셀렉터를 처음 실행할 때 auto_save=True를 주면, 매칭된 요소의 "프로파일"이 디스크에 저장된다.

저장되는 정보:

• 태그 이름 (div, a 등)
• 속성 집합 (class, id, data-*, href, src 등의 키-값)
• 텍스트 내용 (직접 텍스트 + 자식 텍스트)
• 위치 컨텍스트 (부모/형제/자식 태그 패턴)
• 구조적 신호 (DOM 트리에서의 깊이, 형제 인덱스 등)

다음 실행에서 adaptive=True를 주면, Scrapling은 이렇게 동작한다:

1. 먼저 원래 셀렉터로 시도한다.
2. 요소를 못 찾거나, 찾았는데 저장된 프로파일과 너무 다르면 → 유사도 매칭 모드 진입.
3. 저장된 프로파일과 현재 DOM의 모든 요소를 비교해, 유사도 점수가 가장 높은 후보를 반환.

핵심 설계 패턴 2 — 3종 Fetcher의 점진적 강화 (Progressive Stealth)

같은 인터페이스로 점점 강한 위장을 선택할 수 있다.

같은 fetch() API로 3종을 바꿔낄 수 있어서, "먼저 빠른 Fetcher로 시도하다 차단되면 StealthyFetcher로 폴백" 같은 전략이 한 파일에 깔끔하게 들어간다.

핵심 설계 패턴 3 — 멀티 세션 라우팅 (Spider 내부)

Scrapy에는 없는 Scrapling만의 패턴. 한 Spider 안에서 URL 유형에 따라 다른 세션으로 라우팅한다.

class MultiSessionSpider(Spider):
    def configure_sessions(self, manager):
        manager.add("fast",    FetcherSession(impersonate="chrome"))
        manager.add("stealth", AsyncStealthySession(headless=True), lazy=True)

    async def parse(self, response):
        for link in response.css('a::attr(href)').getall():
            if "protected" in link:
                yield Request(link, sid="stealth")   # 보호 페이지 → 스텔스
            else:
                yield Request(link, sid="fast")      # 일반 페이지 → 빠른 HTTP

lazy=True: 무거운 브라우저 세션은 처음 요청이 들어왔을 때만 spin-up. 보호 페이지가 없는 도메인이면 브라우저는 아예 안 뜬다.

핵심 설계 패턴 4 — Checkpoint 기반 Pause & Resume

Scrapy의 JOBDIR과 비슷하지만 더 단순한 API. crawldir="./crawl_data"를 주면:

• 큐(대기 URL), 방문 완료 URL 집합, 부분 결과를 디스크에 주기적으로 직렬화
• Ctrl+C 시 graceful shutdown — 현재 처리 중인 요청까지 마무리하고 상태 저장
• 같은 crawldir로 재시작하면 멈춘 시점부터 재개

장시간 크롤(수일~수주)에 필수. 서버 재부팅·네트워크 단절·디버깅 중단에 강하다.

핵심 설계 패턴 5 — Development Mode (응답 캐싱)

parse() 로직을 고치면서 매번 실제 서버에 요청 보내면 차단 위험 + 느림. Dev 모드는 첫 실행 응답을 디스크에 캐시했다가 이후 실행에선 캐시를 사용. Scrapy의 HTTPCACHE_ENABLED를 기본 워크플로로 승격한 것.

핵심 설계 패턴 6 — Streaming Mode

async for item in spider.stream():
    # 결과가 도착하는 순서대로 즉시 받음 (전체 크롤 끝나기 전에)
    await pipeline.send(item)

UI/대시보드/실시간 인덱싱 파이프라인에 결과를 흘려보낼 때 사용. 일반 모드는 크롤 끝나야 결과 모음을 반환하지만, 스트리밍 모드는 도착하는 대로 yield.

5디렉토리 구조 해부

중요도별 읽는 순서

1. scrapling/__init__.py — 공개 API 한 페이지로 보기 (가장 먼저 읽을 것)
2. scrapling/parser.py — 적응형 매칭 알고리즘. 58KB 단일 파일에 핵심 로직이 다 들어있다. 코드 리딩에서 가장 보람 있는 부분.
3. scrapling/fetchers/ + engines/ — 3종 Fetcher가 어떻게 동일 인터페이스를 유지하는지
4. scrapling/spiders/ — Spider/SessionManager/Checkpoint 구현
5. benchmarks.py — "왜 빠른가"를 수치로 보기
6. Dockerfile — uv 캐시 마운트 패턴 학습 (실무에 바로 적용 가능한 베스트 프랙티스)

6학습 포인트 (기술별)

1) lxml의 진짜 활용법

lxml은 빠르지만 API가 투박하다. Scrapling은 lxml을 베이스로 깔고 BS4 스타일·Parsel 스타일·CSS pseudo-element까지 같이 노출한다. parser.py를 읽으면:

• lxml의 etree·HTMLParser·XPath를 어떻게 래핑하는지
• CSS 셀렉터를 XPath로 변환하는 cssselect 활용법
• ::text, ::attr(href) 같은 pseudo-element를 어떻게 직접 구현했는지

실습: lxml로 직접 작은 셀렉터를 짜본 뒤, Scrapling이 어떻게 그 위에 추상화를 얹는지 비교.

2) TLS 지문 위조 & curl_cffi

일반 requests로 막히던 사이트가 curl_cffi.get(url, impersonate="chrome") 한 줄로 통과되는 마법. 이게 어떻게 가능한지 추적해보면 네트워크 보안 지식이 풍부해진다.

• JA3/JA4 지문이 무엇인지 (Wireshark로 직접 캡처해보기)
• curl-impersonate가 BoringSSL 패치로 어떻게 Chrome TLS 스택을 흉내내는지
• HTTP/3 (QUIC)가 봇 차단을 어떻게 회피하는지

실습: 같은 사이트에 requests·httpx·curl_cffi로 각각 요청 보내고 응답 차이 관찰.

3) Playwright 스텔스 모드

Playwright는 강력하지만 navigator.webdriver=true 같은 자동화 시그널이 그대로 남는다. patchright는 어떤 시그널을 어떻게 패치하는지 코드로 학습할 수 있다.

• browserforge가 생성하는 헤더/지문의 일관성 검증법
• Cloudflare Turnstile의 동작 원리와 우회 방식
• 실제 사용자 마우스 움직임 시뮬레이션 패턴

4) Scrapy의 핵심 패턴을 미니멀하게 다시 짠 케이스 스터디

Scrapy를 다 공부하기엔 부담이지만, Spider/Request/Response/Pipeline의 본질은 scrapling/spiders/를 읽으면 1~2시간이면 잡힌다. 동시성 제어·throttling·재시도 로직이 어떻게 구현되는지가 그대로 노출.

5) asyncio + anyio 동시성 패턴

비동기 컨텍스트 매니저(async with), 세션 풀, 타임아웃 처리, asyncio.gather 사용 패턴. "비동기 코드를 동기 컨텍스트에서도 쓸 수 있게 만드는" FetcherSession의 듀얼 인터페이스 구현이 특히 볼만하다.

6) MCP 서버 구현

scrapling[ai]의 MCP 서버 코드는 "기존 Python 라이브러리에 MCP 인터페이스 얹는 법"의 표준 예제. 도구 명세·파라미터·반환 타입을 어떻게 정의하는지, stdio transport와 HTTP transport(EXPOSE 8000) 양쪽을 어떻게 지원하는지 학습.

7) uv + Docker 베스트 프랙티스

Dockerfile의 캐시 마운트 패턴은 그대로 가져다 다른 Python 프로젝트에 적용 가능:

RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --no-install-project --all-extras --compile-bytecode
COPY . .
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --all-extras --compile-bytecode

의존성을 먼저 설치하고(레이어 캐시), 그 다음에 소스 복사. 코드만 바뀌면 의존성 설치 단계는 캐시 hit.

8) Python 패키징의 모범 답안

pyproject.toml에 optional-dependencies 트리(fetchers → ai/shell → all)를 어떻게 구성했는지, classifiers·MyPy·Pyright 설정·zip-safe 플래그까지 — 그대로 베껴서 자기 프로젝트에 적용 가능한 템플릿이다.

7시스템 요구사항 & 라이선스

최소 요구사항

• Python 3.10 이상 (3.10, 3.11, 3.12, 3.13 공식 지원)
• OS: Linux/macOS/Windows 모두 동작. 다만 Playwright 브라우저 의존성 때문에 Linux가 가장 부드러움
• 디스크: 코어만 ~5MB. scrapling install로 Chromium까지 받으면 ~500MB
• 네트워크: 첫 설치 시 PyPI + Playwright CDN 접근 필요

설치 단계

# 1) 코어만 (파서만 필요할 때)
pip install scrapling

# 2) Fetcher까지 (HTTP 요청·브라우저 자동화 포함)
pip install "scrapling[fetchers]"
scrapling install         # Playwright 브라우저 + 시스템 의존성

# 3) 전부 (AI/MCP + 인터랙티브 셸 + Fetcher)
pip install "scrapling[all]"
scrapling install

# 4) Docker
docker pull pyd4vinci/scrapling
# 또는
docker pull ghcr.io/d4vinci/scrapling:latest

라이선스 — BSD-3-Clause

• 상업적 사용 ✓
• 수정 ✓
• 배포 ✓
• 사적 사용 ✓
• 조건: 저작권 표시 보존, 저자 이름을 광고용 보증으로 쓰지 말 것
• 면책: 보증 없음

8직접 해볼 수 있는 실습 과제

★ 기초 — Hello, Scrapling (30분)

★★ 중급 — 적응형 스크래핑 직접 검증 (1~2시간)

★★★ 중상급 — Stealth 모드로 Cloudflare 통과 (2~3시간)

★★★★ 상급 — 풀크롤러 + Pause/Resume (반나절)

★★★★★ 고급 — MCP 서버를 Claude/Cursor에 연결 (반나절)

9관련 기술 심화 학습 로드맵

1주차 — HTML 파싱의 기본기

• lxml 직접 사용: etree.HTML()·XPath·iterparse까지. Scrapling을 빼고 lxml만으로 같은 작업 짜보기.
• CSS 셀렉터 vs XPath: 각자 강점, ::text·::attr·contains()·following-sibling 익히기.
• BS4와의 차이: BS4의 find·find_all·CSS 셀렉터 지원, 그리고 왜 BS4가 1000배 느린지.
• 실습: 위키피디아에서 특정 표만 추출해 CSV로.

2주차 — HTTP 클라이언트와 TLS 위장

• requests → httpx → curl_cffi 단계별 차이
• JA3/JA4 지문이 뭔지 (Wireshark 캡처해보기, ja3er.com 같은 진단 사이트)
• HTTP/1.1 vs HTTP/2 vs HTTP/3(QUIC)의 봇 탐지 영향
• 실제 Chrome의 헤더 순서 재현 — impersonate="chrome"이 뒤에서 뭘 하는지

3주차 — 브라우저 자동화와 스텔스

• Playwright 기본기: page.goto·page.waitForSelector·page.evaluate
• 탐지 시그널 6종: navigator.webdriver·플러그인·언어·시간대·WebGL·캔버스 지문
• Patchright/Stealth 플러그인이 각각을 어떻게 패치하는지 코드로 확인
• Cloudflare Turnstile vs reCAPTCHA v2/v3 vs hCaptcha 동작 차이

4주차 — Spider/크롤러 아키텍처

• Scrapy의 핵심 컴포넌트(Engine·Downloader·Scheduler·Pipeline) 한 번 훑기
• Scrapling Spider 코드(scrapling/spiders/)와 비교 → "Scrapy의 본질을 어떻게 80% 코드로 잡아냈나"
• 동시성 제어: 세마포어·rate limiter·exponential backoff
• 체크포인트 직렬화 — 디스크 fsync 시점, 충돌 안전성
• 분산 크롤링 옵션: Redis 큐, Kafka, Celery와의 결합 (Scrapling 자체엔 없지만)

5주차 — AI 에이전트 통합 (MCP)

• MCP 명세 읽기 (modelcontextprotocol.io)
• Scrapling MCP 서버 코드 분석 — 도구 이름·파라미터·반환 스키마
• "AI에 1MB HTML을 통째로 보내지 않고 셀렉터로 자른 결과만 보내는" 토큰 절감 패턴
• Claude Code Agent Skill(agent-skill/) — SKILL.md로 자기 도메인의 스크래핑 노하우를 캡슐화
• 실전 통합: LangChain Tool/CrewAI Tool로 Scrapling 래핑

10핵심 키워드 사전

11참고 링크

공식

• GitHub 레포: github.com/D4Vinci/Scrapling
• 공식 문서(Read the Docs): scrapling.readthedocs.io
• MCP 서버 문서: scrapling.readthedocs.io/ai/mcp-server
• PyPI: pypi.org/project/scrapling
• Docker Hub: docker pull pyd4vinci/scrapling
• GHCR: docker pull ghcr.io/d4vinci/scrapling:latest
• Discord 커뮤니티: discord.gg/EMgGbDceNQ
• X(Twitter): @Scrapling_dev
• TrendShift 페이지: trendshift.io/repositories/14244

한국어 문서

• README 한글판: docs/README_KR.md

핵심 의존성 학습 자료

• lxml 공식: lxml.de
• cssselect: cssselect.readthedocs.io
• curl_cffi: github.com/lexiforest/curl_cffi
• Playwright Python: playwright.dev/python
• Patchright: github.com/Kaliiiiiiiiii-Vinyzu/patchright
• browserforge: github.com/daijro/browserforge
• orjson: github.com/ijl/orjson
• uv (Astral): docs.astral.sh/uv
• Model Context Protocol: modelcontextprotocol.io

비교 학습 자료

• Scrapy 공식 튜토리얼: docs.scrapy.org/intro/tutorial
• Parsel 문서: parsel.readthedocs.io
• BeautifulSoup vs lxml 비교 분석들
• The Web Scraping Club의 Scrapling 리뷰(Nov 2025): substack.thewebscraping.club/p/scrapling-hands-on-guide

봇 탐지 / 우회 학습

• JA3 지문 진단: ja3er.com
• 봇 탐지 시그널 모음: bot.sannysoft.com
• Cloudflare Turnstile 공식 설명: cloudflare.com/products/turnstile