Client¶

Client for ruTorrent.

exception xirvik.client.UnexpectedruTorrentError¶

Raised when an unexpected error occurs.

class xirvik.client.ruTorrentClient(host: str, name: str | None = None, password: str | None = None, max_retries: int = 10, netrc_path: str | Path | None = None, backoff_factor: int = 1)¶

ruTorrent client class.

Reference on RPC returned fields.

Parameters:¶

host : str¶

Hostname with no protocol.

name : str | None¶

Username.

If no name and no password are passed, ~/.netrc will be searched with the host provided. The path can be overridden with the netrc_path argument.

password : str | None¶

Password.

max_retries : int¶

Number of tries to retry any request.

netrc_path : str | None¶

netrc file path.

backoff_factor : int¶

Factor used to calculate back-off time when retrying requests.

Raises:¶

ValueError – If no netrc entry is found for the host, or if username or password is not provided.

async aclose() → None¶

Close the underlying HTTP session and release resources.

async add_torrent(filepath: str, *, start_now: bool = True) → None¶

Add a torrent. Use start_now=False to start paused.

Parameters:¶

filepath : str¶

File path to the torrent file.

start_now : bool¶

If the torrent should start immediately.

property add_torrent_uri : str¶

HTTP URI to POST torrents to.

async add_torrent_url(url: str) → None¶

Add a torrent via URI.

Parameters:¶

url : str¶

URI to the torrent file. Must be available either under the current credentials or public.

property auth : tuple[str, str]¶

Basic authentication credentials.

property datadir_action_uri : str¶

HTTP datadir/action.php URI for the host.

async delete(hash_: str) → None¶

Delete a torrent and its files by hash.

Use the remove() method to remove the torrent but keep the data.

Returns if successful. Faults are converted to xmlrpc.Fault exceptions.

Parameters:¶

hash_ : str¶

Hash of the torrent.

async edit_torrents(hashes: Iterable[str], *, comment: str | None = None, private: bool | None = None, trackers: Iterable[str] | None = None) → niquests.Response¶

Edit torrent properties.

Parameters:¶

hashes : Iterable[str]¶

List of torrent hashes to edit.

comment : str | None¶

Comment to set.

private : bool | None¶

Value for the private flag.

trackers : Iterable[str] | None¶

Tracker URLs.

Returns:¶

The response object.

Return type:¶

niquests.Response

async get_torrent(hash_: str) → tuple[Response, str]¶

Prepare to get a torrent file given a hash.

Parameters:¶

hash_ : str¶

Hash of the torrent.

Returns:¶

Response object and the file name string.

Return type:¶

tuple[niquests.Response, str]

host¶

Hostname with no protocol.

property http_prefix : str¶

HTTP URI for the host.

async list_all_files() → AsyncIterator[TorrentTrackedFile]¶

List all files tracked by rTorrent.

If there are thousands of torrents, this may take well over 10 minutes.

Returns a generator of tracked files.

Yields:¶

TorrentTrackedFile – Named tuple with file information.

async list_files(hash_: str) → AsyncIterator[TorrentTrackedFile]¶

List files for a given torrent hash.

Returns a generator of named tuples with fields (in this order): - name - total number of pieces - number of pieces downloaded - size in bytes - priority - download strategy

Example use:

async for name, pieces, pieces_dl, size, priority, dl_strategy in client.list_files():

Parameters:¶

hash_ : str¶

Hash of the torrent.

Yields:¶

TorrentTrackedFile – Named tuple with file information.

async list_torrents() → AsyncIterator[TorrentInfo]¶

Get all torrent information.

Yields:¶

TorrentInfo – Information about each torrent.

Raises:¶

ListTorrentsError – If the response is not as expected.

async move_torrent(torrent_hash: str, target_dir: str, *, fast_resume: bool = True) → None¶

Move a torrent’s files to somewhere else on the server.

Parameters:¶

torrent_hash : str¶

Hash of the torrent.

target_dir : str¶

Must be a valid and usable directory.

fast_resume : bool¶

Use fast resumption.

Raises:¶

UnexpectedruTorrentError – If the server returns errors in the response.

property multirpc_action_uri : str¶

HTTP multirpc/action.php URI for the host.

name¶

Username for authentication.

password¶

Password for authentication.

async remove(hash_: str) → None¶

Remove a torrent from the client but keep the data.

Use the delete() method to remove and delete the torrent data.

Returns if successful. Can raise a HTTPError exception.

Parameters:¶

hash_ : str¶

Hash of the torrent.

async set_label(label: str, torrent_hash: str) → None¶

Set a label to a torrent.

Parameters:¶

label : str¶

Label to use.

torrent_hash : str¶

Hash of the torrent.

