torf Reference

class torf.Torrent(path=None, name=None, exclude_globs=(), exclude_regexs=(), include_globs=(), include_regexs=(), trackers=None, webseeds=None, httpseeds=None, private=None, comment=None, source=None, creation_date=None, created_by='torf 3.1.3', piece_size=None, randomize_infohash=False)

Torrent metainfo representation

Create a new Torrent instance:

>>> from torf import Torrent
>>> torrent = Torrent('path/to/My Torrent',
...                   trackers=['https://localhost:123/announce'],
...                   comment='This is my first torrent. Be gentle.')

Convenient access to metainfo via properties:

>>> torrent.comment
'This is my first torrent. Be gentle.'
>>> torrent.comment = "This is my first torrent. Let's rock!"
>>> torrent.private = True

Full control over unencoded metainfo:

>>> torrent.metainfo['info']['private']
True
>>> torrent.metainfo['more stuff'] = {'foo': 12,
...                                   'bar': ('x', 'y', 'z')}

Hash pieces and update progress once per second:

>>> def cb(torrent, filepath, pieces_done, pieces_total):
...     print(f'{pieces_done/pieces_total*100:3.0f} % done')
>>> success = torrent.generate(callback=cb, interval=1)
  1 % done
  2 % done
  [...]
100 % done

Write torrent file:

>>> torrent.write('my_torrent.torrent')

Create magnet link:

>>> torrent.magnet()
'magnet:?xt=urn:btih:e167b1fbb42ea72f051f4f50432703308efb8fd1&dn=My+Torrent&xl=142631&tr=https%3A%2F%2Flocalhost%3A123%2Fannounce'

Read torrent from file:

>>> t = Torrent.read('my_torrent.torrent')
>>> t.comment
"This is my first torrent. Let's rock!"
>>> t.metainfo['info']['more stuff']
{'bar': ['x', 'y', 'z'], 'foo': 12}
metainfo

Unencoded torrent metainfo as mutable mapping

You can put anything in here as long as keys are convertable to bytes and values are convertable to bytes, int, list or dict.

See also convert() and validate().

The info key is guaranteed to exist.

path

File system path to torrent content

Files are filtered according to exclude_globs, exclude_regexs, include_globs and include_regexs.

Setting or manipulating this property updates metainfo['info']:

  • name, piece length and files or length are set.
  • pieces and md5sum are removed if they exist.
Raises:ReadError – if path or any path underneath it is not readable
files

List of relative paths in this torrent

Paths are File objects and items are automatically deduplicated. Every path starts with name.

Setting or manipulating this property updates metainfo['info']:

  • name, piece length and files or length are set.
  • pieces and md5sum are removed if they exist.

See filepaths for a list of file system paths.

Raises:
  • PathError – if any path is absolute
  • CommonPathError – if not all files share a common parent directory
  • ValueError – if any file is not a File object
filepaths

List of paths of existing files in path included in the torrent

Paths are Filepath objects and items are automatically deduplicated. Directories are resolved into a list of files.

Setting or manipulating this property updates metainfo['info']:

  • name, piece length and files or length are set.
  • pieces and md5sum are removed if they exist.
Raises:ReadError – if any file path is not readable
exclude_globs

List of case-insensitive wildcard patterns to exclude

Include patterns take precedence over exclude patterns to allow including files that match an exclude pattern.

Patterns are matched against paths in files.

include_globs

List of case-insensitive wildcard patterns to include

See exclude_globs.

exclude_regexs

List of regular expression patterns to exclude

Include patterns take precedence over exclude patterns to allow including files that match an exclude pattern.

Patterns are matched against paths in files.

Raises:re.error – if any regular expression is invalid
include_regexs

List of regular expression patterns to include

See exclude_regexs.

filetree

files as a dictionary tree

Parent nodes are dictionaries and leaf nodes are File objects. The top node is always a dictionary with the single key name.

Example:

{'Torrent': {'bar': {'baz.mp3': File('Torrent/bar/baz.mp3',
                                     size=543210),
                     'baz.pdf': File('Torrent/bar/baz.pdf',
                                     size=999)},
             'foo.txt': File('Torrent/foo.txt',
                             size=123456)}}
name

Name of the torrent

Default to last item in path or None if path is None.

If this property is set to None and path is not None, it is set to the default.

Setting this property sets or removes name in metainfo['info'].

mode

singlefile if this torrent contains one file that is not in a directory, multifile if it contains one or more files in a directory, or None if no content is specified (i.e. files is empty).

size

Total size of content in bytes

partial_size(path)

