wxpath - XPath를 사용한 선언적 웹 그래프 탐색

새로운 기능: TUI - wxpath 표현식을 테스트하고 데이터를 내보내기 위한 대화형 터미널 인터페이스(Textual 기반).

Wxpath TUI 데모 스크린샷

설치

Python 3.10+ 필요.

pip install wxpath
# TUI 지원을 위해:
pip install "wxpath[tui]"
# uv를 통해 TUI 즉시 실행:
uvx --from "wxpath[tui]" wxpath-tui

wxpath란?

wxpath는 탐색을 XPath로 직접 표현하는 선언형 웹 크롤러입니다. 명령형 크롤링 루프를 작성하는 대신, wxpath는 하나의 표현식에서 무엇을 따라갈지, 무엇을 추출할지 설명할 수 있습니다. wxpath는 해당 표현식을 동시에, 너비 우선(ish)으로 실행하고, 결과가 발견되는 대로 스트리밍합니다.

이 표현식은 페이지를 가져오고, 링크를 추출하며, 동시에 스트리밍합니다. 크롤링 루프가 필요 없습니다:

import wxpath

expr = "url('https://quotes.toscrape.com')//a/@href"

for link in wxpath.wxpath_async_blocking_iter(expr):
    print(link)

url(...) 연산자와 /// 구문을 도입함으로써 wxpath 엔진은 재귀적(또는 페이지네이션된) 웹 크롤링 및 추출을 수행할 수 있습니다:

import wxpath

path_expr = """
url('https://quotes.toscrape.com')
  ///url(//a/@href)
    //a/@href
"""

for item in wxpath.wxpath_async_blocking_iter(path_expr, max_depth=1):
    print(item)

왜 wxpath인가?

대부분의 웹 스크래퍼는 먼저 크롤링 제어 흐름을 작성하고, 그 다음 추출을 작성하도록 강제합니다.

wxpath는 이 두 단계를 하나로 통합합니다:

탐색을 선언적으로 설명합니다
추출을 인라인으로 표현합니다
엔진이 스케줄링, 동시성, 중복 제거를 처리합니다

RAG 준비 출력

그래프에서 깨끗하고 구조화된 JSON 계층을 직접 추출하세요. LLM에 신호를 공급하고 노이즈는 걸러냅니다. 자세한 내용은 LangChain 통합을 참조하세요.

결정론적

wxpath는 결정론적입니다(참고: LLM 기반이 아님). 네트워크가 안정적이라고 보장할 수는 없지만, 탐색이 결정론적임은 보장할 수 있습니다.

문서 (작업 중)

문서는 현재 여기에서 확인할 수 있습니다.

예제: 지식 그래프
언어 설계
url(...) 및 ///url(...) 설명
일반적인 흐름
비동기 크롤링
정중한 크롤링
출력 유형
XPath 3.1
진행 표시줄
CLI
TUI
영속성 및 캐싱
설정
훅 (실험적)
설치
더 많은 예제
비교
고급: 엔진 및 크롤러 구성
프로젝트 철학
경고
상업적 지원/컨설팅
버전 관리
라이선스

예제

import wxpath
from wxpath.settings import CRAWLER_SETTINGS

# 예의를 위한 사용자 정의 헤더; 일부 사이트(예: Wikipedia)에 필요함
CRAWLER_SETTINGS.headers = {'User-Agent': 'my-app/0.4.0 (contact: [email protected])'}

# 크롤링, 필드 추출, 지식 그래프 구축
path_expr = """
url('https://en.wikipedia.org/wiki/Expression_language')
  ///url(
        //main//a/@href[
            starts-with(., '/wiki/') and not(contains(., ':'))
        ]
    )
    /map{
        'title': (//span[contains(@class, "mw-page-title-main")]/text())[1] ! string(.),
        'url': string(base-uri(.)),
        'short_description': //div[contains(@class, 'shortdescription')]/text() ! string(.),
        'forward_links': //div[@id="mw-content-text"]//a/@href ! string(.)
    }
"""

for item in wxpath.wxpath_async_blocking_iter(path_expr, max_depth=1):
    print(item)

참고: 일부 사이트(Wikipedia 포함)는 적절한 헤더가 없으면 요청을 차단할 수 있습니다.
사용자 정의 User-Agent 설정은 고급: 엔진 및 크롤러 구성을 참조하세요.

