Metadata-Version: 2.4
Name: browser_kit
Version: 0.2.0
Summary: 재사용 가능한 안티탐지 브라우저 드라이버 + 라이브 콘솔/응답캡처 + 알림 채널 추상화
Project-URL: Homepage, https://github.com/kokotu0/browser_kit
Project-URL: Repository, https://github.com/kokotu0/browser_kit
Author-email: kokotu0 <kokotu0@gmail.com>
License: MIT
License-File: LICENSE
Keywords: anti-detection,automation,browser,playwright,repl,scraping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: rebrowser-playwright>=1.52.0
Provides-Extra: console
Requires-Dist: ipython>=8.0; extra == 'console'
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21.0; extra == 'telegram'
Description-Content-Type: text/markdown

# browser_kit

재사용 가능한 **안티탐지 브라우저 드라이버 + 인터랙티브 REPL + 알림 채널 추상화**.
특정 사이트/프로젝트에 종속되지 않은, 스크래핑 공통 인프라만 모아둔 패키지다.

## 구성

| 모듈 | 내용 |
|------|------|
| `browser_kit.driver` | rebrowser-playwright 기반 anti-detection 브라우저, 세션(`.userdata`) 유지, `js_repl`/`py_repl` 인터랙티브 셸 |
| `browser_kit.notify` | `Notifier` 채널 추상화(텔레그램 구현 포함) + 인메모리 1:N pub/sub `Broadcaster` |

> 캡차 풀이처럼 **구체적인 로직은 의도적으로 제외**했다. 이 패키지는 "어디서든 재활용 가능한 기반"만 담는다.

## 설치

```bash
# 드라이버만
pip install "git+ssh://git@github.com/<you>/browser_kit.git"

# 텔레그램 알림 채널까지
pip install "git+ssh://git@github.com/<you>/browser_kit.git#egg=browser_kit[telegram]"
```

로컬 개발 시 (uv 프로젝트에서 editable path 의존성):

```toml
# 소비 프로젝트의 pyproject.toml
dependencies = ["browser_kit"]

[tool.uv.sources]
browser_kit = { path = "../browser_kit", editable = true }
```

## 사용

### 드라이버 + REPL

```python
from browser_kit.driver import open_page, js_repl

async with open_page() as page:          # 세션 유지 anti-detection 브라우저
    await page.goto("https://example.com")
    await js_repl(page)                   # js> 프롬프트로 즉석 평가
```

IPython 등 async 터미널:

```python
from browser_kit.driver import start, stop
page = await start("https://example.com")
...
await stop()
```

### 알림 채널 (추상화)

```python
from browser_kit.notify import TelegramNotifier, NullNotifier, Notifier

notifier: Notifier = TelegramNotifier.from_env()   # 토큰 없으면 NullNotifier 로 교체해도 동일 호출
await notifier.send_message("작업 시작")
answer = await notifier.wait_reply(timeout=300)     # 발신 전용 채널이면 None
```

새 채널(메일/문자)을 추가하려면 `Notifier` 를 구현하면 된다 — 호출부는 그대로.

### 이벤트 브로드캐스터 (SSE 등 fan-out)

```python
from browser_kit.notify import Broadcaster

bus = Broadcaster(log_formatter=lambda e: f"[{e['type']}] {e.get('text','')}")
q = bus.subscribe()
bus.publish({"type": "message", "text": "hello"})
```

## 환경변수

| 변수 | 의미 | 기본값 |
|------|------|--------|
| `BROWSER_KIT_USER_DATA_DIR` | 세션(쿠키·캡차 통과) 저장 경로 | `./.userdata` |
| `SCRAPER_HEADLESS` | `1`이면 헤드리스 | (headful) |
| `SCRAPER_BROWSER_CHANNEL` | 브라우저 채널(빈 값=번들 크로미움) | `chrome` |
| `SCRAPER_PROXY_SERVER` / `_USERNAME` / `_PASSWORD` | 프록시 | (미사용) |
| `TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID` | `TelegramNotifier.from_env()` 용 | — |