Return size of one or more files as specified in metainfo

Parameters:path (str, path-like or iterable) – Relative path within torrent, starting with name; may point to file or directory
Raises:PathError – if path is not known
piece_size

Length of each piece in bytes

If set to None and size is larger than 0, use the return value of calculate_piece_size.

Setting this property sets or removes piece length in metainfo['info'].

classmethod calculate_piece_size(size)

Return the piece size for a total torrent size of size bytes

For torrents up to 1 GiB, the maximum number of pieces is 1024 which means the maximum piece size is 1 MiB. With increasing torrent size both the number of pieces and the maximum piece size are gradually increased up to 10,240 pieces of 8 MiB. For torrents larger than 80 GiB the piece size is piece_size_max with as many pieces as necessary.

It is safe to override this method to implement a custom algorithm.

Returns:calculated piece size
piece_size_min = 16384

Smallest allowed piece size

Setting piece_size to a smaller value raises PieceSizeError.

piece_size_max = 16777216

Greatest allowed piece size

Setting piece_size to a greater value raises PieceSizeError.

pieces

Number of pieces the content is split into

hashes

Tuple of SHA1 piece hashes as bytes

trackers

List of tiers (lists) of announce URLs

http://bittorrent.org/beps/bep_0012.html

This is a smart list that ensures the proper list-of-lists structure, validation and deduplication. You can set this property to a URL, an iterable of URLs or an iterable of iterables of URLs (i.e. “tiers”).

This property automatically sets metainfo['announce'] and metainfo['announce-list'] when it is manipulated or set according to these rules:

  • If it contains a single URL, metainfo['announce'] is set and metainfo['announce-list'] is removed if it exists.
  • If it contains an iterable of URLs, metainfo['announce'] is set to the first URL and metainfo['announce-list'] is set to a list of tiers, one tier for each URL.
  • If it contains an iterable of iterables of URLs, metainfo['announce'] is set to the first URL of the first iterable and metainfo['announce-list'] is set to a list of tiers, one tier for each iterable of URLs.
Raises:
  • URLError – if any of the announce URLs is invalid
  • ValueError – if set to anything that isn’t an iterable or a string
webseeds

List of webseed URLs

http://bittorrent.org/beps/bep_0019.html

The list returned by this property automatically updates metainfo['url-list'] when manipulated. Setting this property sets metainfo['url-list'].

Raises:
  • URLError – if any URL is invalid
  • ValueError – if set to anything that isn’t an iterable or a string
httpseeds

List of webseed URLs

http://bittorrent.org/beps/bep_0017.html

The list returned by this property automatically updates metainfo['httpseeds'] when manipulated. Setting this property sets metainfo['httpseeds'].

Raises:
  • URLError – if any URL is invalid
  • ValueError – if set to anything that isn’t an iterable or a string
private

Whether torrent should use trackers exclusively for peer discovery

True or False if metainfo['info']['private'] exists, None otherwise.

comment

Comment string or None for no comment

Setting this property sets or removes metainfo['comment'].

creation_date

datetime.datetime instance or None for no creation date

int and float are also allowed and converted with datetime.datetime.fromtimestamp().

Setting this property sets or removes metainfo['creation date'].

created_by

Application name or None for no creator

Setting this property sets or removes metainfo['created by'].

source

Source string or None for no source

Setting this property sets or removes metainfo['info']['created by'].

infohash

SHA1 info hash

Raises:MetainfoError – if validate fails or metainfo is not bencodable
infohash_base32

Base 32 encoded SHA1 info hash

randomize_infohash

Whether to ensure that infohash is always unique

This allows for cross-seeding without changing piece_size.

Setting this property to True sets metainfo['info']['entropy'] to a random integer. Setting it to False removes that field.

is_ready

Whether this torrent is ready to be exported to a file or magnet link

generate(threads=None, callback=None, interval=0)

Hash pieces and report progress to callback

This method sets metainfo['info']['pieces'] after all pieces are hashed successfully.

Parameters:
  • threads (int) – How many threads to use for hashing pieces or None to use one thread per available CPU core
  • callback (callable) –

    Callable to report progress and/or abort

    callback must accept 4 positional arguments:

    1. Torrent instance (Torrent)
    2. Path of the currently hashed file (str)
    3. Number of hashed pieces (int)
    4. Total number of pieces (int)

    If callback returns anything that is not None, hashing is stopped.

  • interval (float) – Minimum number of seconds between calls to callback; if 0, callback is called once per hashed piece