위 표현식은 다음을 수행합니다:

지정된 URL https://en.wikipedia.org/wiki/Expression_language에서 시작합니다.
<main> 섹션의 링크 중 /wiki/로 시작하고 콜론(:)을 포함하지 않는 링크를 필터링합니다.
각 링크에 대해,
- 링크를 따라가 페이지의 제목, URL, 짧은 설명을 추출합니다.
- 최대 깊이에 도달할 때까지 2단계를 반복합니다.
발견되는 대로 추출된 데이터를 스트리밍합니다.

`url(...)` 및 `///url(...)` 설명

url(...)은 사용자가 지정하거나 내부적으로 생성된 URL의 콘텐츠를 가져와서 추가 XPath 처리를 위해 lxml.html.HtmlElement로 반환하는 사용자 정의 연산자입니다.
///url(...)은 심층 크롤링을 나타냅니다. 런타임 엔진에게 지정된 max_depth까지 링크를 계속 따라가라고 지시합니다. 반복적인 url() 홉과 달리, 단일 표현식으로 더 깊은 그래프 탐색을 설명할 수 있습니다. 경고: 크롤링 폭발을 방지하기 위해 제약 조건(max_depth 또는 XPath 조건자)을 사용하여 주의해서 사용하세요.

언어 설계

언어 설계에 대한 자세한 내용은 DESIGN.md를 참조하세요. 핵심 개념과 언어를 처음부터 설계하는 과정을 확인할 수 있습니다.

일반적인 흐름

wxpath는 표현식을 일련의 탐색 및 추출 단계(내부적으로 Segment라고 함)로 평가합니다.

url(...)은 정적 URL(고정된 URL) 또는 동적 URL(XPath 표현식에서 파생된 URL)을 통해 크롤링 작업을 생성합니다. URL은 깊이가 아닌 최선의 방식으로 전역적으로 중복 제거됩니다.

XPath 세그먼트는 바로 앞의 url(...) 작업을 통해 가져온 문서에서 작동합니다.

///url(...)은 심층 크롤링을 나타냅니다. 너비 우선(ish) 방식으로 max_depth까지 진행합니다.

결과는 준비되는 대로 생성됩니다.

비동기 크롤링

wxpath는 asyncio/aiohttp 우선으로, 크롤링 및 데이터 추출을 위한 비동기 API를 제공합니다.

import asyncio
from wxpath import wxpath_async

items = []

async def main():
    path_expr = "url('https://en.wikipedia.org/wiki/Expression_language')///url(//@href[starts-with(., '/wiki/')])//a/@href"
    async for item in wxpath_async(path_expr, max_depth=1):
        items.append(item)

asyncio.run(main())

차단형 동시 요청

wxpath는 또한 asyncio-in-sync API를 제공하므로, 동기 코드의 단순성을 유지하면서 여러 페이지를 동시에 크롤링할 수 있습니다. 이는 엄격하게 동기 실행 환경(asyncio 이벤트 루프 외부)에서 성능이 중요할 때 특히 유용합니다.

from wxpath import wxpath_async_blocking_iter

path_expr = "url('https://en.wikipedia.org/wiki/Expression_language')///url(//@href[starts-with(., '/wiki/')])//a/@href"
items = list(wxpath_async_blocking_iter(path_expr, max_depth=1))

정중한 크롤링

wxpath는 기본적으로 WXPathEngine(..., robotstxt=True) 생성자를 통해 robots.txt를 준수합니다.

출력 유형

wxpath Python API는 구조화된 객체를 생성합니다.

표현식에 따라 결과에는 다음이 포함될 수 있습니다:

lxml.* 및 lxml.html.* 객체
elementpath.datatypes.* 객체 (XPath 3.1 기능용)
WxStr (출처가 포함된 문자열 값)
사전 / 맵
리스트 또는 기타 XPath 네이티브 값

CLI는 이러한 객체를 표시를 위해 일반 JSON으로 평탄화합니다. Python API는 기본적으로 구조를 유지합니다.

기본 XPath 3.1

wxpath는 elementpath 라이브러리를 사용하여 XPath 3.1을 지원하므로, 맵, 배열 등 고급 XPath 기능을 사용할 수 있습니다. 이를 통해 더 강력한 XPath 쿼리를 작성할 수 있습니다.

