Metadata-Version: 2.4
Name: thepiratebay-api
Version: 0.1.0
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 :: 5 - Production/Stable
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

[![codecov](https://codecov.io/github/9BitDaniel/thepiratebay-api/graph/badge.svg?token=ZEHPPXOGP6)](https://github.com/9BitDaniel/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's not working.

## 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 git+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("Tenet", category=TorrentClient.Category.Video.HD_MOVIES)

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

# With custom sorting
results = client.search(
    "ubuntu", 
    sort_by=TorrentClient.SortBy.SEEDERS_DESC
)

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

## Working with Results

All results are [Pydantic](https://docs.pydantic.dev) models, so you can serialize them however you need:

```python
results = client.search("Bomber Mafia")

# Convert to dict
results.model_dump()

# Convert to JSON string
results.model_dump_json()

# Individual torrent
torrent = results.torrents[0]
torrent.model_dump()
torrent.model_dump_json()

# Full torrent details
details = client.detail(torrent.torrent_id)
details.model_dump()
details.model_dump_json()
```


### Categories
You could use all the major categories found in The Pirate Bay along with some of the sub 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 that differ across torrents
```

### 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="socks5://localhost:1080")

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

## Requirements

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

## Contributing

Contributions are welcome

## Support the Project ⭐

If you found this API wrapper useful, please consider giving this repository a **Star**

## License

This project is licensed under the [MIT License](LICENSE).