Raises:
  • PathError – if path contains only empty files/directories
  • ReadError – if path or any file beneath it is not readable
  • RuntimeError – if path is None
Returns:

True if all pieces were successfully hashed, False otherwise

verify_filesize(path, callback=None)

Check if path looks like it should contain all the data of this torrent

Walk through files and check if each file exists relative to path, is readable and has the correct size. Excess files in path are ignored.

This is fast and should find most manipulations, but verify() is necessary to detect corruptions (e.g. due to bit rot).

Parameters:
  • path (str) – Directory or file to check
  • callback (callable) –

    Callable to report progress and/or abort

    callback must accept 6 positional arguments:

    1. Torrent instance (Torrent)
    2. File path in file system (str)
    3. File path in torrent (str)
    4. Number of checked files (int)
    5. Total number of files (int)
    6. Exception (TorfError) or None

    If callback returns anything that is not None, verification is stopped.

If a callback is specified, exceptions are not raised but passed to callback instead.

Raises:
Returns:

True if path is verified successfully, False otherwise

verify(path, skip_on_error=True, threads=None, callback=None, interval=0)

Check if path contains all the data specified in this torrent

Generate hashes from the contents of files and compare them to the ones stored in metainfo['info']['pieces'].

Parameters:
  • path (str) – Directory or file to check
  • skip_on_error (bool) – Whether to stop hashing pieces from file if a piece from it is corrupt
  • threads (int) – How many threads to use for hashing pieces or None to use one thread per available CPU core
  • callback (callable) –

    Callable to report progress and/or abort

    callback must accept 7 positional arguments:

    1. Torrent instance (Torrent)
    2. File path in file system (str)
    3. Number of checked pieces (int)
    4. Total number of pieces (int)
    5. Index of the current piece (int)
    6. SHA1 hash of the current piece or None (bytes)
    7. Exception (TorfError) or None

    If callback returns anything that is not None, verification is stopped.

  • interval (float) – Minimum number of seconds between calls to callback (if 0, callback is called once per piece); this is ignored if an error is found

If a callback is specified, exceptions are not raised but passed to callback instead.

Raises:
Returns:

True if path is verified successfully, False otherwise

validate()

Check if all mandatory keys exist in metainfo and all standard keys have correct types

References:
Raises:MetainfoError – if metainfo would not generate a valid torrent file or magnet link
convert()

Return metainfo with all keys encoded to bytes and all values encoded to bytes, int, list or OrderedDict

Raises:MetainfoError – if a value cannot be converted properly
dump(validate=True)

Create bencoded metainfo (i.e. the content of a torrent file)

Parameters:validate (bool) – Whether to run validate() first
Returns:metainfo as bencoded bytes
write_stream(stream, validate=True)

Write metainfo to a file-like object

Parameters:
  • stream – Writable file-like object (e.g. io.BytesIO)
  • validate (bool) – Whether to run validate() first
Raises:
write(filepath, validate=True, overwrite=False)

Write metainfo to torrent file

Parameters:
  • filepath – Path of the torrent file
  • validate (bool) – Whether to run validate() first
  • overwrite (bool) – Whether to silently overwrite filepath (only after all pieces were hashed successfully)
Raises:
magnet(name=True, size=True, trackers=True, tracker=False)

Magnet instance

Parameters:
  • name (bool) – Whether to include the name
  • size (bool) – Whether to include the size
  • trackers (bool) – Whether to include all trackers
  • tracker (bool) – Whether to include only the first tracker of the first tier (overrides trackers)
Raises:

MetainfoError – if metainfo is invalid

classmethod read_stream(stream, validate=True)

Read torrent metainfo from file-like object

Parameters:
  • stream – Readable file-like object (e.g. io.BytesIO)
  • validate (bool) –

    Whether to run validate() on the new Torrent instance

    NOTE: If the “info” field is not a dictionary,
    MetainfoError is raised even if validate is set to False
Raises:
  • ReadError – if reading from stream fails
  • BdecodeError – if stream does not produce a valid bencoded byte sequence
  • MetainfoError – if validate is True and the read metainfo is invalid
Returns:

New Torrent instance

classmethod read(filepath, validate=True)

Read torrent metainfo from file

Parameters:
  • filepath – Path of the torrent file
  • validate (bool) – Whether to run validate() on the new Torrent instance
Raises:
  • ReadError – if reading from filepath fails
  • BdecodeError – if filepath does not contain a valid bencoded byte sequence
  • MetainfoError – if validate is True and the read metainfo is invalid
Returns:

New Torrent instance

copy()

Create a new Torrent instance with the same metainfo

