Metadata-Version: 2.4
Name: dataleaksearch
Version: 1.0.0
Summary: Python SDK & CLI for DataLeak Search — breach intelligence across billions of leaked records
Author-email: ThreatNova Security <contact@threatnovasecurity.com>
License-Expression: MIT
Project-URL: Homepage, https://threatnovasecurity.com/
Project-URL: Documentation, https://dataleaksearch.space-z.ai/
Project-URL: Repository, https://github.com/threatnovasecurity/dataleaksearch-python
Project-URL: Bug Tracker, https://github.com/threatnovasecurity/dataleaksearch-python/issues
Keywords: data-breach,breach-search,credential-leak,osint,security,threatnova,dataleaksearch
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"

# DataLeak Search — Python SDK & CLI

Search billions of leaked records across 1,300+ breach databases from your terminal or Python code.

## Install

```bash
pip install dataleaksearch
```

## CLI Usage

```bash
dataleaksearch
```

Follow the interactive prompts to search by **Email**, **Username**, **Password**, **Domain**, or **Phone**.

## Library Usage

```python
from dataleaksearch import DataLeakSearchClient

# Context manager (auto-closes the session)
with DataLeakSearchClient() as client:
    # Search by email
    result = client.search_email("user@example.com")

    if result.is_breached:
        print(f"Found in {result.total_breaches} breach(es)")
        for breach in result.breaches:
            print(f"  - {breach.name}: {breach.pwn_count:,} records")
    else:
        print("Clean — no breaches found!")

    # Search by password (k-anonymity, NOT stored)
    pw = client.search_password("S3cur3P@ss!")
    if pw.password_hit_count:
        print(f"Password seen {pw.password_hit_count:,} times!")

    # Generic search
    r = client.search("john_doe", "username")
    r = client.search("example.com", "domain")
    r = client.search("+1234567890", "phone")
```

## API

### `DataLeakSearchClient(api_url=None, timeout=30, session=None)`

| Method | Description |
|---|---|
| `search(query, search_type)` | Generic search. `search_type`: `email`, `username`, `password`, `domain`, `phone` |
| `search_email(email)` | Shortcut for email search |
| `search_username(username)` | Shortcut for username search |
| `search_password(password)` | Shortcut for password search (k-anonymity) |
| `search_domain(domain)` | Shortcut for domain search |
| `search_phone(phone)` | Shortcut for phone search |
| `close()` | Close the underlying HTTP session |

### `SearchResult`

| Attribute | Type | Description |
|---|---|---|
| `query` | `str` | The search query |
| `search_type` | `str` | Type of search performed |
| `scanned_databases` | `int` | Number of databases scanned |
| `total_breaches` | `int` | Number of breaches found |
| `breaches` | `list[Breach]` | List of breach records |
| `checked_at` | `datetime \| None` | When the check was performed |
| `password_hit_count` | `int \| None` | (Password only) Times the password appeared |
| `elapsed_ms` | `int` | API response time in milliseconds |
| `is_breached` | `bool` | `True` if any breaches found |

### Exceptions

| Exception | Parent | When |
|---|---|---|
| `DataLeakSearchError` | `Exception` | Base for all client errors |
| `TimeoutError` | `DataLeakSearchError` | Request timed out |
| `ConnectionError` | `DataLeakSearchError` | Cannot reach the server |
| `HTTPError` | `DataLeakSearchError` | Non-2xx response (has `.status_code`) |

## License

MIT — ThreatNova Security