async set_label_to_hashes(**kwargs: Any) → None¶

Set a label to a list of info hashes. The label can be a new label.

To remove a label, pass an empty string as the label keyword argument.

Example use:

client.set_labels(hashes=[hash_1, hash_2],
                  label='my new label')

Parameters:¶

**kwargs : Any¶

Expected keys: hashes (list of hash strings), label (str), and optionally allow_recursive_fix (bool), recursion_limit (int), recursion_attempt (int).

Raises:¶

TypeError – If the hashes or label keyword arguments are not passed.

async stop(hash_: str) → None¶

Stop a torrent by hash.

Returns if successful. Can raise a HTTPError exception.

Parameters:¶

hash_ : str¶

Hash of the torrent.

Utilities¶

Utility functions.

xirvik.utils.parse_header(line: str) → tuple[str, dict[str, str]]¶

Parse a Content-type like header.

Return the main content-type and a dictionary of options.

Parameters:¶

line : str¶

The header line to parse.

Returns:¶

A tuple of the main content-type and a dictionary of options.

Return type:¶

tuple[str, dict[str, str]]

Typing utilities¶

Typing helpers.

class xirvik.typing.FileDownloadStrategy(*values)¶

Single file download strategy.

NORMAL = 0¶

Also known as ‘trailing chunk first’.

class xirvik.typing.FilePriority(*values)¶

Single file priority.

These are based on ruTorrent’s code, not rTorrent’s.

class xirvik.typing.HashingState(*values)¶

Hashing state of the torrent.

class xirvik.typing.State(*values)¶

State of the torrent.

class xirvik.typing.TorrentInfo(hash: str, is_open: bool, is_hash_checking: bool, is_hash_checked: bool, state: State, name: str, size_bytes: int, completed_chunks: int, size_chunks: int, bytes_done: int, up_total: int, ratio: float, up_rate: int, down_rate: int, chunk_size: int, custom1: str, peers_accounted: int, peers_not_connected: int, peers_connected: int, peers_complete: int, left_bytes: int, priority: int, state_changed: datetime | None, skip_total: int, hashing: HashingState, chunks_hashed: int, base_path: str, creation_date: datetime | None, tracker_focus: int, is_active: bool, message: str, custom2: str, free_diskspace: int, is_private: bool, is_multi_file: bool, finished: datetime | None)¶

Torrent information.

base_path : str¶

Path before the torrent directory or file.

bytes_done : int¶

Alias for field number 9

chunk_size : int¶

Chunk size (usually a power of 2).

chunks_hashed : int¶

Alias for field number 25

completed_chunks : int¶

Alias for field number 7

creation_date : datetime | None¶

Date torrent was added to the client. Can be None if this was not captured, or possibly due to a crash.

custom1 : str¶

Usually contains the assigned label.

custom2 : str¶

Alias for field number 31

down_rate : int¶

Alias for field number 13

finished : datetime | None¶

Alias for field number 35

free_diskspace : int¶

Alias for field number 32

hash : str¶

Alias for field number 0

hashing : HashingState¶

Alias for field number 24

is_active : bool¶

Alias for field number 29

is_hash_checked : bool¶

Alias for field number 3

is_hash_checking : bool¶

Alias for field number 2

is_multi_file : bool¶

Alias for field number 34

is_open : bool¶

Alias for field number 1

is_private : bool¶

Alias for field number 33

left_bytes : int¶

Alias for field number 20

message : str¶

Message from the server.

name : str¶

Alias for field number 5

peers_accounted : int¶

Alias for field number 16

peers_complete : int¶

Alias for field number 19

peers_connected : int¶

Alias for field number 18

peers_not_connected : int¶

Alias for field number 17

priority : int¶

Alias for field number 21

ratio : float¶

Alias for field number 11

size_bytes : int¶

Alias for field number 6

size_chunks : int¶

Alias for field number 8

skip_total : int¶

Alias for field number 23

state : State¶

Alias for field number 4

state_changed : datetime | None¶

Alias for field number 22

tracker_focus : int¶

Alias for field number 28

up_rate : int¶

Alias for field number 12

up_total : int¶

Alias for field number 10

class xirvik.typing.TorrentTrackedFile(name: str, number_of_pieces: int, downloaded_pieces: int, size_bytes: int, priority_id: FilePriority, download_strategy_id: FileDownloadStrategy)¶

Contains information about a single file within a torrent.

download_strategy_id : FileDownloadStrategy¶

Download strategy.

downloaded_pieces : int¶

Alias for field number 2

name : str¶

File name without path.

number_of_pieces : int¶

Alias for field number 1

priority_id : FilePriority¶

Download priority.

size_bytes : int¶

Alias for field number 3