Working With `Torrent` Object

Introduction to torrents

A torrent can be identified using a .torrent file, a magnet link, or an info hash. A .torrent file contains the metainfo needed to validate downloaded content, while an info hash identifies that metainfo. When starting with only an info hash, the client must retrieve the metainfo from a peer that supports ut_metadata.

Creating a Torrent object

The library creates torrents from a .torrent file, a TorrentMetaInfo object, an info hash, or a magnet link.

From a magnet link

from torrentlib import Torrent

torrent = Torrent.from_magnet(
    "magnet:?xt=urn:btih:0123456789abcdef0123456789abcdef01234567"
    "&dn=Example%20File"
    "&xl=1234"
    "&tr=udp%3A%2F%2Ftracker.example%3A6881%2Fannounce"
    "&x.pe=192.0.2.1%3A6881"
)

The method also accepts runtime state:

from torrentlib import TorrentStatus

torrent = Torrent.from_magnet(
    magnet_uri,
    downloaded=1024,
    uploaded=256,
    event=TorrentStatus.STARTED,
)

Supported magnet parameters

Parameter	Meaning	Result
xt	Exact topic	A urn:btih topic becomes torrent.info_hash.
dn	Display name	Becomes the initial torrent.name hint.
xl	Exact length in bytes	Becomes torrent.total_size.
tr	Tracker URL	Repeated values populate announce and announce-list.
x.pe	Peer endpoint	Repeated values populate torrent.peers or torrent.peers6.

The BTIH value in xt may use either a 40-character hexadecimal hash or a 32-character Base32 hash. Both forms are normalized to lowercase hexadecimal.

x.pe accepts IPv4 addresses and hostnames in host:port form. IPv6 addresses should use bracketed form, such as [2001:db8::1]:6881. Ports must be between 1 and 65535. Invalid peer hints are ignored because they are optional discovery hints; their original values remain available in the parsed parameters.

The created torrent contains only the hints supplied by the magnet URI. It does not contain full torrent metainfo until metadata is retrieved from a peer.

Accessing the magnet parser directly

Use MagnetParser to inspect a magnet URI without constructing a Torrent:

from torrentlib.MagnetParser import MagnetParser

magnet = MagnetParser.parse(magnet_uri)

print(magnet.info_hash)
print(magnet.display_name)
print(magnet.exact_length)
print(magnet.trackers)
print(magnet.peer_endpoints)

MagnetParser.parse() returns an immutable Magnet value object. Parameters without specialized behavior, such as ws, xs, as, kt, and so, are preserved in magnet.parameters:

web_seeds = magnet.parameters.get("ws", ())

Magnet validation

The parser raises ValueError when:

• the URI does not use the magnet scheme;
• no valid urn:btih exact topic is present;
• xl is not a non-negative integer.

Passing a value other than a string raises TypeError.

From a torrent file

from torrentlib import Torrent

torrent = Torrent.from_file("example.torrent")

From a TorrentMetaInfo object

from torrentlib import Torrent, TorrentMetaInfo

metainfo = TorrentMetaInfo.from_file("example.torrent")
torrent = Torrent.from_metainfo(metainfo)

From an info hash

Create a minimal Torrent when you only have an info hash:

from torrentlib import Torrent

torrent = Torrent(
    info_hash="1234567890abcdef1234567890abcdef12345678"
)

With explicit runtime state

from torrentlib import Torrent, TorrentStatus

torrent = Torrent(
    info_hash="1234567890abcdef1234567890abcdef12345678",
    total_size=1145141919810,
    left=1145141919810,
    downloaded=0,
    uploaded=0,
    event=TorrentStatus.STOPPED,
    name="example_file.iso",
    piece_length=None,
    num_pieces=None,
)

Retrieving information from a Torrent object

print(torrent)
print(torrent.name)
print(torrent.info_hash)
print(torrent.total_size)
print(torrent.piece_length)
print(torrent.num_pieces)
print(torrent.has_metainfo)
print(torrent.metadata)  # Bencoded info dictionary, or None.

files = torrent.get_files_info()  # Returns None until metadata is available.
if files:
    for file_hash, file_info in files.items():
        print(file_hash, file_info["name"], file_info["length"])

        same_file = torrent.get_file_by_hash(file_hash)
        print(same_file)

Updating runtime state

from torrentlib import TorrentStatus

torrent.update_downloaded(1024)
torrent.update_uploaded(512)
torrent.set_event(TorrentStatus.COMPLETED)

Notes

• Torrent owns runtime swarm state such as downloaded, uploaded, left, event, and peer caches.
• TorrentStatus provides COMPLETED, STARTED, and STOPPED.
• Torrent.update_from_metadata() verifies that received metadata matches the original info hash.