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:
DelugeWebClientTimeoutError – If the request times out.
DelugeWebClientConnectionError – If the Web UI cannot be reached.
DelugeWebClientDecodeError – If the response is not a JSON object.
DelugeWebClientHTTPError – If the Web UI returns a non-2xx status.
DelugeWebClientRPCError – If Deluge reports a JSON-RPC error and handle_error is True.
- 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:
DelugeWebClientConnectionError – If there is no Deluge Web UI reachable at the configured URL.
DelugeWebClientTimeoutError – If the request times out.
DelugeWebClientError – On any other Deluge or HTTP failure.
- 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¶
-
HEADERS: