or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

bencoding.mdindex.mdtorrent-operations.mdutilities.md
tile.json

tessl/pypi-torrentool

A Python library for creating, reading, and modifying torrent files with bencoding utilities and CLI tools.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/torrentool@1.2.x

To install, run

npx @tessl/cli install tessl/pypi-torrentool@1.2.0

index.mddocs/

Torrentool

A comprehensive Python library for working with torrent files and bencoding. Torrentool enables developers to create, read, and modify torrent files programmatically, supporting operations like setting tracker URLs, calculating file hashes, and generating magnet links. It also includes bencoding utilities for encoding and decoding BitTorrent data structures and a command-line interface for creating torrents from files or directories.

Package Information

  • Package Name: torrentool
  • Language: Python
  • Installation: pip install torrentool
  • CLI Installation: pip install torrentool[cli] (includes Click dependency)

Core Imports

from torrentool.api import Torrent, Bencode

Individual imports:

from torrentool.torrent import Torrent, TorrentFile
from torrentool.bencode import Bencode
from torrentool.utils import upload_to_cache_server, get_open_trackers_from_local, get_open_trackers_from_remote, get_app_version, humanize_filesize

Basic Usage

from torrentool.api import Torrent

# Create a torrent from a file or directory
new_torrent = Torrent.create_from('/path/to/file_or_directory')
new_torrent.announce_urls = ['udp://tracker.example.com:80/announce']
new_torrent.comment = 'My awesome torrent'
new_torrent.to_file('my_torrent.torrent')

# Read and modify an existing torrent
existing_torrent = Torrent.from_file('existing.torrent')
print(f"Name: {existing_torrent.name}")
print(f"Size: {existing_torrent.total_size} bytes")
print(f"Hash: {existing_torrent.info_hash}")
print(f"Magnet: {existing_torrent.magnet_link}")

# Modify properties
existing_torrent.comment = 'Updated comment'
existing_torrent.webseeds = ['http://webseed.example.com/files/']
existing_torrent.to_file()  # Save changes back to original file

# Get magnet link with specific details
magnet = existing_torrent.get_magnet(detailed=['tr', 'ws'])  # Include trackers and webseeds

Architecture

The library is organized around several key components:

  • Torrent class: Main interface for creating, reading, and modifying torrent files
  • Bencode utilities: Low-level encoding/decoding of bencoded data structures
  • CLI tools: Command-line interface for common torrent operations
  • Utility functions: Helper functions for tracker management and file uploads

Capabilities

Torrent File Operations

Core functionality for creating, reading, and modifying torrent files. Handles all torrent metadata including file lists, tracker URLs, creation dates, and hash calculations.

class Torrent:
    def __init__(self, dict_struct: dict = None): ...
    
    @classmethod
    def create_from(cls, src_path: Union[str, Path]) -> 'Torrent': ...
    
    @classmethod
    def from_file(cls, filepath: Union[str, Path]) -> 'Torrent': ...
    
    @classmethod
    def from_string(cls, string: str) -> 'Torrent': ...
    
    def to_file(self, filepath: str = None): ...
    def to_string(self) -> bytes: ...
    def get_magnet(self, detailed: Union[bool, list, tuple, set] = True) -> str: ...

Torrent Operations

Bencoding Utilities

Encoding and decoding functionality for bencoded data structures used in BitTorrent protocol. Supports all bencode data types including strings, integers, lists, and dictionaries.

class Bencode:
    @classmethod
    def encode(cls, value: TypeEncodable) -> bytes: ...
    
    @classmethod
    def decode(cls, encoded: bytes, *, byte_keys: Set[str] = None) -> TypeEncodable: ...
    
    @classmethod
    def read_string(cls, string: Union[str, bytes], *, byte_keys: Set[str] = None) -> TypeEncodable: ...
    
    @classmethod
    def read_file(cls, filepath: Union[str, Path], *, byte_keys: Set[str] = None) -> TypeEncodable: ...

Bencoding

Utility Functions

Helper functions for tracker management, file size formatting, and torrent caching services. Includes both local and remote tracker list management.

def get_app_version() -> str: ...
def humanize_filesize(bytes_size: int) -> str: ...
def upload_to_cache_server(fpath: str) -> str: ...
def get_open_trackers_from_remote() -> List[str]: ...
def get_open_trackers_from_local() -> List[str]: ...

Utilities

Command Line Interface

Command-line tools for creating torrents and displaying torrent information. Requires Click package installation with pip install torrentool[cli].

# Create torrent from file or directory
torrentool torrent create /path/to/source [OPTIONS]

# Display torrent information
torrentool torrent info /path/to/file.torrent

Available options for create command:

  • --dest: Destination directory for .torrent file
  • --tracker: Comma-separated tracker URLs
  • --open_trackers: Add public tracker URLs automatically
  • --comment: Add comment to torrent
  • --cache: Upload to torrent cache service

Types

from typing import Union, List, Optional, Set, Tuple, NamedTuple
from pathlib import Path
from datetime import datetime

class TorrentFile(NamedTuple):
    """Represents a file in torrent."""
    name: str
    length: int

TypeEncodable = Union[str, int, list, set, tuple, dict, bytes, bytearray]

Exceptions

class TorrentoolException(Exception):
    """Base torrentool exception."""

class BencodeError(TorrentoolException):
    """Base exception for bencode related errors."""

class BencodeDecodingError(BencodeError):
    """Raised when unable to decode bencoded data."""

class BencodeEncodingError(BencodeError):
    """Raised when unable to encode data into bencode."""

class TorrentError(TorrentoolException):
    """Base exception for Torrent object related errors."""

class RemoteUploadError(TorrentoolException):
    """Upload to remote services failed."""

class RemoteDownloadError(TorrentoolException):
    """Download from remote services failed."""