path_expr = """
    url('https://en.wikipedia.org/wiki/Expression_language')
    ///url(//div[@id='mw-content-text']//a/@href)
    /map{ 
        'title':(//span[contains(@class, "mw-page-title-main")]/text())[1], 
        'short_description':(//div[contains(@class, "shortdescription")]/text())[1],
        'url'://link[@rel='canonical']/@href[1]
    }
"""
# [...
# {'title': 'Computer language',
# 'short_description': 'Formal language for communicating with a computer',
# 'url': 'https://en.wikipedia.org/wiki/Computer_language'},
# {'title': 'Machine-readable medium and data',
# 'short_description': 'Medium capable of storing data in a format readable by a machine',
# 'url': 'https://en.wikipedia.org/wiki/Machine-readable_medium_and_data'},
# {'title': 'Domain knowledge',
# 'short_description': 'Specialist knowledge within a specific field',
# 'url': 'https://en.wikipedia.org/wiki/Domain_knowledge'},
# ...]

진행 표시줄

wxpath는 크롤링 진행 상황을 추적하기 위해 진행 표시줄(tqdm 사용)을 제공합니다. 장기 실행 크롤링에 특히 유용합니다.

engine.run(..., progress=True)로 설정하거나, wxpath_async*(...) 함수에 progress=True를 전달하여 활성화합니다.

items = wxpath.wxpath_async_blocking("...", progress=True)
> 100%|██████████████████████████████████████████████████████████▎| 469/471 [00:05<00:00, 72.00it/s, depth=2, yielded=457]

CLI

wxpath는 명령줄 인터페이스(CLI)를 제공하여 터미널에서 직접 wxpath 표현식을 빠르게 실험하고 실행할 수 있습니다.

다음 예제는 Wikipedia의 "Expression language" 페이지에서 시작하여 다른 위키 페이지로의 링크를 추출하고, 각 연결된 페이지에서 특정 필드를 검색하는 방법을 보여줍니다.

참고: 웹 콘텐츠의 특성상 출력은 시간이 지남에 따라 달라질 수 있습니다.

> wxpath --depth 1 \
    --header "User-Agent: my-app/0.1 (contact: [email protected])" \
    "url('https://en.wikipedia.org/wiki/Expression_language') \
    ///url(//div[@id='mw-content-text']//a/@href[starts-with(., '/wiki/') \
        and not(matches(@href, '^(?:/wiki/)?(?:Wikipedia|File|Template|Special|Template_talk|Help):'))]) \
    /map{ \
        'title':(//span[contains(@class, 'mw-page-title-main')]/text())[1], \
        'short_description':(//div[contains(@class, 'shortdescription')]/text())[1], \
        'url':string(base-uri(.)), \
        'backlink':wx:backlink(.), \
        'depth':wx:depth(.) \
        }"

{"title": "Computer language", "short_description": "Formal language for communicating with a computer", "url": "https://en.wikipedia.org/wiki/Computer_language", "backlink": "https://en.wikipedia.org/wiki/Expression_language", "depth": 1.0}
{"title": "Machine-readable medium and data", "short_description": "Medium capable of storing data in a format readable by a machine", "url": "https://en.wikipedia.org/wiki/Machine_readable", "backlink": "https://en.wikipedia.org/wiki/Expression_language", "depth": 1.0}
{"title": "Domain knowledge", "short_description": "Specialist knowledge within a specific field", "url": "https://en.wikipedia.org/wiki/Domain_knowledge", "backlink": "https://en.wikipedia.org/wiki/Expression_language", "depth": 1.0}
{"title": "Advanced Boolean Expression Language", "short_description": "Hardware description language and software", "url": "https://en.wikipedia.org/wiki/Advanced_Boolean_Expression_Language", "backlink": "https://en.wikipedia.org/wiki/Expression_language", "depth": 1.0}
{"title": "Data Analysis Expressions", "short_description": "Formula and data query language", "url": "https://en.wikipedia.org/wiki/Data_Analysis_Expressions", "backlink": "https://en.wikipedia.org/wiki/Expression_language", "depth": 1.0}
{"title": "Jakarta Expression Language", "short_description": "Computer programming language", "url": "https://en.wikipedia.org/wiki/Jakarta_Expression_Language", "backlink": "https://en.wikipedia.org/wiki/Expression_language", "depth": 1.0}
{"title": "Rights Expression Language", "short_description": [], "url": "https://en.wikipedia.org/wiki/Rights_Expression_Language", "backlink": "https://en.wikipedia.org/wiki/Expression_language", "depth": 1.0}
{"title": "Computer science", "short_description": "Study of computation", "url": "https://en.wikipedia.org/wiki/Computer_science", "backlink": "https://en.wikipedia.org/wiki/Expression_language", "depth": 1.0}

