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 4.2.6', piece_size=None, piece_size_min=None, piece_size_max=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['more stuff']
{'bar': ['x', 'y', 'z'], 'foo': 12}
property 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.

property 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

property location

path without name or None if path is None

property 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

property 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

property 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.

Wildcard

Description

*

matches everything

?

matches any single character

[SEQ]

matches any character in SEQ

[!SEQ]

matches any char not in SEQ

property include_globs

List of case-insensitive wildcard patterns to include

See exclude_globs.

property 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

property include_regexs

List of regular expression patterns to include

See exclude_regexs.

property 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)}}
property 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'].

property 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).

property 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

property 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. If set to None and size is smaller than 1, remove metainfo['info']['piece length'] .

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

property piece_size_min

Smallest allowed piece size

Setting this property also sets piece_size to the same value if it is smaller.

property piece_size_max

Largest allowed piece size

Setting this property also sets piece_size to the same value if it is bigger.

piece_size_min_default = 16384

Smallest allowed piece size (default value)

Setting piece_size to a smaller value raises PieceSizeError.

piece_size_max_default = 16777216

Greatest allowed piece size (default value)

Setting piece_size to a greater value raises PieceSizeError.

classmethod calculate_piece_size(size, min_size=None, max_size=None)

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

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

Parameters:
Returns:

calculated piece size

property pieces

Number of pieces the content is split into

property hashes

Tuple of SHA1 piece hashes as bytes

property 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

property 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

property 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

property private

Whether torrent should use trackers exclusively for peer discovery

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

property comment

Comment string or None for no comment

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

property 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'].

property created_by

Application name or None for no creator

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

property source

Source string or None for no source

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

property infohash

SHA1 info hash

Raises:

MetainfoError – if validate fails or metainfo is not bencodable

property infohash_base32

Base 32 encoded SHA1 info hash

property 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.

property 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(path, threads=None, callback=None, interval=0)

Check if path contains all the data specified in this torrent

Generate hashes from file content and compare them to the ones stored in metainfo['info']['pieces'].

Parameters:
  • path (str) – Directory or file to read from

  • 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 (bytes or None)

    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

verify_filesize(path, callback=None)

Check if path has the expected file size

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

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

reuse(path, callback=None, interval=0)

Copy pieces and piece length from existing torrent

If path is a directory, it is searched recursively for a matching .torrent file. Otherwise, it is read() as a .torrent file.

path may also be an iterable, in which case each item is treated as described above until a match is found.

A matching torrent is found by searching for a torrent with the same name and files (file size must also match). If a match is found, compare three piece hashes per file to reduce the risk of a false positive.

Warning

This should almost always work in practice, but a false positive match is theoretically possible, and there is no way to avoid that.

Note

This will likely change infohash and turn this instance into a new torrent.

Parameters:
  • path – Path to torrent file or directory or iterable of file/directory paths

  • callback (callable) –

    Callable to report progress and/or abort

    callback must accept 6 positional arguments:

    1. Torrent instance (Torrent)

    2. Torrent file path (str) or None

    3. Number of checked torrent files (int)

    4. Total number of torrent files (int)

    5. Status indicator:

      False - File name or size does not match

      True - File name and size matches

      None - Hashing file and comparing piece hashes

    6. Exception (TorfError) or None

    If callback returns anything that is not None, stop searching.

  • interval (float) – Minimum number of seconds between calls to callback; if 0, callback is called for each torrent file; callback is always called if exception is not None

Raises:
  • ReadError – if reading a torrent file fails

  • BdecodeError – if parsing a torrent file fails

  • MetainfoError – if a torrent file contains invalid or insufficient metadata

Returns:

True if a matching torrent was found, False otherwise

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:
property dn

Display Name: Name of the torrent or None

property 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

property infohash

Info hash as base 16 or base 32

Raises:

MagnetError – if set to an invalid value

property xl

