Metadata-Version: 2.4
Name: thepiratebay-api
Version: 0.1.0b1
Summary: An Unofficial API wrapper for the pirate bay
Project-URL: Homepage, https://github.com/9BitDaniel/thepiratebay-api
Project-URL: Repository, https://github.com/9BitDaniel/thepiratebay-api
Project-URL: Documentation, https://github.com/9BitDaniel/thepiratebay-api/blob/main/README.md
Project-URL: BugTracker, https://github.com/9BitDaniel/thepiratebay-api/issues
Author-email: Danial Zahedi <Da.36512021@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Daniel
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: api-wrapper,httpx,piratebay,pydantic,scraper,thepiratebay,thepiratebay-api,torrent,tpb
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.15.0
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: lxml>=6.1.1
Requires-Dist: pydantic>=2.13.4
Description-Content-Type: text/markdown

# thepiratebay-api

An unofficial Python API wrapper for The Pirate Bay.

>**Beta** — Please [open an issue](https://github.com/9BitDaniel/thepiratebay-api/issues) if something breaks.

## Installation

```bash
pip install thepiratebay-api
```
```bash
uv add thepiratebay-api
```

Or directly from GitHub:

```bash
pip install git+https://github.com/9BitDaniel/thepiratebay-api.git
```
```bash
uv add https://github.com/9BitDaniel/thepiratebay-api.git
```

## Quick Start

```python
from thepiratebay_api import TorrentClient

with TorrentClient() as client:
    results = client.search("ubuntu")

    for torrent in results.torrents:
        print(torrent.title, torrent.seeders)
```

## Usage

### Search

```python
# Basic search
results = client.search("ubuntu")

# With category
results = client.search("interstellar", category=TorrentClient.Category.Video.HD_MOVIES)

# With pagination
results = client.search("ubuntu", page=2)

print(f"Page {results.current_page} of {results.page_count}")
```

### Categories

```python
TorrentClient.Category.ALL

TorrentClient.Category.Audio.MUSIC
TorrentClient.Category.Audio.FLAC
TorrentClient.Category.Audio.AUDIOBOOKS

TorrentClient.Category.Video.MOVIES
TorrentClient.Category.Video.TV_SHOWS
TorrentClient.Category.Video.HD_MOVIES
TorrentClient.Category.Video.HD_TV_SHOW
TorrentClient.Category.Video.UHD_MOVIES

TorrentClient.Category.Games.PC
TorrentClient.Category.Apps.WIN
TorrentClient.Category.Other.EBOOKS
```

### Torrent Details

```python
# Pass a torrent ID from search results
details = client.detail(torrent.torrent_id)

print(details.title)
print(details.size)
print(details.seeders)
print(details.magnet_link)
print(details.info_hash)
print(details.num_files)
print(details.uploader)
print(details.is_vip)
print(details.is_trusted)
print(details.description)
print(details.images)         # image URLs found in the description
print(details.additional_info) # extra metadata like tags, language, etc.
```

### Browse & Discover

```python
# Browse a category (category has to be specified)
results = client.browse(TorrentClient.Category.Video.HD_MOVIES)

# Top torrents in a category (category has to be specified)
results = client.top(TorrentClient.Category.Audio.MUSIC)

# Recently uploaded torrents
results = client.recent()
results = client.recent(page=2)
```

### Mirror Sites

If the default URL is blocked or unreachable:

```python
mirrors = client.mirrors()
alive = mirrors.alive  # only working mirrors

if alive:
    client = TorrentClient(url=alive[0].url)
```

### Custom HTTP Options

Any keyword argument is passed directly to `httpx.Client`:

```python
# Custom timeout
client = TorrentClient(timeout=30)

# Custom headers
client = TorrentClient(headers={"User-Agent": "Mozilla/5.0"})

# Through a proxy
client = TorrentClient(proxy="http://localhost:8080")

# Custom mirror as base URL
client = TorrentClient(url="https://tpb.party")
```

## Requirements

- Python 3.10+
- httpx
- beautifulsoup4
- lxml
- pydantic

## License

MIT