Client

class DelugeWebClient(url, password, daemon_port=58846) → None

Bases: object

HEADERS: ClassVar[dict[str, str]] = {'Accept': 'application/json', 'Content-Type': 'application/json'}
add_host(username, password, timeout=30) → Response

Add a host to the host list.

A successful payload contains a boolean and the host ID. Otherwise, the payload contains an error message.

Example output:

new_host = Response(
    result=[True, "f3558dd405924807a0c5e5a057f7a496"],
    error=None,
)

Example usage:

new_host = client.add_host("test", "test")
if new_host.result:
    host_id = new_host.result[1]
Return type:

Response

add_label(label, timeout=30) → Response

Adds a label to the client, ignoring labels if they already exist.

Return type:

Response

add_torrent_magnet(uri, torrent_options, timeout=30) → Response

Adds a torrent from a magnet link.

Parameters:
  • uri (str) – Magnet input.

  • torrent_options (TorrentOptions) – Torrent options.

  • timeout (int) – Time to timeout.

Returns:

Response object.

Return type:

Response

Raises:

DelugeWebClientError – On failures (except duplicate torrents, which are returned as a successful result).

add_torrent_url(url, torrent_options, timeout=30) → Response

Adds a torrent from a URL.

Parameters:
  • url (str) – URL input.

  • torrent_options (TorrentOptions) – Torrent options.

  • timeout (int) – Time to timeout.

Returns:

Response object.

Return type:

Response

Raises:

DelugeWebClientError – On failures (except duplicate torrents, which are returned as a successful result).

check_connected(timeout=30) → Response

Use the web.connected method to get a boolean response if the Web UI is connected to a deluged host.

Return type:

Response

close_session() → None

Closes the DelugeWebClient session. This is handled automatically when DelugeWebClient is used in a context manager.

Return type:

None

connect_to_host(host_id, timeout=30) → Response

To connect to deluged with <hostID>.

Return type:

Response

daemon_port
disconnect(timeout=30) → Response

Disconnects from the Web UI.

This disconnects the Web UI session from its currently connected daemon.

Return type:

Response

edit_host(host_id, username, password, timeout=30) → Response

Edit a host in the hostlist.

This is used to set or update the username/password that the Web UI will use when connecting to a deluged daemon.

result will return True if successful.

Return type:

Response

execute_call(payload, handle_error=True, timeout=30) → Response

Helper method to execute most calls to the Web UI as needed.

Parameters:
  • payload (dict) – Payload object to be called.

  • handle_error (bool, optional) – Handle errors here or allow the caller to handle the error. Defaults to True.

  • timeout (int) – Time to timeout.

Returns:

Response object for each call.

Return type:

Response

Raises:
find_host_id_by_name(host_name, timeout=30) → Response

Find a host ID by its name.

Return type:

Response

Example output:
host_id = client.find_host_id_by_name("localclient")
if host_id.result:
    print(f"Found host ID: {host_id.result}")
get_free_space(path=None, timeout=30) → Response

Gets free space.

Return type:

Response

get_host_status(host_id, timeout=30) → Response

Get the deluged host status <hostID>.

Return type:

Response

get_hosts(timeout=30) → Response

Returns hosts we’re connected to currently.

Return type:

Response

Example output:
Response(
    result=[["host_hash", "127.0.0.1", 58846, "localclient"]],
    error=None,
)
get_labels(timeout=30) → Response

Gets defined labels.

Return type:

Response

get_libtorrent_version(timeout=30) → Response

Gets libtorrent version.

Return type:

Response

get_listen_port(timeout=30) → Response

Gets listen port.

Return type:

Response

get_path_size(path=None, timeout=30) → Response

Gets path size.

Returns the size of the file or folder path and -1 if the path is unaccessible (non-existent or insufficient privs)

Return type:

Response

get_plugins(timeout=30) → Response

Gets plugins.

Return type:

Response

get_torrent_files(torrent_id, timeout=30) → Response

Gets the files for a torrent in tree format.

Return type:

Response

get_torrent_status(torrent_id, keys=None, diff=False, timeout=30) → Response

