Client¶

Client for ruTorrent.

xirvik.client.LOG_NAME: Final[str] = 'xirvik.rutorrent'¶: Name used in logger.

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.

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.

add_torrent_uri¶: HTTP URI to POST torrents to.

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.

auth¶: Basic authentication credentials.

datadir_action_uri¶: HTTP datadir/action.php URI for the host.

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.

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

Prepare to get a torrent file given a hash.

Returns:: requests.Request object and the file name string.
Return type:: tuple

http_prefix¶: HTTP URI for the host.

list_all_files() → Iterator[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.

list_files(hash_: str) → Iterator[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:

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

Parameters:: hash_ (str) – Hash of the torrent.

list_torrents() → Iterator[TorrentInfo]¶: Get all torrent information.

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.

multirpc_action_uri¶: HTTP multirpc/action.php URI for the host.

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 requests exception.

Parameters:: hash_ (str) – Hash of the torrent.

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.

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')

stop(hash_: str) → None¶

Stop a torrent by hash.

Returns if successful. Can raise a requests exception.

Parameters:: hash_ (str) – Hash of the torrent.

Utilities¶

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.

Typing utilities¶

Typing helpers.

class xirvik.typing.FileDownloadStrategy(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Single file download strategy.

LEADING_CHUNK_FIRST = 1¶

NORMAL = 0¶: Also known as ‘trailing chunk first’.

class xirvik.typing.FilePriority(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

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

DO_NOT_DOWNLOAD = 0¶

HIGH = 2¶

NORMAL = 1¶

class xirvik.typing.HashingState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

Hashing state of the torrent.

FIRST_HASH_CHECK = 1¶

HASHING = 2¶

NOT_HASHING = 0¶

REHASHING = 3¶

class xirvik.typing.State(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶

State of the torrent.

STARTED_OR_PAUSED = 1¶

STOPPED = 0¶

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

Client¶

Utilities¶

Typing utilities¶

xirvik-tools

Navigation

Related Topics