Metadata-Version: 2.4
Name: googer
Version: 0.7.3
Summary: A powerful, multi-engine search library for Python with DuckDuckGo, Brave Search, Google, Ecosia, Yahoo, AOL, and Naver — featuring concurrent multi-engine mode, suggestions, instant answers, and result caching.
Author: googer contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/googer/googer
Project-URL: Bug Tracker, https://github.com/googer/googer/issues
Keywords: python,search,duckduckgo,brave,google,ecosia,yahoo,aol,naver,web-search,search-engine,multi-engine
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: click>=8.1.8
Requires-Dist: primp>=1.1.0
Requires-Dist: lxml>=4.9.4
Provides-Extra: browser
Requires-Dist: patchright>=1.58.0; extra == "browser"
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: lxml-stubs; extra == "dev"
Dynamic: license-file

# Googer

**A multi-engine search library for Python supporting 7 search engines.**

DuckDuckGo · Brave · Google · Ecosia · Yahoo · AOL · Naver — unified search through a single API.

[한국어 문서 (Korean)](README_KO.md)

## Installation

```bash
pip install googer
```

## Quick Start

```python
from googer import Googer

# Search (default: auto mode — automatic engine selection with fallback)
results = Googer().search("python programming")
for r in results:
    print(r.title, r.href)
```

## Engine Selection

```python
from googer import Googer

# Use a specific engine
g = Googer(engine="brave")
results = g.search("rust language")

# Multi-engine — query multiple engines concurrently and merge results
g = Googer(engine="multi")
results = g.search("machine learning")

# Override engine per method call
g = Googer(engine="duckduckgo")
results = g.search("AI news", engine="naver")  # uses Naver for this call only
```

### Supported Engines

| Engine | Text | Images | News | Videos |
|--------|:----:|:------:|:----:|:------:|
| `duckduckgo` | ✅ | ✅ | ✅ | ✅ |
| `brave` | ✅ | | ✅ | ✅ |
| `google` | ✅ | ✅ | ✅ | ✅ |
| `ecosia` | ✅ | | | |
| `yahoo` | ✅ | | | |
| `aol` | ✅ | | | |
| `naver` | ✅ | | | |

### Engine Modes

| Mode | Description |
|------|-------------|
| `auto` | Default. Tries engines in fallback order, uses the first that succeeds |
| `multi` | Queries multiple engines concurrently, merges and deduplicates results |
| `duckduckgo`, `brave`, ... | Uses only the specified engine |

## Search Types

```python
from googer import Googer

g = Googer()

# Text search
results = g.search("python", region="ko-kr", max_results=20)

# Image search
images = g.images("cute cats", size="large", color="color")
for img in images:
    print(img.title, img.image)

# News search (last 24 hours)
news = g.news("AI", timelimit="d")
for n in news:
    print(n.title, n.source, n.date)

# Video search (short videos only)
videos = g.videos("python tutorial", duration="short")

# Autocomplete suggestions
suggestions = g.suggest("python")

# Instant answer
answer = g.answers("python release date")
```

## Advanced Queries

```python
from googer import Googer, Query

q = (
    Query("machine learning")
    .exact("neural network")
    .site("arxiv.org")
    .filetype("pdf")
    .exclude("tutorial")
)

results = Googer().search(q, max_results=20)
```

## Proxy & Context Manager

```python
from googer import Googer

# With proxy (also supports GOOGER_PROXY env var)
with Googer(proxy="socks5://127.0.0.1:9150") as g:
    results = g.search("privacy tools")

# Tor Browser shorthand
with Googer(proxy="tb") as g:
    results = g.search("onion sites")
```

## All Options

```python
g = Googer(
    engine="auto",          # auto | multi | duckduckgo | brave | google | ecosia | yahoo | aol | naver
    proxy=None,             # Proxy URL (http/https/socks5)
    timeout=10,             # Request timeout in seconds
    max_retries=3,          # Number of retries
    cache_ttl=300,          # Cache TTL in seconds (0 to disable)
    backend="http",         # http | browser
    headless=True,          # Headless mode when using browser backend
    verify=True,            # SSL certificate verification
)
```

## CLI

```bash
# Text search
googer search -q "python programming" -m 5

# Specify engine
googer search -q "news" --engine naver

# Multi-engine search
googer search -q "AI" --engine multi

# News (past week)
googer news -q "AI" -t w

# Images
googer images -q "landscape" --size large

# Videos
googer videos -q "cooking" --duration short

# Suggestions
googer suggest -q "python"

# Save results
googer search -q "python" -o results.json
googer search -q "python" -o results.csv

# With proxy
googer search -q "python" --proxy socks5://127.0.0.1:9150

# Version
googer version
```

### CLI Options

| Option | Short | Description |
|--------|-------|-------------|
| `--query` | `-q` | Search query (required) |
| `--engine` | | Engine selection (default: `auto`) |
| `--region` | `-r` | Region code (default: `us-en`) |
| `--safesearch` | `-s` | `on` / `moderate` / `off` |
| `--timelimit` | `-t` | `h` (hour) `d` (day) `w` (week) `m` (month) `y` (year) |
| `--max-results` | `-m` | Maximum number of results (default: `10`) |
| `--backend` | | `http` / `browser` |
| `--proxy` | | Proxy URL |
| `--timeout` | | Timeout in seconds (default: `10`) |
| `--output` | `-o` | Save to `.json` or `.csv` file |
| `--no-color` | | Disable colored output |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `GOOGER_PROXY` | Default proxy URL |

## Requirements

- Python 3.10+
- [primp](https://github.com/deedy5/primp) — HTTP client with TLS fingerprint impersonation
- [lxml](https://lxml.de/) — HTML parsing
- [click](https://click.palletsprojects.com/) — CLI framework

## License

Apache License 2.0 — [LICENSE.md](LICENSE.md)