Gets the status for a torrent.

Parameters:
  • torrent_id (str) – Torrent hash of for a single torrent.

  • keys (list[str]) – List of specific torrent’s property keys to fetch.

  • diff (bool) – Whether to return the status difference.

  • timeout (int) – Time to timeout for the call.

Returns:

The response from the API call.

Return type:

Response

get_torrents_status(filter_dict=None, keys=None, diff=False, timeout=30) → Response

Gets the status for multiple torrents, returns all torrents, optionally filtered by filter_dict.

Parameters:
  • filter_dict (dict) – Filtering criteria for torrents.

  • keys (list[str]) – List of specific torrents’ property keys to fetch.

  • diff (bool) – Whether to return the status difference.

  • timeout (int) – Time to timeout for the call.

Returns:

The response from the API call.

Return type:

Response

Example filter_dict: >>> {“id”: [“tid”, “tid”]} … or >>> state = str(TorrentState.SEEDING) >>> {“state”: state, “id”: [“tid”, “tid”]}

login(timeout=30) → Response

Log in to Web UI and connect to the first available host.

Parameters:

timeout (int) – Timeout for the login and connection attempts.

Returns:

A summary of the login and connection attempts.

Return type:

Response

Raises:
password
pause_torrent(torrent_id, timeout=30) → Response

Pause a specific torrent.

Return type:

Response

pause_torrents(torrent_ids, timeout=30) → Response

Pause a list of torrents.

Return type:

Response

remove_host(host_id, timeout=30) → Response

Remove a host from the host list.

If successful result will return True. Otherwise, will return False.

Return type:

Response

remove_torrent(torrent_id, remove_data=False, timeout=30) → Response

Removes a specific torrent.

Return type:

Response

remove_torrents(torrent_ids, remove_data=False, timeout=30) → Response

Removes a list of torrents.

Return type:

Response

resume_torrent(torrent_id, timeout=30) → Response

Resumes a specific torrent.

Return type:

Response

resume_torrents(torrent_ids, timeout=30) → Response

Resumes a list of torrents.

Return type:

Response

session
set_label(info_hash, label, timeout=30) → Response

Sets the label for a specific torrent.

Return type:

Response

set_torrent_trackers(torrent_id, trackers, timeout=30) → Response

Sets a torrents tracker list. Trackers will be [{'url', 'tier'}].

Return type:

Response

start_daemon(timeout=30) → Response

Start local daemon.

Response result and error will both be None if successfully started.

Return type:

Response

stop_daemon(host_id, timeout=30) → Response

Stop local daemon.

Response result and error will both be None if successfully stopped.

Return type:

Response

test_listen_port(timeout=30) → bool

Checks if the active port is open.

Returns:

If active port is opened or closed.

Return type:

bool

update_ui(keys=None, filter_dict=None, timeout=30) → Response

Gather information used to update the UI.

Return type:

Response

upload_torrent(torrent_path, torrent_options, timeout=30) → Response

Opens the torrent path building out the payload as needed to upload a single torrent to the client.

Parameters:
  • torrent_path (PathLike[str] | str | Path) – Path to a torrent file.

  • torrent_options (TorrentOptions) – Torrent options.

  • timeout (int) – Time to timeout.

Returns:

Response object.

Return type:

Response

Raises:
  • DelugeWebClientError – On upload failures (except duplicate torrents, which are returned as a successful result).

  • OSError – If torrent_path cannot be read. This is intentionally not wrapped in DelugeWebClientError.

upload_torrents(torrents, torrent_options, timeout=30) → dict[str, Response]

Uploads multiple torrents.

Parameters:
  • torrents (Iterable[PathLike[str] | str | Path]) – Iterable of torrent file paths.

  • torrent_options (TorrentOptions) – Torrent options. Avoid using name when uploading multiple torrents.

  • timeout (int) – Time to timeout.

Returns:

Responses keyed by torrent stem.

Return type:

dict[str, Response]

Raises:
  • DelugeWebClientError – On the first failed upload, aborting the batch. The specific subclass of the underlying failure is preserved.

  • OSError – If a torrent file cannot be read.

url