명령줄 옵션:

--depth                <depth>       최대 크롤링 깊이
--verbose              [true|false]  기본적인 CLI 정보 제공
--debug                [true|false]  상세한 런타임 출력 및 정보 제공
--concurrency          <concurrency> 동시 가져오기 수
--concurrency-per-host <concurrency> 호스트당 동시 가져오기 수
--header               "Key:Value"   사용자 정의 헤더 추가 (예: 'Key:Value'). 여러 번 사용 가능.
--respect-robots       [true|false] (기본값: True) robots.txt 준수
--cache                [true|false] (기본값: False) 크롤링 결과를 로컬 데이터베이스에 저장

TUI

wxpath는 대화형 표현식 테스트 및 데이터 추출을 위한 터미널 인터페이스(TUI)를 제공합니다.

자세한 내용은 TUI 빠른 시작을 참조하세요.

영속성 및 캐싱

wxpath는 크롤링 결과를 선택적으로 로컬 데이터베이스에 저장합니다. 이는 많은 수의 URL을 크롤링할 때 특히 유용합니다. 크롤링을 일시 중지하고, 추출 표현식을 변경하거나, 다시 시작해야 하는 경우에 사용할 수 있습니다.

wxpath는 sqlite와 redis 두 가지 백엔드를 지원합니다. SQLite는 단일 작업자(즉, engine.crawler.concurrency == 1)로 소규모 크롤링에 적합합니다. Redis는 여러 작업자로 대규모 크롤링을 수행할 때 좋습니다. sqlite 백엔드를 사용할 때 min(engine.crawler.concurrency, engine.crawler.per_host) > 1이면 경고가 발생합니다.

사용하려면 적절한 선택적 종속성을 설치해야 합니다:

pip install wxpath[cache-sqlite]
pip install wxpath[cache-redis]

종속성을 설치한 후 캐시를 활성화해야 합니다:

from wxpath.settings import SETTINGS

# 캐싱 활성화; 기본값은 sqlite
SETTINGS.http.client.cache.enabled = True

# redis 백엔드의 경우
SETTINGS.http.client.cache.enabled = True
SETTINGS.http.client.cache.backend = "redis"
SETTINGS.http.client.cache.redis.address = "redis://localhost:6379/0"

# 평소처럼 wxpath 실행
items = list(wxpath_async_blocking_iter('...', max_depth=1, engine=engine))

설정

설정에 대한 자세한 내용은 settings.py를 참조하세요.

훅 (실험적)

wxpath는 크롤링 및 추출 동작을 수정할 수 있는 플러그 가능한 훅 시스템을 지원합니다. URL 전처리, HTML 후처리, 추출 값 필터링 등을 위한 훅을 등록할 수 있습니다. 훅은 등록된 순서대로 실행됩니다. 훅은 성능에 영향을 줄 수 있습니다.


from wxpath import hooks

@hooks.register
class OnlyEnglish:
    def post_parse(self, ctx, elem):
        lang = elem.xpath('string(/html/@lang)').lower()[:2]
        return elem if lang in ("en", "") else None

비동기 사용법

참고: 훅은 동기 또는 비동기일 수 있지만, 프로젝트의 모든 훅은 동일한 스타일을 따라야 합니다. 동기와 비동기 훅을 혼합하는 것은 지원되지 않으며 예기치 않은 동작을 유발할 수 있습니다.


from wxpath import hooks

@hooks.register
class OnlyEnglish:
    async def post_parse(self, ctx, elem):
        lang = elem.xpath('string(/html/@lang)').lower()[:2]
        return elem if lang in ("en", "") else None

사전 정의된 훅

JSONLWriter (NDJSONWriter로도 알려짐)는 추출된 데이터를 개행으로 구분된 JSON 파일에 기록하는 내장 훅입니다. 이는 나중에 쉽게 처리할 수 있는 구조화된 형식으로 결과를 저장하는 데 유용합니다.