eXact Length: Size in bytes or None

Raises:

MagnetError – if set to an invalid value

property tr

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

Raises:

URLError – if any of the URLs is invalid

property xs

eXact Source: Torrent file URL or None

Raises:

URLError – if the URL is invalid

property 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

property ws

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

See BEP19.

Raises:

URLError – if any of the URLs is invalid

property kt

Keyword Topic: List of search keywords or None

property 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 also stores the file size

class torf.Filepath(*args, **kwargs)

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

class torf.TorrentFileStream(torrent, content_path=None)

Traverse concatenated files as they are described in a torrent

Parameters:

torrentTorrent object

Files are opened on demand and kept open for re-use. It is recommended to make use of the context manager protocol to make sure they are properly closed when no longer needed.

Example:

>>> torrent = torf.Torrent(...)
>>> with TorrentFileStream(torrent) as tfs:
>>>     # Get the 29th piece of the concatenated file stream
>>>     piece = tfs.get_piece(29)
close()

Close all opened files

This is called automatically when the instance is used as a context manager.

property max_piece_index

Largest valid piece index (smallest is always 0)

get_file_position(file)

Return index of first byte of file in stream of concatenated files

Parameters:

fileFile object

Raises:

ValueError – if file is not specified in the torrent

get_file_at_position(position, content_path=None)

Return file that belongs to the byte at position in stream of concatenated files

Parameters:
  • position – Byte index in the stream; minimum is 0, maximum is the torrent’s size minus 1

  • content_path – Path to file or directory (defaults to class argument of the same name, path or the file path from the torrent)

get_piece_indexes_of_file(file, exclusive=False)

Return indexes of pieces that contain at least one byte of file

Parameters:
  • exclusive (bool) – Whether to include only indexes of pieces that don’t contain bytes of any other files, i.e. only return piece indexes that belong to file exlusively

  • fileFile object

get_files_at_byte_range(first_byte_index, last_byte_index, content_path=None)

Return list of files that have at least one byte at first_byte_index, last_byte_index or between those two in the stream of concatenated files

Parameters:

content_path – Path to file or directory (defaults to class argument of the same name, path or the file path from the torrent)

get_byte_range_of_file(file)

Return index of first and last byte in the stream of concatenated files that contains at least one byte of file

get_files_at_piece_index(piece_index, content_path=None)

Return list of files that have 1 or more bytes in piece at piece_index

Parameters:
  • piece_index – Index of the piece; minimum is 0, maximum is the torrent’s number of pieces minus 1

  • content_path – Path to file or directory (defaults to class argument of the same name, path or the file path from the torrent)

get_absolute_piece_indexes(file, relative_piece_indexes)

Return list of validated absolute piece indexes

Parameters:
  • fileFile object

  • relative_piece_indexes – Sequence of piece indexes within file; negative values address pieces at the end of file, e.g. [0, 12, -1, -2]

Example:

>>> # Assume `file` starts in the 50th piece in the stream of
>>> # concatenated files and is 100 pieces long. `1000` and `-1000` are
>>> # ignored because they are out of bounds.
>>> tfs.get_absolute_piece_indexes(file, (0, 1, 70, 75, 1000, -1000, -3, -2, -1))
[50, 51, 120, 125, 147, 148, 149]
get_relative_piece_indexes(file, relative_piece_indexes)

Return list of validated relative piece indexes

Parameters:
  • fileFile object

  • relative_piece_indexes – Sequence of piece indexes within file; negative values address pieces at the end of file, e.g. [0, 12, -1, -2]

Example:

>>> # Assume `file` starts in the 50th piece in the stream of
>>> # concatenated files and is 100 pieces long. `1000` and `-1000` are
>>> # ignored because they are out of bounds.
>>> tfs.get_absolute_piece_indexes(file, (0, 1, 70, 75, 1000, -1000, -3, -2, -1))
[0, 1, 70, 75, 97, 98, 99]
get_piece(piece_index, content_path=None)

