upsies.utils.torrent

Create torrent file

Module Attributes

upsies.utils.torrent.SKIP_SEARCHING = 'skip_searching'

Return value for the progress_callback to stop searching for a reusable torrent (see create())

Functions

upsies.utils.torrent.create(*, content_path, announce, source, torrent_path, exclude=(), use_cache=True, reuse_torrent_path=None, piece_size_calculator=None, piece_size_min_max_calculator=None, init_callback, progress_callback)

Generate and write torrent file

Parameters:

• content_path (str) – Path to the torrent’s payload

• announce (str) – Announce URL

• source (str) – Value of the source field in the torrent. This makes the torrent unique for each tracker to avoid cross-seeding issues, so it is usually the tracker’s abbreviated name.

• torrent_path (str) – Path of the generated torrent file

• exclude –

  Sequence of glob patterns (str) and re.Pattern (return value from re.compile()) or Regex objects

  Files beneath content_path are excluded from the torrent.

  Glob patterns are matched case-insensitively. For case-insensitive matching with regular expressions, use (?i:<pattern>).

• use_cache (bool) – Whether to get piece hashes from previously created torrents or from reuse_torrent_path

• reuse_torrent_path –

  Path to existing torrent file to get hashed pieces and piece size from. If the given torrent file doesn’t match the files in the torrent we want to create, hash the pieces normally.

  If this is a directory, search it recursively for *.torrent files and use the first one that matches.

  Non-existing or otherwise unreadable paths as well as falsy values (e.g. "" or None) are silently ignored.

  If this is a sequence, its items are expected to be directory or file paths and handled as described above.

• piece_size_calculator –

  Function that takes the torrent’s content size in bytes and returns the piece size

  If this is None, the default implementation is used.

• piece_size_min_max_calculator –

  Function that takes the torrent’s content size in bytes and returns the allowed minimum and maximum piece sizes or None to use the default minimum or maximum piece size

  If this is None, the default minimum and maximum piece sizes are used.

• init_callback – Callable that is called once before torrent generation commences with a Files object

• progress_callback – Callable that is called at regular intervals with a CreateTorrentProgress or FindTorrentProgress object as a positional argument

Callbacks can cancel the torrent creation by returning True or any other truthy value. If progress_callback returns SKIP_SEARCHING, the search for a reusable torrent is cancelled and pieces are hashed normally.

Raises:

TorrentCreateError – if anything goes wrong

Returns:

torrent_path or None if cancelled

Classes

class upsies.utils.torrent.CreateTorrentProgress(bytes_per_second, filepath, percent_done, piece_size, pieces_done, pieces_total, seconds_elapsed, seconds_remaining, seconds_total, time_finished, time_started, total_size)

Bases: CreateTorrentProgress

namedtuple() with these attributes:

• bytes_per_second (Bytes)

• filepath (str)

• percent_done (float)

• piece_size (Bytes)

• pieces_done (int)

• pieces_total (int)

• seconds_elapsed (timedelta)

• seconds_remaining (timedelta)

• seconds_total (timedelta)

• time_finished (datetime)

• time_started (datetime)

• total_size (Bytes)

class upsies.utils.torrent.Files(torrent)

Bases: object

Structured torrent file content

property list

Sequence of existing file paths (str)

property tree

Nested files

This is a tree where each node is a tuple in which the first item is the directory name and the second item is a sequence of (file_name, file_size) or (file_name, sub_tree) tuples.

Example:

('Parent',
    ('Foo', (
        ('Picture.jpg', 82489),
        ('Music.mp3', 5315672),
        ('More files', (
            ('This.txt', 57734),
            ('And that.txt', 184),
            ('Also some of this.txt', 88433),
        )),
    )),
    ('Bar', (
        ('Yee.mp4', 288489392),
        ('Yah.mkv', 3883247384),
    )),
)

property excluded

Sequence of file paths that exist but are not in the torrent for any reason

class upsies.utils.torrent.FindTorrentProgress(exception, filepath, files_done, files_per_second, files_total, percent_done, seconds_elapsed, seconds_remaining, seconds_total, status, time_finished, time_started)

Bases: CreateTorrentProgress

namedtuple() with these attributes:

• exception (TorrentCreateError or None)

• filepath (str)

• files_done (int)

• files_per_second (int)

• files_total (int)

• percent_done (float)

• seconds_elapsed (timedelta)

• seconds_remaining (timedelta)

• seconds_total (timedelta)

• status (hit, miss or verifying)

• time_finished (datetime)

• time_started (datetime)