from wxpath import hooks
hooks.register(hooks.JSONLWriter)

설치

Python 3.10+ 필요.

pip install wxpath

영속화/캐싱을 위해 wxpath는 다음 백엔드를 지원합니다:

pip install wxpath[cache-sqlite]
pip install wxpath[cache-redis]

더 많은 예제

더 많은 사용 예제는 EXAMPLES.md를 참조하세요.

비교

다른 웹 스크래핑 도구와의 비교는 COMPARISONS.md를 참조하세요.

고급: 엔진 및 크롤러 구성

다음과 같이 엔진과 크롤러의 동작을 변경할 수 있습니다:

from wxpath import wxpath_async_blocking_iter
from wxpath.core.runtime import WXPathEngine
from wxpath.http.client.crawler import Crawler

crawler = Crawler(
    concurrency=8,
    per_host=2,
    timeout=10,
    respect_robots=False,
    headers={
        "User-Agent": "my-app/0.1.0 (contact: [email protected])", # Wikipedia 같은 사이트에서 좋아할 것
    },
)

# `crawler`를 지정하지 않으면 제공된 concurrency, per_host, respect_robots 값 또는 기본값으로 기본 Crawler가 생성됩니다.
engine = WXPathEngine(
    # concurrency: int = 16, 
    # per_host: int = 8,
    # respect_robots: bool = True,
    # allowed_response_codes: set[int] = {200},
    # allow_redirects: bool = True,
    crawler=crawler,
)

path_expr = "url('https://en.wikipedia.org/wiki/Expression_language')//url(//main//a/@href)"

items = list(wxpath_async_blocking_iter(path_expr, max_depth=1, engine=engine))

런타임 API (`wxpath_async*`) 옵션

max_depth: int = 1
progress: bool = False
engine: WXPathEngine | None = None
yield_errors: bool = False

설정

settings.py를 사용하여 캐싱, 스로틀링, 동시성 등을 활성화할 수도 있습니다.

프로젝트 철학

원칙

번거로움 없이 선언적인 크롤링 및 스크래핑을 가능하게 함
가볍고 조합 가능하게 유지
고성능 크롤링을 위한 비동기 지원

목표

URL은 크롤링별로 최선의 방식으로 중복 제거됩니다.
크롤링은 프론티어가 소진되거나 max_depth에 도달하면 종료됩니다.
요청은 동시에 수행됩니다.
결과는 사용 가능해지는 즉시 스트리밍됩니다.

현재 제한 사항

다음 기능은 아직 지원되지 않습니다:

자동 프록시 순환
브라우저 기반 렌더링 (JavaScript 실행)
엄격한 결과 순서

경고!!!

이 프로젝트는 초기 개발 단계에 있습니다. 핵심 개념은 안정적이지만 API와 기능은 변경될 수 있습니다. 문제(특히 교착 상태 크롤링 또는 예상치 못한 동작)와 보고 싶은 기능이 있으면 알려주십시오(구현을 보장하지는 않습니다).

웹사이트를 크롤링할 때는 예의를 지키십시오. scrapy에서 영감을 받은 스로틀러가 기본적으로 활성화되어 있습니다.
심층 크롤링(///)은 무한 확장(크롤링 폭발)을 방지하기 위해 사용자의 규율이 필요합니다.
특정 상황(예: 모든 작업이 차단된 요청을 기다리는 경우)에서 교착 상태 및 중단이 발생할 수 있습니다. 이러한 동작이 발생하면 문제를 보고해 주십시오.
시간 제한, max_depth 및 XPath 조건자와 필터를 사용하여 크롤링 범위를 제한하는 것을 고려하십시오.

상업적 지원/컨설팅

wxpath를 사용하여 크롤러/데이터 피드를 구축하거나 운영(추출, 스케줄링, 모니터링, 중단 수정)하거나 기타 웹 스크래핑 요구 사항에 대한 도움이 필요하면 다음 주소로 연락해 주십시오: [email protected].

기부

wxpath가 마음에 들고 개발을 지원하고 싶다면 기부를 고려해 주십시오.

버전 관리

wxpath는 semver를 따릅니다: <MAJOR>.<MINOR>.<PATCH>.

단, 1.0.0 미만은 0.<MAJOR>.<MINOR|PATCH>를 따릅니다.

라이선스

AGPL-3.0

wxpath

인기