Return piece at piece_index or None for nonexisting file(s)

Parameters:
  • piece_index – Index of the piece; minimum is 0, maximum is the torrent’s number of pieces minus 1

  • content_path – Path to file or directory to read piece from (defaults to class argument of the same name or path)

Raises:
iter_pieces(content_path=None, oom_callback=None)

Iterate over (piece, filepath, (exception1, exception2, …))

Each piece consists of piece_size bytes, except for the final piece in the stream of concatenated files, which may be shorter.

Filepaths are generated from content_path and the relative file paths from the torrent.

Exceptions are TorfError subclasses.

If a file is not readable, pieces are None for each missing piece. This usually includes the last piece of the previous file and the first piece of the next file unless the unreadable file starts/ends right on a piece boundary.

You can wrap this iterator in enumerate() to get the piece index for each piece:

>>> for piece_index, (piece, filepath, exceptions) in stream.iter_pieces():
>>>     ...
Parameters:
  • content_path – Path to file or directory to read pieces from (defaults to class argument of the same name or path)

  • oom_callback

    Callable that gets MemoryError instance

    Between calls to oom_callback, the piece that caused the exception is read again and again until it fits into memory. This callback offers a way to free more memory. If it fails, it is up to the callback to raise the exception or deal with it in some other way.

    If this is None, MemoryError is raised normally.

Raises:
get_piece_hash(piece_index, content_path=None)

Read piece at piece_index from file(s) and return its SHA1 hash

Parameters:
  • piece_index – Index of the piece; minimum is 0, maximum is the torrent’s number of pieces minus 1

  • content_path – Path to file or directory to read piece from (defaults to class argument of the same name or path)

Raises:
Returns:

bytes

verify_piece(piece_index, content_path=None)

Generate SHA1 hash for piece at piece_index and compare to the expected hash in the torrent

Parameters:
  • piece_index – Index of the piece; minimum is 0, maximum is the torrent’s number of pieces minus 1

  • content_path – Path to file or directory to read piece from (defaults to class argument of the same name or path)

Raises:
Returns:

result of the hash comparision (bool) or None if a file at piece_index does not exist

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

Base exception for all exceptions raised by torf

exception torf.URLError(url)

Invalid URL

property url

The invalid URL

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

Invalid piece size

property size

The invalid piece size

property min

Smallest allowed piece size or None

property 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

property filepath

Path of the offending torrent file or None

exception torf.MagnetError(uri, reason=None)

Invalid magnet URI or value

property uri

The invalid URI

property reason

Why URI is invalid

exception torf.PathError(path, msg)

General invalid or unexpected path

property path

Path of the offending file or directory

exception torf.CommonPathError(filepaths)

Files don’t share parent directory

property filepaths

Paths to offending files

exception torf.VerifyNotDirectoryError(path)

Expected (link to) directory, but found something else

property path

Path of the offending non-directory

exception torf.VerifyIsDirectoryError(path)

Expected file but found directory

property path

Path of the offending directory

exception torf.VerifyFileSizeError(filepath, actual_size, expected_size)

Unexpected file size

property filepath

Path of the offending file

property actual_size

Size as reported by the file system

property expected_size

Size as specified in the metainfo

exception torf.VerifyContentError(filepath, piece_index, piece_size, file_sizes)

On-disk data does not match hashes in metainfo

property filepath

Path to file that caused the piece corruption

property piece_index

Index of the corrupt piece in the stream of concatenated files

property piece_size

Size of the corrupt piece in bytes

property files

Potentially corrupt neighboring files

exception torf.ReadError(errno, path=None)

Unreadable file or stream

property path

Path of the offending file or None

property errno

POSIX error number from errno.h

exception torf.WriteError(errno, path=None)

Unwritable file or stream

property path

Path of the offending file or None

property errno

POSIX error number from errno.h