# torrfetch
**torrfetch** is a Python package that lets you search torrents across multiple public torrent indexers with deduplication and relevance sorting. Designed for developers building CLI tools or automation scripts around torrent discovery.
## Features
- Search multiple torrent providers in parallel or fallback mode
- Automatic deduplication of results
- Smart scoring by title relevance and seeders
- Fast and extensible provider interface
## Providers
Currently supports:
- The Pirate Bay
- yts
## Installation
```bash
pip install torrfetch
```
## Usage
### Parallel mode (default)
All providers are queried simultaneously, and the output is ranked by relevance and seeders
```python
torrfetch.search_torrents("oppenheimer 2023 1080p", mode="parallel")
```
### Fallback mode
Queries providers one by one, proceeding to the next if the current one is down or returns no results
```python
torrfetch.search_torrents("oppenheimer", mode="fallback")
```
### Restrict to specific providers
Use `only` to limit the search to a subset of sources (e.g., just YTS or YTS and Piratebay):
```python
torrfetch.search_torrents("oppenheimer", only=["yts"])
```
## Sample data returned
The first 30 results are returned, sorted by a combination of relevance and seeders:
```
[
{
"title": "Interstellar (2014)",
"magnet": "magnet:?xt=urn:btih:...",
"size": "2.2 GB",
"uploaded": "2020-10-01",
"uploader": "YTS",
"category": "Movies",
"seeders": 2145,
"leechers": 198,
"source": "yts"
},
{
"title": "Interstellar.2014.1080p.BluRay.x264",
"magnet": "magnet:?xt=urn:btih:...",
"size": "3.1 GB",
"uploaded": "2019-07-12",
"uploader": "1337xUploader",
"category": "Movies",
"seeders": 1200,
"leechers": 230,
"source": "1337x"
},
...
]
```
Raw data
{
"_id": null,
"home_page": null,
"name": "torrfetch",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "torrent, scraper, metadata, torrent indexer, torrent scraper",
"author": null,
"author_email": "Aayush Kumar <aayush214.kumar@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ba/cc/836b1ed9ecf73a6fc91abd4489f8488394bd538d5d80b5a79af207eebe87/torrfetch-0.1.4.tar.gz",
"platform": null,
"description": "# torrfetch\n\n**torrfetch** is a Python package that lets you search torrents across multiple public torrent indexers with deduplication and relevance sorting. Designed for developers building CLI tools or automation scripts around torrent discovery.\n\n## Features\n\n- Search multiple torrent providers in parallel or fallback mode \n- Automatic deduplication of results \n- Smart scoring by title relevance and seeders \n- Fast and extensible provider interface \n\n## Providers\n\nCurrently supports:\n- The Pirate Bay\n- yts\n\n## Installation\n\n```bash\npip install torrfetch\n```\n\n## Usage\n\n### Parallel mode (default)\nAll providers are queried simultaneously, and the output is ranked by relevance and seeders\n```python\ntorrfetch.search_torrents(\"oppenheimer 2023 1080p\", mode=\"parallel\")\n```\n\n### Fallback mode\nQueries providers one by one, proceeding to the next if the current one is down or returns no results\n```python\ntorrfetch.search_torrents(\"oppenheimer\", mode=\"fallback\")\n```\n\n### Restrict to specific providers\nUse `only` to limit the search to a subset of sources (e.g., just YTS or YTS and Piratebay):\n```python\ntorrfetch.search_torrents(\"oppenheimer\", only=[\"yts\"])\n```\n\n## Sample data returned\nThe first 30 results are returned, sorted by a combination of relevance and seeders:\n```\n[\n {\n \"title\": \"Interstellar (2014)\",\n \"magnet\": \"magnet:?xt=urn:btih:...\",\n \"size\": \"2.2 GB\",\n \"uploaded\": \"2020-10-01\",\n \"uploader\": \"YTS\",\n \"category\": \"Movies\",\n \"seeders\": 2145,\n \"leechers\": 198,\n \"source\": \"yts\"\n },\n {\n \"title\": \"Interstellar.2014.1080p.BluRay.x264\",\n \"magnet\": \"magnet:?xt=urn:btih:...\",\n \"size\": \"3.1 GB\",\n \"uploaded\": \"2019-07-12\",\n \"uploader\": \"1337xUploader\",\n \"category\": \"Movies\",\n \"seeders\": 1200,\n \"leechers\": 230,\n \"source\": \"1337x\"\n },\n ...\n]\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package to fetch torrent metadata from multiple sources",
"version": "0.1.4",
"project_urls": {
"Documentation": "https://github.com/aayushkdev/torrfetch#readme",
"Homepage": "https://github.com/aayushkdev/torrfetch",
"Source": "https://github.com/aayushkdev/torrfetch",
"Tracker": "https://github.com/aayushkdev/torrfetch/issues"
},
"split_keywords": [
"torrent",
" scraper",
" metadata",
" torrent indexer",
" torrent scraper"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3e3576aafda752ae005cda9ff972ccdedb9d4042999e4cd37b2ffb6be0242085",
"md5": "dbb9f925db701e2d9c682eb4974ba95c",
"sha256": "0f7d0e377712ba668802990b4512d40dfc73e2a5a5db8cd125d4f9f7495783bf"
},
"downloads": -1,
"filename": "torrfetch-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dbb9f925db701e2d9c682eb4974ba95c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6789,
"upload_time": "2025-07-29T18:17:08",
"upload_time_iso_8601": "2025-07-29T18:17:08.729766Z",
"url": "https://files.pythonhosted.org/packages/3e/35/76aafda752ae005cda9ff972ccdedb9d4042999e4cd37b2ffb6be0242085/torrfetch-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bacc836b1ed9ecf73a6fc91abd4489f8488394bd538d5d80b5a79af207eebe87",
"md5": "19af91f960ad21cdab243c84615a617f",
"sha256": "0d0dfad41fd25c5cbf91845141678d6aa2f0c20d1b14c022f8a800f6e6d135a2"
},
"downloads": -1,
"filename": "torrfetch-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "19af91f960ad21cdab243c84615a617f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6476,
"upload_time": "2025-07-29T18:17:10",
"upload_time_iso_8601": "2025-07-29T18:17:10.453926Z",
"url": "https://files.pythonhosted.org/packages/ba/cc/836b1ed9ecf73a6fc91abd4489f8488394bd538d5d80b5a79af207eebe87/torrfetch-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 18:17:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aayushkdev",
"github_project": "torrfetch#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "torrfetch"
}
JSON
