The TorBox functions module handles all interactions with the TorBox API, including fetching downloads, searching metadata, and downloading file content.
Enums
DownloadType
class DownloadType(Enum):
torrent = "torrents"
usenet = "usenet"
webdl = "webdl"
IDType
class IDType(Enum):
torrents = "torrent_id"
usenet = "usenet_id"
webdl = "web_id"
Download management
getUserDownloads
def getUserDownloads(type: DownloadType)
The type of downloads to fetch (torrents, usenet, or webdl).
A tuple containing:
files (list | None): List of processed file dictionaries, or None on errorsuccess (bool): Whether the operation succeededdetail (str): Success or error message
- Fetches downloads from TorBox API with pagination (1000 items per page)
- Filters for cached items only
- Processes video files in parallel using multiple threads
- Enriches each file with metadata (title, year, media type, images)
- Stores processed files in the database
File filtering:
- Only processes files with MIME type
video/x-matroska (MKV) or video/mp4 (MP4)
- Skips non-cached items
Example:
from functions.torboxFunctions import getUserDownloads, DownloadType
files, success, detail = getUserDownloads(DownloadType.torrent)
if success:
print(f"Retrieved {len(files)} torrent files")
for file in files:
print(f"{file['metadata_title']} - {file['file_size']} bytes")
else:
print(f"Error: {detail}")
process_file
def process_file(item, file, type)
getUserDownloads.
The download item from the TorBox API.
The file object within the download item.
A processed file dictionary with metadata, or None if the file should be skipped.
{
"item_id": int,
"type": str,
"folder_name": str,
"folder_hash": str,
"file_id": int,
"file_name": str,
"file_size": int,
"file_mimetype": str,
"path": str,
"download_link": str,
"extension": str,
"metadata_title": str,
"metadata_link": str,
"metadata_mediatype": str, # "movie" or "series"
"metadata_image": str,
"metadata_backdrop": str,
"metadata_years": int,
"metadata_season": int, # for series only
"metadata_episode": int, # for series only
"metadata_filename": str,
"metadata_foldername": str, # for series only
"metadata_rootfoldername": str,
}
def searchMetadata(query: str, title_data: dict, file_name: str, full_title: str, hash: str, item_name: str)
The search query (usually the parsed title from the filename).
Parsed title data from PTN (parse-torrent-name) containing season, episode, year, etc.
The full title including folder name and filename for better matching.
The hash of the torrent/download item for logging.
The name of the parent download item.
A tuple containing:
metadata (dict): Dictionary of metadata fieldssuccess (bool): Whether metadata was founddetail (str): Success or error message
{
"metadata_title": str, # Cleaned title
"metadata_link": str, # Link to media info
"metadata_mediatype": str, # "movie", "series", or "anime"
"metadata_image": str, # Poster image URL
"metadata_backdrop": str, # Backdrop image URL
"metadata_years": int, # Release year
"metadata_season": int, # Season number (series only)
"metadata_episode": int, # Episode number (series only)
"metadata_filename": str, # Formatted filename
"metadata_foldername": str, # Season folder name (series only)
"metadata_rootfoldername": str, # Root folder name
}
import PTN
from functions.torboxFunctions import searchMetadata
file_name = "The.Matrix.1999.1080p.BluRay.mkv"
title_data = PTN.parse(file_name)
metadata, success, detail = searchMetadata(
query=title_data.get("title"),
title_data=title_data,
file_name=file_name,
full_title=file_name,
hash="abc123",
item_name="The Matrix Collection"
)
if success:
print(f"Title: {metadata['metadata_title']}")
print(f"Year: {metadata['metadata_years']}")
print(f"Type: {metadata['metadata_mediatype']}")
File download functions
getDownloadLink
def getDownloadLink(url: str)
The TorBox API URL that redirects to the actual file.
The resolved download URL, or the original URL if no redirect occurs.
from functions.torboxFunctions import getDownloadLink
api_url = "https://api.torbox.app/v1/api/torrents/requestdl?token=...&torrent_id=123&file_id=456&redirect=true"
actual_url = getDownloadLink(api_url)
print(f"Actual download URL: {actual_url}")
downloadFile
def downloadFile(url: str, size: int, offset: int = 0)
The number of bytes to download.
The starting byte offset.
The downloaded file content.
- Raises
Exception if the response status code is not 200 (OK) or 206 (Partial Content)
Example:
from functions.torboxFunctions import downloadFile, getDownloadLink
api_url = "https://api.torbox.app/v1/api/torrents/requestdl?..."
download_url = getDownloadLink(api_url)
# Download first 1MB
data = downloadFile(download_url, size=1024*1024, offset=0)
print(f"Downloaded {len(data)} bytes")
# Download next 1MB
data = downloadFile(download_url, size=1024*1024, offset=1024*1024)
print(f"Downloaded {len(data)} bytes")
Constants
ACCEPTABLE_MIME_TYPES
ACCEPTABLE_MIME_TYPES = [
"video/x-matroska",
"video/mp4",
]