class torf.Magnet(xt, *, dn=None, xl=None, tr=None, xs=None, as_=None, ws=None, kt=None, **kwargs)

BTIH Magnet URI

Parameters:
  • xt (str) – eXact Topic: Info hash (Base 16 or 32)
  • dn (str) – Display Name: Name of the torrent
  • xl (int) – eXact Length: Size in bytes
  • tr (list) – TRacker: Iterable of tracker URLs
  • xs (str) – eXact Source: Torrent file URL
  • as_ (str) – Acceptable Source: Fallback torrent file URL
  • ws (list) – WebSeeds: Iterable of webseed URLs (see BEP19)
  • kt (list) – Keyword Topic: List of search keywords

All keyword arguments that start with x_ go into the x dictionary with the part after the underscore as the key. They appear as “x.<name>” in the rendered URI.

References:
dn

Display Name: Name of the torrent or None

xt

eXact Topic: URN containing the info hash as base 16 or base 32

Example:

For convenience, this property may be set to the info hash without the urn:btih part.

Raises:MagnetError – if set to an invalid value
infohash

Info hash as base 16 or base 32

Raises:MagnetError – if set to an invalid value
xl

eXact Length: Size in bytes or None

Raises:MagnetError – if set to an invalid value
tr

TRackers: List of tracker URLs, single tracker URL or None

Raises:URLError – if any of the URLs is invalid
xs

eXact Source: Torrent file URL or None

Raises:URLError – if the URL is invalid
as_

Acceptable Source: Fallback torrent file URL or None

(The trailing underscore is needed because “as” is a keyword in Python.)

Raises:URLError – if the URL is invalid
ws

WebSeeds: List of webseed URLs, single webseed URL or None

See BEP19.

Raises:URLError – if any of the URLs is invalid
kt

Keyword Topic: List of search keywords or None

x

Mapping of custom keys to their values

For example, “x.pe” (a peer address) would be accessed as magnet.x['pe'].

torrent()

Torrent instance

get_info(validate=True, timeout=60, callback=None)

Download the torrent’s “info” section

Try the following sources in this order: xs, as, tr

torrent() can only return a complete torrent if this method is called first.

Parameters:
  • validate – Whether to ensure the downloaded “info” section is valid
  • timeout (int, float) – Give up after this many seconds
  • callable (callback) – Callable that is called with a TorfError instance if a source is specified but fails
Returns:

True if the “info” section was successfully downloaded, False otherwise

classmethod from_string(uri)

Create Magnet URI from string

Raises:
class torf.File(path, size)

Path-like that only accepts relative paths and also stores the file size

class torf.Filepath

Path-like that makes relative paths equal to their absolute versions

exception torf.TorfError(msg, *posargs, **kwargs)

Base exception for all exceptions raised by torf

exception torf.URLError(url)

Invalid URL

url

The invalid URL

exception torf.PieceSizeError(size, min=None, max=None)

Invalid piece size

size

The invalid piece size

min

Smallest allowed piece size or None

max

Largest allowed piece size or None

exception torf.MetainfoError(msg)

Invalid torrent metainfo

exception torf.BdecodeError(filepath=None)

Failed to decode bencoded byte sequence

filepath

Path of the offending torrent file or None

exception torf.MagnetError(uri, reason=None)

Invalid magnet URI or value

uri

The invalid URI

reason

Why URI is invalid

exception torf.PathError(path, msg)

General invalid or unexpected path

path

Path of the offending file or directory

exception torf.CommonPathError(filepaths)

Files don’t share parent directory

filepaths

Paths to offending files

exception torf.VerifyNotDirectoryError(path)

Expected file but found directory

path

Path of the offending directory

exception torf.VerifyIsDirectoryError(path)

Expected (link to) directory, but found something else

path

Path of the offending non-directory

exception torf.VerifyFileSizeError(filepath, actual_size, expected_size)

Unexpected file size

filepath

Path of the offending file

actual_size

Size as reported by the file system

expected_size

Size as specified in the metainfo

exception torf.VerifyContentError(piece_index, piece_size, file_sizes)

On-disk data does not match hashes in metainfo

piece_index

Index of the corrupt piece in the stream of concatenated files

piece_size

Size of the corrupt piece in bytes

files

Potentially corrupt files

exception torf.ReadError(errno, path=None)

Unreadable file or stream

path

Path of the offending file or None

errno

POSIX error number from errno.h

exception torf.WriteError(errno, path=None)

Unwritable file or stream

path

Path of the offending file or None

errno

POSIX error number from errno.h