Skip to main content

High-level Python 3 module for creating and parsing torrent files

Project description

torf is a Python (>=3.6) module for creating, parsing and editing .torrent files. It started as a fork of dotorrent but turned into a rewrite with more features like full access to the torrent’s metainfo, magnet link generation, validation and more.


torf is available on PyPI.

The latest development version is in the master branch on Github.




Create a new torrent object:

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

Convenient access to metainfo via properties:

>>> torrent.comment
'This is my first torrent. Be gentle.'
>>> torrent.private = True

Full control over unencoded metainfo:

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

Start hashing and update progress once per second:

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

Write torrent file:

>>> with open('my_torrent.torrent', 'wb') as f:
...    torrent.write(f)

Generate magnet link:

>>> torrent.magnet()

Read torrent:

>>> with open('my_torrent.torrent', 'rb') as f:
...    t =
>>> t.comment
'This is my first torrent. Be gentle.'

Methods defined here:

__init__(self, path=None, exclude=(), trackers=(), webseeds=(), httpseeds=(),
         private=False, comment=None, creation_date=None, created_by=None,
         source=None, piece_size=None, include_md5=False)
    Initialize self.

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

    Raise MetainfoError on values that cannot be converted properly.

dump(self, validate=True)
    Return `metainfo` as validated, bencoded byte string

    validate: Whether to run validate() first

generate(self, callback=None, interval=0)
    Set 'pieces' in 'info' dictionary of `metainfo`

    callback: Callable with signature (filename, pieces_completed,
              pieces_total); if `callable` returns anything that is not
              None, hashing is canceled
    interval: Number of seconds between calls to `callback`

    Raise PathEmptyError if `path` contains no data.

    Return True if 'pieces' was successfully added to `metainfo`.
    Return False if `callback` canceled the operation.

magnet(self, name=True, size=True, trackers=True, tracker=False, validate=True)
    BTIH Magnet URI (generate() must run first)

    name: Whether to include the name
    size: Whether to include the size
    trackers: Whether to include all trackers
    tracker: Whether to include only the first tracker of the first tier
             (overrides `trackers`)
    validate: Whether to run validate() first

    Check if all mandatory keys exist in `metainfo` and are of expected types

    The necessary values are documented here:

    Note that 'announce' is not considered mandatory because of DHT.

    Raise MetainfoError if `metainfo` would not generate a valid torrent
    file or magnet link.

write(self, stream, validate=True)
    Write torrent metainfo to file object (generate() must run first)

    stream: A stream or file object (must be opened in 'wb' mode)
    validate: Whether to run validate() first

Class methods defined here:

read(stream, validate=True) from builtins.type
    Read torrent metainfo from file object

    stream: A stream or file object (must be opened in 'rb' mode)
    validate: Whether to run validate() on the Torrent object

    Raise MetainfoParseError if metainfo is not a valid bencoded byte

    Return a new Torrent object.

Data descriptors defined here:

    Comment string or None

    Setting this property sets or removes 'comment' in `metainfo`.

    Application name or None

    Setting this property sets or removes 'created by' in `metainfo`.

    datetime object, int (as from time.time()) or None

    Setting this property sets or removes 'creation date' in `metainfo`.

    List of filename patterns to exclude:

        *      matches everything
        ?      matches any single character
        [seq]  matches any character in seq
        [!seq] matches any char not in seq

    Yield absolute paths to local files in `path`

    Yield relative paths to files specified in `metainfo`

    Paths include the torrent's name.

    Note that the paths may not exist. See `filepaths` for existing files.

    List of httpseed URLs or None

    Whether to include MD5 sums for each file

    This takes only effect when generate() is called.

    SHA1 info hash (generate() must run first)

    Base32 encoded SHA1 info hash (generate() must run first)

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

    'info' is guaranteed to exist.

    Torrent name

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

    Setting this property sets or removes 'name' in the 'info' dictionary of

    Path to torrent content or None

    Piece size/length or None to pick one automatically

    Setting this property sets 'piece length' in the 'info' dictionary in

    Getting this property if it hasn't been set calculates 'piece length' so
    that there are approximately 1500 pieces in total. The result is stored
    in `metainfo`.

    Whether torrent should use trackers exclusively for peer discovery

    Setting this property sets or removes 'private' in the 'info' dictionary
    of `metainfo`.

    Whether to ensure that `infohash` is always different

    This allows cross-seeding without changing `piece_size` manually.

    Setting this property to True sets 'entropy' in the 'info' dictionary of
    `metainfo` to a random integer. Setting it to False removes it if

    Total size of content in bytes

    If the 'info' dictionary in `metainfo` doesn't have 'length' or 'files'
    set, return None instead.

    Source string or None

    Setting this property sets or removes 'source' in `metainfo`.

    List of tiers of announce URLs or None

    A tier is either a single announce URL (string) or a list (any iterable)
    of announce URLs.

    Setting this property sets or removes 'announce' and 'announce-list' in
    `metainfo`. 'announce' is set to the first tracker of the first tier.

    List of webseed URLs or None

Data and other attributes defined here:

MAX_PIECE_SIZE = 67108864


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for torf, version 1.0rc1
Filename, size File type Python version Upload date Hashes
Filename, size torf-1.0rc1.tar.gz (14.7 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page